CASAN/docs/plans/CASAN_APPLY_REALESTATE_MATCHING.md

CASAN APPLY — Runbook: Dự án BĐS "Match người mua ↔ bất động sản"

Mục đích: mô tả cụ thể một luồng/phiên làm việc áp dụng CASAN harness cho bài toán match người mua với BĐS phù hợp — chuẩn bị gì, môi trường ra sao, các bước nào, ai chịu trách nhiệm, gate ở đâu, xuất ra bằng chứng gì. Đối tượng đọc: Harness/Context Engineer, BA, môi giới (domain expert), pháp chế/DPO, lãnh đạo. Bối cảnh: BĐS là domain rủi ro cao (tiền lớn, PII tài chính, pháp lý, công bằng) → harness là điều kiện dùng được, không phải trang trí.

Trạng thái script: ✅ đã có trong harness · 🟡 có 1 phần · 📋 trong plan (chưa implement). Đánh dấu ngay tại chỗ dùng. Runbook này mô tả luồng; chưa phải lệnh chạy production.

---

0. Nguyên tắc bất di (đọc trước)

1. Match score của model là phần dễ. Giá trị nằm ở pipeline có gate: hard-filter → rank → verify → fairness → audit.
2. Ràng buộc cứng (ngân sách, pháp lý, eligibility, deal-breaker) nằm NGOÀI model — luật deterministic, model không được "linh hoạt" bỏ qua.
3. Delegation L1–L2: AI xếp hạng + giải thích + gợi ý; người quyết định cuối. Không tự chốt giao dịch.
4. PII tài chính không lên cloud model nếu chưa duyệt/consent.
5. Mọi gợi ý có evidence click được + audit ai-được-gợi-ý-gì-vì-sao.
6. Fairness: cấm match/loại theo thuộc tính được bảo vệ (dân tộc, tôn giáo, giới, tình trạng hôn nhân…).

---

PHẦN A — CHUẨN BỊ (trước phiên làm việc)

A1. Con người & vai trò (RACI)

Vai trò	Trách nhiệm chính
Product Owner / BA	Chốt mục tiêu match, success-criteria, KPI
Domain expert (môi giới trưởng)	Định nghĩa "phù hợp", deal-breaker, trọng số sở thích
Pháp chế / DPO	Duyệt fairness rules, PII policy, quy định sở hữu (vd người nước ngoài)
Harness Engineer	Dựng pipeline gate, cấu hình harness, loop policy
Context Engineer	Thiết kế context assembly + must-keep + nén
Validator (kiểm định)	Định nghĩa verify-gate H3, bộ test đối kháng
Approver (cấp quản lý)	Duyệt nới delegation / giao dịch giá trị lớn

A2. Dữ liệu & nguồn phải sẵn sàng

• Listing DB (BĐS): giá, vị trí, loại, diện tích, trạng thái pháp lý (sổ, tranh chấp), tiện ích, hướng/tầng, ROI, ngày bàn giao, trạng thái bán.
• CRM / hồ sơ người mua: ngân sách, mục đích, khu vực, must-have/deal-breaker, lịch sử tương tác.
• Tool bên ngoài: mortgage calculator (khả năng vay), legal-check API (sổ/tranh chấp), comparable-price API (giá so sánh).
• Chất lượng dữ liệu: mỗi nguồn có chủ sở hữu + độ tươi (freshness) — dữ liệu cũ → badge stale, không tô xanh.

A3. Chính sách phải CHỐT trước khi chạy (không vừa chạy vừa định)

Artifact	Nội dung	Ai duyệt
hard-constraints.yaml	Luật cứng: budget cap, eligibility pháp lý, deal-breaker → REJECT bất kể score	BA + Pháp chế
fairness-rules.yaml	Danh sách thuộc tính bảo vệ cấm dùng để match/loại	Pháp chế/DPO
data-classification.yaml ✅	Nhãn PII/confidential/internal/public (Plan-15)	DPO
loop-policy.yaml 📋	Budget: max_steps/tokens/thời gian; ngưỡng convergence (Plan-17)	Harness Eng
delegation.yaml	Mức L1–L2, action nào cần approval	Approver
success-criteria.yaml	"Match tốt" = gì (đo được), Top-N, ngưỡng chất lượng	PO/BA

