@educa-corp/sdd-framework 0.2.4 → 0.2.6

package/core/commands/generate-code.md

@@ -443,6 +443,8 @@ Lệnh này giới hạn nghiêm ngặt trong **một file feature** được tr
 3. CLAUDE.md §architecture + §coding_standards
 4. **(chỉ FE/App)** Design Spec — nạp qua **Guard** bên dưới (gate approved/độ-tươi + sanity), là nguồn của màn hình, component inventory, và link Figma frame từng-màn.
 
+> **Phạm vi vét nguồn (SRC-CHAIN):** khi một giá trị còn thiếu ở nguồn chính, được phép đọc thêm các artifact **cùng feature-package** `{paths.specs_dir}/{domain}/{prd-slug}/` — PRD `{TICKET-ID}-{prd-slug}.md`, các `.feature` khác (system/web/app), design-spec, tech-doc anh em — cùng `core-entities.md`/`business-dictionary.md`. Đọc **theo nhu cầu** để phân giải giá trị trước khi hỏi người (xem §Quy tắc nguồn giá trị).
+
 ---
 
 ## Guard — BDD & Design Spec đã sẵn sàng chưa *(cảnh báo MỀM — đồng bộ generate-bdd)*
@@ -554,13 +556,25 @@ Phân giải design điều khiển adapter từ **tech-doc gộp của PRD** `{
 - **Mapping port→endpoint→DTO→error** (ưu tiên): §4.5.4 (API Integration Layer của platform này) — mỗi client method → endpoint có thật.
 - **Nguồn endpoint/shape**: §4.1 Endpoints + §4.2 Request-Response + §4.3 Error của cùng doc.
 
-Đọc `@trace.status` của doc. Nếu `draft` hoặc `in-review` → cảnh báo:
-```
-⚠ Tech design {TICKET-ID} (UC {UC-ID} / {platform}) đang {status}.
-  Contract / mapping adapter còn có thể đổi.
-  Tiếp tục — đảm bảo BE endpoint đã deploy hoặc confirm mapping thủ công.
-```
-Nếu doc **thiếu §4.5.4** (client integration chưa được vẽ cho platform này) → cảnh báo: "Chưa có §4.5.4 cho {platform} — fallback map trực tiếp từ §4.1 endpoint (mapping adapter được infer). Khuyến nghị: chạy `/generate-tech-docs {web|app .feature}` để bổ sung §4.5 trước."
+**Client contract gate — DS4** *(chỉ `--phase=integration`; KHÔNG áp dụng `--phase=ui` — UI vẫn degrade êm qua mock).* Đối xứng với DS3 của BE: soi §4.5.4 **đủ chưa** cho UC/platform này *trước khi* wire adapter thật.
+
+1. **Xác định phạm vi cần:** các client method mà UC NÀY dùng — lấy từ §10 (định vị scenario của UC) → §4.5.4 rows / interface `{UC-ID}ApiPort` của mock adapter (`--phase=ui`).
+2. **Kiểm tính đủ của §4.5.4 cho từng method:** có endpoint (resolve được ở §4.1) + map request + response→model + error→UI. *(Khác cảnh báo cũ: cái cũ chỉ bắt "thiếu HẲN §4.5.4"; DS4 bắt cả "thiếu MỘT PHẦN".)*
+3. **Phân loại (giống DS3):**
+   - **Đủ + `@trace.status: approved` + 0 🔴 blocker-GAP (§12) chạm §4.5.4/UC này** → dùng làm nguồn, KHÔNG hỏi.
+   - **`@trace.status` = `draft`/`in-review`, HOẶC §12 còn 🔴 blocker `open` chạm UC này** → WARN (không chặn): "contract/mapping adapter chưa chốt / còn {n} blocker-GAP open — đảm bảo BE endpoint đã deploy hoặc confirm mapping thủ công; có thể rework khi §4.5.4 đổi."
+   - **Thiếu §4.5.4, HOẶC khuyết một phần cho method UC cần** →
+     a. Áp **SRC-CHAIN** (xem §Quy tắc nguồn giá trị) lấp phần thiếu từ nguồn khác (§4.1–4.3, PRD, BDD `Then`, core-entities, mock adapter đã sinh).
+     b. Phần SRC-CHAIN giải quyết được → tiếp tục.
+     c. Phần **thực sự còn trống** → **CHECKPOINT chặn mềm, GỘP mọi gap vào một lần** (mỗi gap ghi rõ "đã tìm ở: {nguồn}"):
+        ```
+        ⚠️  §4.5.4 chưa đủ cho {UC-ID}/{platform} — {n} mapping còn trống (đã vét SRC-CHAIN):
+             - {client method} → {thiếu gì: endpoint/field/error→UI}
+           Wire adapter thật với mapping chưa chốt sẽ phải rework.
+           Khuyến nghị (front-load): /generate-tech-docs {web|app .feature} → bổ sung §4.5.4 → /review-tech-docs.
+           Vẫn wire bây giờ? (Y = best-effort/giữ mock cho phần thiếu · N = dừng, đi hoàn thiện tech-docs)
+        ```
+        Chỉ tiếp khi Y. *(Đây là "tư thế BE": trỏ ngược tech-docs thay vì hỏi live từng câu.)*
 Định vị mock adapter có sẵn từ lần chạy `--phase=ui` (tìm `{UC-ID}MockApiAdapter` trong `{paths.src_dir}/{domain}/`).
 Nếu không tìm thấy → cảnh báo: "Không tìm thấy mock adapter — sinh real API adapter từ đầu dùng contract tech-doc."
 
@@ -775,7 +789,18 @@ DTOs → Entity/Model → Repository → Service interface → Service impl →
 
 > **Quy tắc entry-point:** `@trace.implements` phải xuất hiện ở **layer entry-point** như định nghĩa trong `CLAUDE.md §2`. Với REST API → Controller. Với module event-driven → event handler / consumer class. Với context-engineering → hàm orchestration prompt. Không bao giờ chỉ đặt ở layer trong.
 
-> **Quy tắc nguồn giá trị (chống hard-code):** MỌI giá trị cụ thể (endpoint path, error code, tên field/DTO, enum, limit/timeout, header) phải lấy từ **nguồn đã chốt** — tech-doc §4 (contract) · `core-entities.md` (enum/field) · config/env — **KHÔNG bịa inline**. Nếu một hằng số nghiệp vụ lặp lại hoặc mang ý nghĩa (retry count, ngưỡng, key) → **đặt tên hằng số** (constant/config), không rải magic number/string trong code. Không có nguồn cho một giá trị → đây là GAP: dừng và hỏi, đừng chế bừa (đồng bộ Cổng 2 của generate-tech-docs). *(DS3 đã đảm bảo có §4 contract trước khi tới đây với BE.)*
+> **Quy tắc nguồn giá trị (chống hard-code):** MỌI giá trị cụ thể (endpoint path, error code, tên field/DTO, enum, limit/timeout, header) phải lấy từ **nguồn đã chốt** — **KHÔNG bịa inline**. Nếu một hằng số nghiệp vụ lặp lại hoặc mang ý nghĩa (retry count, ngưỡng, key) → **đặt tên hằng số** (constant/config), không rải magic number/string trong code.
+>
+> **VÉT CẠN NGUỒN TRƯỚC KHI HỎI (SRC-CHAIN) — bắt buộc.** Khi một giá trị chưa thấy ở nguồn chính, PHẢI quét lần lượt các nguồn đã có trong context/spec-package theo thứ tự sau, **dừng ngay khi tìm thấy** (skip-if-answered), KHÔNG hỏi người ngay:
+> 1. Tech-doc gộp §4 (contract: §4.1 endpoint · §4.2 request/response · §4.3 error · §4.5.4 client integration)
+> 2. `core-entities.md` (tên field / type / enum) · `business-dictionary.md` (thuật ngữ chuẩn)
+> 3. PRD của UC (nhất là Appendix "Existing API Contract" khi `API Source: existing`, và metadata)
+> 4. Design-spec (FE/App: field/label/state màn hình)
+> 5. System/platform BDD — mệnh đề `Then` (behavior + giá trị fixture)
+> 6. Code/adapter đã sinh ở lần chạy trước (vd mock adapter `--phase=ui` đã chốt shape port/DTO) · config/env
+> 7. Tech-doc anh em cùng domain
+>
+> Chỉ giá trị **thật sự không nguồn nào có** mới là GAP. **Gom TẤT CẢ GAP còn lại vào MỘT checkpoint** (mỗi GAP ghi rõ "đã tìm ở: {các nguồn}"), hỏi một lượt — KHÔNG hỏi lắt nhắt từng câu, KHÔNG chế bừa (đồng bộ Cổng 2 của generate-tech-docs). *(DS3 đã đảm bảo có §4 contract trước khi tới đây với BE.)*
 
 ### Test Selectors — emit element ID ổn định *(chỉ UI FE/App)*
 
@@ -829,7 +854,8 @@ Dựng mock từ `mock_source` đã phân giải ở Phase Detection — **shape
 *Bỏ qua hoàn toàn section này nếu `--phase` không phải `integration`.*
 
 1. **Đọc integration design.** Trong tech-doc gộp `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md`: ưu tiên §4.5.4 (mapping port→endpoint→DTO→error của platform), dùng §4.1/§4.2/§4.3 làm nguồn endpoint / request-response / error-code. Nếu doc chưa có §4.5.4 cho platform này, trích endpoint + shape + error code trực tiếp từ §4.1–§4.3.
-2. **Đọc mock adapter có sẵn** interface (`{UC-ID}ApiPort`) từ output `--phase=ui`.
+   - **Tính đủ của §4.5.4 đã được cửa DS4 (Phase Detection) kiểm + vét SRC-CHAIN + gộp-hỏi TỪ TRƯỚC.** Ở bước này dùng thẳng kết quả đã phân giải của DS4 — **KHÔNG mở checkpoint/hỏi lại**. Nếu DS4 kết luận một mapping vẫn trống mà người đã chọn Y (best-effort) → giữ mock cho đúng phần đó, tag `@trace.stub`, ghi sổ seam; đừng bịa giá trị.
+2. **Đọc mock adapter có sẵn** interface (`{UC-ID}ApiPort`) từ output `--phase=ui`. Real adapter implements **cùng** interface này → shape port/DTO đã cố định từ mock; **không hỏi lại shape** đã có ở đây.
 3. **Sinh real API adapter** tại `{paths.src_dir}/{domain}/{UC-ID}ApiAdapter.{ext}`:
    - Implements cùng interface `{UC-ID}ApiPort` như mock adapter
    - Gọi HTTP thật tới endpoint từ contract tech-doc