@educa-corp/sdd-framework 0.2.5 → 0.2.6

package/commands/generate-code.md

@@ -556,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."
 
@@ -842,7 +854,7 @@ 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.
-   - **Nếu §4/§4.5.4 thiếu bất kỳ chi tiết integration nào (endpoint, field/DTO, error-code, mapping):** ÁP DỤNG **SRC-CHAIN** (xem §Quy tắc nguồn giá trị) — vét cạn PRD (Appendix Existing API Contract), design-spec, mệnh đề `Then` của System/platform BDD, `core-entities.md`, **mock adapter đã sinh ở `--phase=ui`** (shape port/DTO đã chốt — nguồn shape mạnh nhất, đừng bỏ quên), tech-doc anh em cùng domain — TRƯỚC khi coi là GAP. Skip-if-answered. Chỉ hỏi cái không nguồn nào có, và **gộp mọi GAP còn lại vào MỘT checkpoint** (ghi rõ đã tìm ở đâu). *(Đây là fix cho tình trạng phase=integration hỏi nhiều dù đáp án đã nằm trong tài liệu khác.)*
+   - **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

package/commands/generate-code.tmpl

@@ -144,13 +144,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."
 
@@ -430,7 +442,7 @@ 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.
-   - **Nếu §4/§4.5.4 thiếu bất kỳ chi tiết integration nào (endpoint, field/DTO, error-code, mapping):** ÁP DỤNG **SRC-CHAIN** (xem §Quy tắc nguồn giá trị) — vét cạn PRD (Appendix Existing API Contract), design-spec, mệnh đề `Then` của System/platform BDD, `core-entities.md`, **mock adapter đã sinh ở `--phase=ui`** (shape port/DTO đã chốt — nguồn shape mạnh nhất, đừng bỏ quên), tech-doc anh em cùng domain — TRƯỚC khi coi là GAP. Skip-if-answered. Chỉ hỏi cái không nguồn nào có, và **gộp mọi GAP còn lại vào MỘT checkpoint** (ghi rõ đã tìm ở đâu). *(Đây là fix cho tình trạng phase=integration hỏi nhiều dù đáp án đã nằm trong tài liệu khác.)*
+   - **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