---

PHẦN B — MÔI TRƯỜNG

B1. Tách 3 môi trường

• dev/pilot — dữ liệu giả lập/ẩn danh, model local, gate bật, không PII thật.
• staging — dữ liệu thật đã mask, chạy full gate + audit, chưa phục vụ khách.
• prod — dữ liệu thật, secure-by-default (mọi gate bật, opt-out phải audit).

B2. Model routing (quan trọng cho PII)

• PII/confidential (tài chính người mua) → model local (không rời hạ tầng).
• Cloud model chỉ cho dữ liệu public/internal hoặc khi có consent + approval.
• Enforce bằng harness-preflight.sh ✅ (check-cloud TRƯỚC model-call) + rai-guard.py check-cloud ✅.

B3. Cấu trúc thư mục dự án (mẫu)

realestate-match/
  config/
    hard-constraints.yaml
    fairness-rules.yaml
    data-classification.yaml       # ✅ mẫu có sẵn trong harness
    loop-policy.yaml               # 📋 Plan-17
    delegation.yaml
    success-criteria.yaml
  app/                             # logic dự án (hard-filter, rank, explain)
    hard_filter.py                 #   luật cứng — deterministic, NGOÀI model
    ranker.py                      #   gọi model qua model-router
    explainer.py                   #   trích thuộc tính thật → evidence
  harness/  ->  (dùng packages/casan-harness/scripts/bash của CASAN)
  artifacts/                       # output + audit + evidence (append-only)

B4. Verify môi trường trước phiên (pre-flight)

# (minh hoạ) kiểm tra harness + policy sẵn sàng
rai-guard.py model-card --check          # ✅ model có card/không pinned → chặn
security-check --selftest                # ✅ action-gate fail-closed
# đọc được policy? thiếu policy → deny-by-default (fail-closed)
test -f config/hard-constraints.yaml && test -f config/fairness-rules.yaml

---

PHẦN C — INPUT SCHEMA (cụ thể)

C1. Yêu cầu match (request)

{
  "request_id": "MATCH-2026-07-06-001",
  "mode": "buyer_to_properties",         // hoặc property_to_buyers
  "buyer_ref": "BUYER-8891",
  "top_n": 5,
  "delegation_level": "L2",
  "requested_by": "agent_id:human",
  "purpose": "own_use"                   // own_use | investment
}

C2. Người mua (buyer) — PII, ưu tiên model local

{
  "buyer_ref": "BUYER-8891",
  "budget": { "max_price": 5200000000, "loan_preapproved": 3000000000, "currency": "VND" },
  "location_pref": ["Q7", "Nhà Bè"],
  "property_type": ["apartment"],
  "size": { "min_bedrooms": 2, "min_area_m2": 65 },
  "must_have": ["so_hong", "ban_giao_truoc:2027-06"],
  "deal_breaker": ["tranh_chap_phap_ly", "khong_so"],
  "purpose": "own_use",
  "risk_appetite": "low",
  "timeline_months": 6
}

Không đưa thuộc tính bảo vệ (dân tộc/tôn giáo/giới…) vào tín hiệu match. Nếu có trong CRM → strip trước khi vào context.

C3. Bất động sản (property)

{
  "property_id": "PROP-4471",
  "price": 4900000000,
  "location": "Q7",
  "type": "apartment",
  "area_m2": 72, "bedrooms": 2,
  "legal_status": "so_hong",
  "dispute": false,
  "handover_date": "2026-12-01",
  "direction": "DongNam", "floor": 12,
  "rental_yield_pct": 4.8,
  "status": "available",
  "source_freshness": "2026-07-05T10:00:00Z"
}

---

PHẦN D — LUỒNG MỘT PHIÊN LÀM VIỆC (step-by-step)

Mỗi bước ghi: input → hành động (H nào) → output artifact → gate → ai chịu trách nhiệm.

