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)
```bash
# (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)
```json
{
  "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
```json
{
  "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)
```json
{
  "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.**

```mermaid
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)._