@educa-corp/sdd-framework 0.2.4 → 0.2.6

package/commands/generate-tech-docs.tmpl

@@ -51,6 +51,25 @@ Lưu `input_features`, `platforms_present`, danh sách scenario theo từng UC,
 
 ---
 
+## Bước 0.5 — [ARCH] Nạp Architecture Context (nếu có)
+
+Tech-design chắt lọc kiến trúc hệ thống thành API contract + client design, nên đây là **nơi duy nhất** trong pipeline nạp `architecture.md` (SSOT cross-cutting sinh bởi `/generate-architecture`). Không nạp toàn cục ở context-loader — chỉ lệnh này cần nó ở mức sâu.
+
+1. **Phân giải path:** `{paths.specs_dir}/architecture.md` (mặc định `specs/architecture.md`). Chế độ umbrella: context-loader đã trỏ `specs_dir`/`service_root` về service đang active → dùng `architecture.md` của chính service đó (kiến trúc là code-level, per-service).
+2. **Nếu file KHÔNG tồn tại** → bỏ qua âm thầm, đặt `arch = none`. Vẫn dựa vào CLAUDE.md §2 (layers/rules) + core-entities như trước. (Gợi ý mềm một lần trong report cuối: "Chưa có architecture.md — cân nhắc chạy `/generate-architecture` để tech-design bám kiến trúc hệ thống.")
+3. **Nếu tồn tại** → đọc **có chọn lọc theo tier** (mỗi mục có marker `<!-- tier: core|conditional|ops -->`):
+   - **Nạp** thân các mục **`core` + `conditional`** — đây là phần ảnh hưởng code/API/data: layer boundaries + dependency direction, phân loại/nguồn dữ liệu, injection rules, luồng xác thực, response API chuẩn, caching/sharding/messaging, multi-tenant/identity-resolution.
+   - **BỎ QUA** các mục **`ops`** (Observability, Triển khai & DevOps, Chiến lược kiểm thử, NFR) — không đổi thiết kế API/data-model, chỉ làm nhiễu context.
+   - Các section §2–§4 (data model, API contract, integration) PHẢI nhất quán với phần đã nạp — KHÔNG tự suy khác.
+4. **Mục đang STUB (`<!-- status: stub -->`):** nếu một UC trong batch **chạm** tới một concern mà mục tương ứng còn stub (vd UC có tenant scoping nhưng §Multi-tenant là stub) → **cảnh báo mềm** trong report: *"§{Mục} chưa tài liệu hoá trong architecture.md — chạy `/generate-architecture --section={slug}` để tech-design chính xác hơn."* Vẫn tiếp tục dựa vào CLAUDE.md.
+5. **Trust-gate — đọc frontmatter `verified_by`:**
+   - `verified_by: AI-draft` (hoặc trống) → nội dung do AI dựng từ config/tài liệu/code, CHƯA ai verify. Vẫn dùng làm tham chiếu nhưng **cảnh báo** trong report: *"⚠️ architecture.md còn là AI-draft chưa verify — tech-design có thể kế thừa giả định sai. Nên để Tech Lead verify (đổi `verified_by`) trước khi chốt."* Khi mâu thuẫn với CLAUDE.md/BDD thì ưu tiên CLAUDE.md/BDD.
+   - `verified_by: {người thật}` → coi là ràng buộc kiến trúc chính thức.
+
+Lưu `arch` (`none` | `ai-draft` | `verified`) để dùng ở các bước sinh section và report.
+
+---
+
 ## Bước 1 — Chế độ Fresh vs Append
 
 Kiểm tra `output_path` đã tồn tại chưa.
@@ -190,6 +209,8 @@ Trước khi finalize/append doc, **tự phản biện bản nháp** qua 4 cổn
 **Cổng 2 — GAP-or-FLAG (trung thực, không bịa).**
 Cần một type/giá trị/policy (auth, config, event, error code) mà **không có nguồn** → **không** chép hình dạng ở boundary, **không** bịa: ghi `[GAP]` hoặc `[ASSUMPTION: {owner} confirm]`. Nếu doc định thiết kế endpoint/flow mà **BDD không định nghĩa nghiệp vụ** (design vượt BDD) → khai GAP + escalate, đừng âm thầm hợp thức hoá.
 
+**Cổng 2b — Client integration (§4.5.4) cũng phải đủ, không chỉ contract BE.** Với MỖI client method mà một màn hình/UC cần, §4.5.4 phải map đủ: **endpoint thật ở §4.1 · nguồn field request/response · error→UI**. Bất kỳ mảnh nào không suy được từ nguồn → khai `[GAP]` + một dòng §12 (đừng để §4.5.4 khuyết một phần rồi lọt xuống `/generate-code --phase=integration` — đó chính là chỗ FE bị hỏi live). **Severity blocker (🔴)** nếu màn hình không render/hoạt động được khi thiếu mapping đó (→ giữ `@trace.status: in-review`, chặn code-gen tới khi đóng); non-blocker (🟢) nếu chỉ là chi tiết phụ đoán tạm được. Đối xứng với contract BE: front-load ẩn số client về tech-docs, đừng đẩy sang lúc wire adapter.
+
 **Cổng 3 — CATALOG (không hard-code).**
 Literal & constant rải rác như luật → gom lại: **generic envelope** (đừng typed-per-thing khi PRD-BR đã đưa hợp đồng chung) + bảng catalog (vd `signal_type × source`) + constants **đặt tên**. Fail nếu còn hằng số/enum inline chưa vào catalog.
 

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.2.4
+0.2.6