flowchart TD
    S0["S0 Pre-flight<br/>classify PII + check-cloud"] --> S1["S1 Context assembly (H1)"]
    S1 --> S2["S2 Retrieve (H2)"]
    S2 --> S3["S3 Hard-filter<br/>(deterministic, NGOÀI model)"]
    S3 --> S4["S4 Rank (model, L1-L2)"]
    S4 --> S5["S5 Explain<br/>trích thuộc tính thật"]
    S5 --> G["S6 Verify-gate (H3)<br/>+ Fairness (H5)"]
    G -- fail --> S3
    G -- pass --> S7["S7 Loop control<br/>budget/convergence"]
    S7 --> S8["S8 Human review / approval"]
    S8 --> S9["S9 Present + Audit"]

S0 — Pre-flight (H4/RAI) ✅

• Input: buyer PII, request.
• Hành động: rai-guard.py classify gắn nhãn; harness-preflight.sh chặn PII→cloud nếu chưa duyệt → route model local.
• Output: artifacts/preflight.json (verdict + envelope provenance).
• Gate: PII lên cloud không consent → HALT.
• Ai: Harness Engineer (tự động).

S1 — Context assembly (H1) ✅ (nén)

• Hành động: gom buyer + catalog slice + market; context-compress.py --respect-policy nén nhưng must-keep = budget/legal/deal-breaker.
• Output: artifacts/context.json.
• Gate: must-keep bị rớt → FAIL (không cho qua).
• Ai: Context Engineer.

S2 — Retrieve (H2)

• Hành động: query listing DB + legal-check API + mortgage calculator (khả năng vay thực).
• Output: candidates_raw.json (kèm source_freshness).
• Gate: dữ liệu stale quá ngưỡng → badge stale, không tính là "verified".
• Ai: app (app/…) qua tool đã đăng ký (H2 allowlist).

S3 — Hard-filter (deterministic, NGOÀI model) ⭐

• Hành động: hard_filter.py loại ứng viên vi phạm hard-constraints.yaml: vượt budget/khả năng vay, sai eligibility pháp lý, dính deal-breaker, không sổ/tranh chấp.
• Output: candidates_eligible.json + rejected_with_reason.json.
• Gate: đây là luật cứng — model không được đụng vào.
• Ai: Harness/BA (luật do BA+Pháp chế chốt).

S4 — Rank (model, L1–L2)

• Hành động: ranker.py gọi model-router.sh ✅ chấm điểm khớp sở thích mềm (vị trí, hướng, tiện ích, ROI) trên tập đã eligible.
• Output: ranked.json (score + feature contributions).
• Gate: model chỉ xếp hạng, không thêm ứng viên ngoài eligible.
• Ai: Harness Engineer.

S5 — Explain (evidence)

• Hành động: explainer.py sinh lý do trích thuộc tính THẬT từ DB: "khớp vì budget ✔ (đã check vay), sổ hồng ✔, 3/4 must-have; loại PROP-X vì vượt budget".
• Output: explained.json (mỗi match ↔ evidence_ref tới bản ghi nguồn).
• Gate: giải thích chứa thuộc tính không có trong DB → FAIL (chống bịa).
• Ai: Validator kiểm mẫu.

S6 — Verify-gate (H3) + Fairness (H5) ⭐

• Hành động:
  • H3: re-check top-N vẫn thoả hard-constraints (double-check sau rank); faithfulness (evidence khớp nguồn).
  • H5 fairness: quét tín hiệu match — không dùng thuộc tính bảo vệ (fairness-rules.yaml); kiểm phân bố kết quả không lệch theo nhóm bảo vệ.
• Output: gate_verdict.json (PASS/FAIL + lý do).
• Gate: vi phạm → quay lại S3 / loại; fail-closed (gate lỗi = FAIL).
• Ai: Validator + (Pháp chế cho fairness).

S7 — Loop control (Plan-17) 📋

• Hành động: loop-governor.py giới hạn số vòng/tokens; loop-convergence.py dừng khi Top-N ổn định / phát hiện oscillation; ghi loop-trace.
• Output: loop_trace.json.
• Gate: vượt budget → HALT; kẹt → escalate. Người có loop-breaker.
• Ai: Harness Engineer.

S8 — Human review / approval (HITL)

• Hành động: môi giới xem Top-N + evidence; chỉnh/loại; giao dịch giá trị lớn → approval (control-plane-settings.py ✅, JWT thật + SoD 📋 sau Plan-16).
• Output: human_decision.json (ai duyệt/từ chối + lý do).
• Gate: L1–L2 → bắt buộc người quyết.
• Ai: Môi giới / Approver.

S9 — Present + Audit

• Hành động: trả Top-N cho người mua; ghi audit hash-chain (ai được gợi ý gì, vì sao, ai duyệt).
• Output: audit/… (append-only) + record cho governance-report.py ✅.
• Gate: thiếu audit → không được present (accountability).
• Ai: Harness (tự động).

---

PHẦN E — Delegation ladder (khi nào nâng L)

Mức	Cho phép	Điều kiện nâng
L1	AI nháp gợi ý, người duyệt toàn bộ	Khởi động — luôn bắt đầu ở đây
L2	AI xếp hạng + giải thích, người quyết chọn	Gate H3/H5 xanh ổn định + AgentOps đạt KPI
L3	Tự lọc/gợi ý rủi ro thấp trong scope hẹp (vd chỉ shortlist tự động)	Cần: Plan-16 (enforce), audit WORM (Plan-07 T2), fairness đo liên tục, approval cấp cao

Nâng L = security-sensitive → phải duyệt. Không tự nâng.

---

PHẦN F — Cái gì hiện cho lãnh đạo (Command Center §8.6 Plan-13) 📋

• Match quality (conversion, độ hài lòng) · Fairness = 0 vi phạm · PII zero-leak · audit đầy đủ · token→$ tiết kiệm.
• Click bất kỳ match → Evidence drawer: xem lý do + bản ghi nguồn + ai duyệt.
• Thông điệp: "vừa hiệu quả, vừa an toàn pháp lý — không tin thì bấm xem tận gốc."

---

PHẦN G — Checklist đi vào PRODUCTION

• hard-constraints.yaml + fairness-rules.yaml được Pháp chế/DPO ký.
• PII→cloud bị chặn (preflight test xanh); model local cho tài chính.
• Verify-gate H3 + fairness H5 fail-closed (test đối kháng xanh).
• Audit hash-chain bật; verify-chain phát hiện tamper.
• Plan-16 P0 đã vá (approval JWT thật, không bypass) — bắt buộc trước L2 thật.
• AgentOps đo bias + hallucination + cost, có ngưỡng cảnh báo.
• Loop budget/convergence (Plan-17) cấu hình — có loop-breaker.
• Delegation khoá ở L1–L2; nâng L cần approval.

---

PHẦN H — Ghi chú trung thực

• Chạy pilot L1–L2 được sớm: context/hard-filter/rank/explain + gate deterministic dùng script đã có (✅) + logic app dự án.
• Chưa "thật" cho tới khi: Plan-16 (fail-closed/approval thật), Plan-15 enforce (PII/RAI), Plan-07 T2 (audit WORM/KMS) — nếu không, rủi ro rò PII tài chính hoặc gợi ý phân biệt đối xử lọt lưới = rủi ro pháp lý + thương hiệu cho dự án BĐS.
• Script 📋 (loop-*, Command Center) thuộc Plan-17/Plan-13 — chưa implement; runbook mô tả cách chúng vào luồng để chuẩn bị trước.
• Ranh giới cứng: hard-filter (budget/pháp lý/deal-breaker) và fairness là luật ngoài model — tuyệt đối không giao cho model tự giác.

---

Liên quan: CASAN_PLAN_13_CONTROL_PLANE.md (§3.4 HITL, §8.6 Command Center) · CASAN_PLAN_15_RESPONSIBLE_AI_DATA_GOV.md (PII/RAI/model-card) · CASAN_PLAN_16_SECURITY_AUDIT_REMEDIATION.md (fail-closed/approval thật) · CASAN_PLAN_17_LOOP_ENGINEERING.md (budget/convergence/loop-trace) · CASAN_PLAN_10_TRACEABILITY_EVAL.md (H3 eval) · FPT_CASAN_Full.md (§4.3 Human-led, §4.4 delegation L0–L5).