@educa-corp/sdd-framework 0.2.4 → 0.2.6

package/commands/generate-tech-docs.md

@@ -463,6 +463,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.
@@ -587,308 +606,300 @@ Ghi/mở rộng `{output_path}` dùng template dưới đây, chỉ sinh **nội
 
 <!--
   ════════════════════════════════════════════════════════════════════════════
-  TEMPLATE: Technical Design Document (per-PRD, full-stack, merged)
-  Used by: /generate-tech-docs
+  TEMPLATE: Tài liệu Thiết kế Kỹ thuật (per-PRD, full-stack, gộp)
+  Dùng bởi: /generate-tech-docs
   ════════════════════════════════════════════════════════════════════════════
 
-  SCOPE MODEL
-  - ONE document per PRD (not per UC). It covers EVERY use case of the PRD in a
-    single merged, full-stack design: backend (API, data model, DB) AND client
-    (components, state, API-integration) side by side, joined by cross-tier
-    sequence diagrams. This is the "construction blueprint" any developer opens
-    to implement the whole feature.
-  - INPUT is the BDD feature files of the PRD (web/ · app/ · system/), NOT the
-    PRD prose. The PRD is loaded only for Overview/Goals/Actors context.
-
-  INCREMENTAL / APPEND
-  - When new BDD is added to the same PRD later, this document is EXTENDED, not
-    regenerated: add the new UC's sections + sequence diagrams, update the
-    UC Coverage matrix (§10) and the Changelog. Never clobber existing content
-    or hand edits.
-
-  FILLING RULES
-  - Replace every {…} placeholder with real content. Delete guidance comments.
-  - TERMINOLOGY: obey the project dictionary 100%
-    (specs/domain-knowledge/business-dictionary.md). Status/enum values →
-    core-entities.md (Enum Registry). Entities → core-entities.md.
-  - Keep code/DTO/DB samples in the project's stack idiom (see the active module
-    stack-profile). The C#/Angular snippets below are ILLUSTRATIVE — swap for
-    the real stack.
-  - A section that does not apply to this PRD: keep the heading and write
-    "N/A — {reason}" rather than deleting it, so the shape stays predictable.
-  - Every sequence diagram / API / rule should be traceable back to a scenario:
-    reference the SC id (e.g. UC1-SC3) it serves.
+  MÔ HÌNH PHẠM VI
+  - MỘT tài liệu cho mỗi PRD (không phải per-UC). Nó bao phủ MỌI use case của PRD
+    trong một thiết kế full-stack gộp: backend (API, mô hình dữ liệu, DB) VÀ client
+    (component, state, tích hợp API) đặt cạnh nhau, nối bằng sequence diagram xuyên
+    tầng. Đây là "bản vẽ thi công" mà bất kỳ dev nào mở ra để implement cả feature.
+  - ĐẦU VÀO là các file BDD của PRD (web/ · app/ · system/), KHÔNG phải văn xuôi PRD.
+    PRD chỉ nạp để lấy bối cảnh Overview/Goals/Actors.
+
+  TĂNG DẦN / APPEND
+  - Khi BDD mới được thêm vào cùng PRD về sau, tài liệu này được MỞ RỘNG, không sinh
+    lại: thêm section + sequence diagram của UC mới, cập nhật ma trận Độ phủ UC (§10)
+    và Changelog. KHÔNG bao giờ đè nội dung có sẵn hay chỉnh tay.
+
+  QUY TẮC ĐIỀN
+  - Thay MỌI placeholder {…} bằng nội dung thật. Xoá các comment hướng dẫn.
+  - THUẬT NGỮ: tuân 100% từ điển dự án (specs/domain-knowledge/business-dictionary.md).
+    Giá trị status/enum → core-entities.md (Enum Registry). Entity → core-entities.md.
+  - Giữ code/DTO/DB mẫu theo idiom stack của dự án (xem stack-profile của module đang
+    dùng). Snippet C#/Angular bên dưới chỉ MANG TÍNH MINH HOẠ — thay bằng stack thật.
+  - Section không áp dụng cho PRD này: GIỮ heading và viết "N/A — {lý do}" thay vì
+    xoá, để cấu trúc luôn nhất quán, dễ đoán.
+  - Mọi sequence diagram / API / rule phải truy vết được về một scenario: tham chiếu
+    id SC (vd UC1-SC3) mà nó phục vụ.
 -->
 
-# {Feature Area} — {PRD Title} Technical Design Document
+# {Feature Area} — Tài liệu Thiết kế Kỹ thuật: {PRD Title}
 
-<!-- @trace block (PRD-level). ucs = every UC covered by this doc; append ids as UCs are added. -->
+<!-- Khối @trace (cấp PRD). ucs = mọi UC mà doc này phủ; nối thêm id khi thêm UC. GIỮ NGUYÊN key @trace.* — máy đọc. -->
 ---
 @trace.id: {TICKET-ID}
 @trace.domain: {domain}
 @trace.prd: {TICKET-ID}
 @trace.ucs: {TICKET-ID}-UC1, {TICKET-ID}-UC2{, …}
-@trace.service: {service — from BDD header @trace.service}
-@trace.module: {module(s) involved — e.g. dotnet, angular}
-@trace.platforms: {system | web | app — whichever BDD folders exist}
-@trace.bdd_version: {per-platform map — e.g. system=1.5, web=1.9, app=1.7; only platforms present. Each feature carries its own bdd_version; do not flatten to one number.}
+@trace.service: {service — từ header BDD @trace.service}
+@trace.module: {module liên quan — vd dotnet, angular}
+@trace.platforms: {system | web | app — tuỳ thư mục BDD nào tồn tại}
+@trace.bdd_version: {map theo từng platform — vd system=1.5, web=1.9, app=1.7; chỉ platform có mặt. Mỗi feature mang bdd_version riêng; đừng gộp về một số.}
 @trace.api_source: {existing | —}
 @trace.revision: 1
 @trace.status: draft
 @trace.generated_at: {YYYY-MM-DD}
 ---
 
-> **Related docs:** {link sibling PRDs / tech-designs this depends on, e.g. [OTHER-TICKET](../{other-slug}/tech-docs/{OTHER-TICKET}-tech-design.md)}. Delete if none.
+> **Tài liệu liên quan:** {link các PRD / tech-design anh em mà doc này phụ thuộc, vd [OTHER-TICKET](../{other-slug}/tech-docs/{OTHER-TICKET}-tech-design.md)}. Xoá nếu không có.
 
-## 1. Overview
+## 1. Tổng quan (Overview)
 
-<!-- 2–4 sentences: what this feature does, who uses it, the key technical shape
-     (data sources, primary side effects). Name where data comes from (DB vs
-     external API) and the main write. Source: PRD + system BDD. -->
+<!-- 2–4 câu: feature làm gì, ai dùng, hình dạng kỹ thuật cốt lõi (nguồn dữ liệu,
+     side effect chính). Nêu rõ dữ liệu đến từ đâu (DB vs API ngoài) và thao tác ghi
+     chính. Nguồn: PRD + system BDD. -->
 
-{What the feature does, its main actor, and the core technical mechanism. State
-which data is owned (DB) vs sourced live (external API), and the primary write.}
+{Feature làm gì, tác nhân chính, và cơ chế kỹ thuật cốt lõi. Nêu rõ dữ liệu nào được
+sở hữu (DB) vs lấy live (API ngoài), và thao tác ghi chính.}
 
-### Goals
+### Mục tiêu (Goals)
 
-<!-- Bullet the technical goals — derived from PRD goals, phrased as what the
-     system must guarantee. -->
+<!-- Liệt kê mục tiêu kỹ thuật — suy từ mục tiêu PRD, diễn đạt thành thứ hệ thống
+     phải đảm bảo. -->
 
-- {Goal 1}
-- {Goal 2}
+- {Mục tiêu 1}
+- {Mục tiêu 2}
 
-### Business Actors
+### Tác nhân nghiệp vụ (Business Actors)
 
-| Actor | Description | Channel |
+| Tác nhân | Mô tả | Kênh |
 |-------|-------------|---------|
-| {Actor} | {role & permission} | {entry path, e.g. App → Widget → Portal → API} |
+| {Actor} | {vai trò & quyền} | {đường vào, vd App → Widget → Portal → API} |
 
 ---
 
-## 2. Architecture Overview
+## 2. Tổng quan Kiến trúc (Architecture Overview)
 
-### 2.1 High-level Architecture
+### 2.1 Kiến trúc tổng thể (High-level Architecture)
 
-<!-- ASCII (or mermaid) topology showing the systems this feature touches:
-     client → gateway → service(s) → data stores / external APIs. Keep it to the
-     components THIS PRD actually exercises. Source: architecture.md /
-     project-context.yaml (services, stack). -->
+<!-- ASCII (hoặc mermaid) topology thể hiện các hệ thống feature này chạm tới:
+     client → gateway → service(s) → data store / API ngoài. Chỉ giữ các component
+     mà PRD NÀY thực sự dùng. Nguồn: architecture.md / project-context.yaml (services, stack). -->
 
 ```
-{ASCII or mermaid diagram of the components this feature touches}
+{Sơ đồ ASCII hoặc mermaid các component feature này chạm tới}
 ```
 
-> **Note:** {call out which data is fetched live from an external API vs stored in the owned DB, and any cache layer + TTL.}
+> **Lưu ý:** {chỉ ra dữ liệu nào lấy live từ API ngoài vs lưu trong DB sở hữu, và lớp cache + TTL nếu có.}
 
-### 2.2 Communication Patterns
+### 2.2 Mẫu giao tiếp (Communication Patterns)
 
-| Pattern | Usage | Scope (UC/SC) |
+| Mẫu | Dùng cho | Phạm vi (UC/SC) |
 |---------|-------|---------------|
 | {Client → Gateway → API} | {auth / action} | {UC1} |
-| {API → External API} | {what it fetches, cache TTL} | {UC1-SC…} |
+| {API → API ngoài} | {lấy gì, cache TTL} | {UC1-SC…} |
 
 ---
 
-## 3. Data Model
+## 3. Mô hình Dữ liệu (Data Model)
 
-<!-- Source: core-entities.md (owned entities) + BDD Then-clauses (state) + PRD.
-     Distinguish OWNED entities (in the DB) from API-SOURCED models (fetched
-     live, not persisted). List only fields this PRD reads or writes. -->
+<!-- Nguồn: core-entities.md (entity sở hữu) + mệnh đề Then của BDD (state) + PRD.
+     Phân biệt entity SỞ HỮU (trong DB) với model NGUỒN-API (lấy live, không lưu).
+     Chỉ liệt kê field mà PRD này đọc hoặc ghi. -->
 
-### 3.1 Entity Design
+### 3.1 Thiết kế Entity (Entity Design)
 
-#### {EntityName} ({DB entity | API-sourced POCO})
+#### {EntityName} ({DB entity | POCO nguồn-API})
 
-{One line: what it represents, and whether it is persisted or fetched live.}
+{Một dòng: nó biểu diễn gì, và được lưu hay lấy live.}
 
-| Field | Type | Usage in {TICKET-ID} |
+| Field | Kiểu | Dùng trong {TICKET-ID} |
 |-------|------|----------------------|
-| `{field}` | `{type}` | {how this feature uses it — read/write, which SC} |
+| `{field}` | `{type}` | {feature này dùng thế nào — đọc/ghi, SC nào} |
 
-<!-- Repeat per entity. If the feature has meaningful state transitions, add a
-     small state table/diagram like below. -->
+<!-- Lặp lại cho mỗi entity. Nếu feature có chuyển trạng thái đáng kể, thêm bảng/sơ đồ
+     state nhỏ như dưới. -->
 
-**State transitions (if any):**
+**Chuyển trạng thái (nếu có):**
 
 ```
-{state A}:  {condition}  → {outcome / UI signal}
-{state B}:  {condition}  → {outcome}
+{state A}:  {điều kiện}  → {kết quả / tín hiệu UI}
+{state B}:  {điều kiện}  → {kết quả}
 ```
 
-**Constraints:**
-- {invariant enforced in application/DB logic, e.g. exactly one primary per tenant}
+**Ràng buộc:**
+- {invariant enforce ở tầng application/DB, vd đúng một primary cho mỗi tenant}
 
-### 3.2 Entity Relationships
+### 3.2 Quan hệ Entity (Entity Relationships)
 
 ```
-{relationship diagram — cardinalities, join keys, which fields are read-only vs owned}
+{sơ đồ quan hệ — cardinality, khoá join, field nào read-only vs sở hữu}
 ```
 
-### 3.3 Data Source Boundaries
+### 3.3 Ranh giới Nguồn dữ liệu (Data Source Boundaries)
 
-<!-- Crisp statement of what THIS PRD reads vs writes, and what is delegated
-     elsewhere. Prevents scope bleed. -->
+<!-- Phát biểu gọn PRD NÀY đọc gì vs ghi gì, và cái gì được uỷ thác nơi khác.
+     Chống lem phạm vi. -->
 
-**{TICKET-ID} scope: {READ … / WRITE …}.**
+**Phạm vi {TICKET-ID}: {ĐỌC … / GHI …}.**
 
-| Responsibility | In scope? | Handled by |
+| Trách nhiệm | Trong phạm vi? | Do ai xử lý |
 |----------------|-----------|-----------|
-| {read merged list} | ✅ Yes | {endpoint / service} |
-| {write X flag} | ✅ Yes | {service} |
-| {base data} | ❌ Read-only | {external API + cache} |
-| {other module concern} | ❌ No | {module/team} |
+| {đọc list đã gộp} | ✅ Có | {endpoint / service} |
+| {ghi cờ X} | ✅ Có | {service} |
+| {dữ liệu gốc} | ❌ Read-only | {API ngoài + cache} |
+| {mối lo module khác} | ❌ Không | {module/team} |
 
 ### 3.4 Multi-tenant & Sharding
 
-<!-- Only if the project is multi-tenant. Else write "N/A — single tenant". -->
+<!-- Chỉ khi dự án multi-tenant. Nếu không, viết "N/A — single tenant". -->
 
-- {tenant key on entities, query-filter isolation, shard resolution — from architecture.md}
+- {khoá tenant trên entity, cách ly bằng query-filter, phân giải shard — từ architecture.md}
 
 ---
 
-## 4. API Contracts
+## 4. Hợp đồng API (API Contracts)
 
-<!-- Backend contract. For greenfield: design endpoints from BDD scenarios. For
-     brownfield (@trace.api_source = existing): reverse-document the live API
-     as-is and note gaps vs BDD expectations. Mark REUSE vs NEW explicitly.
-     CLIENT-ONLY PRD (no system/ BDD — this feature owns no backend): do NOT
-     fabricate a BE contract. §4.1 then lists the endpoints the client CONSUMES
-     (external / third-party / another team's / existing), marked "consumed
-     (external)", reverse-documented from the client BDD Then-clauses + PRD;
-     fill §4.2/§4.3 only if the shape is known. If the feature makes no network
-     calls at all → write "N/A — client-only, no backend". §4.5.4 maps client
-     methods to whatever §4.1 lists (or none). -->
+<!-- Contract backend. Greenfield: thiết kế endpoint từ scenario BDD. Brownfield
+     (@trace.api_source = existing): reverse-document API đang chạy as-is và ghi chú
+     gap so với kỳ vọng BDD. Đánh dấu REUSE vs NEW rõ ràng.
+     PRD CHỈ-CLIENT (không có BDD system/ — feature này không sở hữu backend): ĐỪNG
+     bịa contract BE. §4.1 khi đó liệt kê các endpoint mà client TIÊU THỤ (ngoài /
+     bên thứ ba / của team khác / có sẵn), đánh dấu "consumed (external)",
+     reverse-document từ mệnh đề Then của BDD client + PRD; chỉ điền §4.2/§4.3 nếu
+     biết shape. Nếu feature không gọi mạng gì cả → viết "N/A — client-only, no backend".
+     §4.5.4 ánh xạ method client tới bất cứ gì §4.1 liệt kê (hoặc không có). -->
 
 
 ### 4.1 Endpoints
 
 ```
-{METHOD} {/path}          # NEW | REUSE ({source}) — {one-line purpose}
+{METHOD} {/path}          # NEW | REUSE ({nguồn}) — {mục đích một dòng}
 ```
 
-### 4.2 Request/Response Models
+### 4.2 Model Request/Response (Request/Response Models)
 
-<!-- Show DTO shapes in the stack's idiom. Note which fields come from DB vs
-     external API. -->
+<!-- Thể hiện shape DTO theo idiom của stack. Ghi rõ field nào đến từ DB vs API ngoài. -->
 
 ```{lang}
-{DTO definitions with per-field source comments}
+{định nghĩa DTO kèm comment nguồn từng field}
 ```
 
-### 4.3 Validation & Error Codes
+### 4.3 Validation & Mã lỗi (Validation & Error Codes)
 
-**Validation rules:**
+**Quy tắc validation:**
 
 ```{lang}
-{validation rules, in the stack's idiom (e.g. FluentValidation / class-validator)}
+{quy tắc validation, theo idiom stack (vd FluentValidation / class-validator)}
 ```
 
-| Code | HTTP Status | Description | Trace |
+| Code | HTTP Status | Mô tả | Trace |
 |------|-------------|-------------|-------|
-| `{ERROR_CODE}` | {4xx/5xx} | {when it fires} | {UC1-SC…} |
+| `{ERROR_CODE}` | {4xx/5xx} | {khi nào phát sinh} | {UC1-SC…} |
 
-### 4.4 Handler Logic (key endpoints)
+### 4.4 Logic Handler (endpoint chính)
 
-<!-- For non-trivial writes, spell out the ordered steps (validation →
-     transaction → commit/rollback → return). Keeps the sequence diagram and
-     the code aligned. -->
+<!-- Với các thao tác ghi không tầm thường, viết rõ các bước có thứ tự (validation →
+     transaction → commit/rollback → return). Giữ sequence diagram và code khớp nhau. -->
 
 **{HandlerName}:**
-1. {step}
-2. {step — transaction boundary if any}
+1. {bước}
+2. {bước — ranh giới transaction nếu có}
 
-### 4.5 UI Component Mapping — {platform} ({framework})
+### 4.5 Ánh xạ Component UI (UI Component Mapping) — {platform} ({framework})
 
-<!-- CLIENT design, GROUPED BY PLATFORM: one "### 4.5 … — {platform}" section per
-     client platform present in the BDD (a web group, an app group). Do NOT title
-     this heading by screen — screens/UCs live in the sub-blocks below.
-     Inside a platform group:
-       • §4.5.1 Component Hierarchy — repeat the sub-block per screen/UC:
-         "#### 4.5.1.x {Screen} — {UC}". A PRD with many screens/UCs → many sub-blocks
-         in the SAME platform group (never a second 4.5 group for the same platform).
-       • §4.5.2–§4.5.5 — likewise per screen/UC where they differ.
-       • §4.5.6 Test Selectors — ONE shared table for the whole platform group; its
-         "Serves SC" column carries (UC · SC) so per-UC consumers filter their rows.
-     Append: new platform → new "### 4.5 — {platform}" group; new screen/UC in an
-     existing platform → add a sub-block + rows to §4.5.6 (don't duplicate the group).
-     Omit §4.5 entirely for a backend-only PRD. -->
+<!-- Thiết kế CLIENT, NHÓM THEO PLATFORM: một section "### 4.5 … — {platform}" cho mỗi
+     platform client có trong BDD (một nhóm web, một nhóm app). ĐỪNG đặt tên heading
+     này theo màn hình — màn hình/UC nằm ở các sub-block bên dưới.
+     Bên trong một nhóm platform:
+       • §4.5.1 Cây Component — lặp sub-block theo màn hình/UC:
+         "#### 4.5.1.x {Screen} — {UC}". Một PRD nhiều màn hình/UC → nhiều sub-block
+         trong CÙNG nhóm platform (không bao giờ tạo nhóm 4.5 thứ hai cho cùng platform).
+       • §4.5.2–§4.5.5 — tương tự theo màn hình/UC ở chỗ chúng khác nhau.
+       • §4.5.6 Test Selectors — MỘT bảng dùng chung cho cả nhóm platform; cột
+         "Phục vụ SC" mang (UC · SC) để consumer per-UC lọc row của mình.
+     Append: platform mới → nhóm "### 4.5 — {platform}" mới; màn hình/UC mới trong
+     platform đã có → thêm sub-block + row vào §4.5.6 (đừng lặp nhóm).
+     Bỏ hẳn §4.5 với PRD backend-only. -->
 
-> **Source:** {Figma file + node id, from design-spec}
-> **Stack:** {framework, state primitive, component library}
-> <!-- @figma.url: {node-level figma url} -->
+> **Nguồn:** {file Figma + node id, từ design-spec}
+> **Stack:** {framework, state primitive, thư viện component}
+> <!-- @figma.url: {url figma cấp node} -->
 
-#### 4.5.1 Component Hierarchy — {Screen} ({UC})
+#### 4.5.1 Cây Component (Component Hierarchy) — {Screen} ({UC})
 
-<!-- Repeat this sub-block per screen/UC in this platform group (4.5.1.a, 4.5.1.b …). -->
+<!-- Lặp sub-block này theo màn hình/UC trong nhóm platform này (4.5.1.a, 4.5.1.b …). -->
 
 ```
-{component tree — container vs presentational, conditional children}
+{cây component — container vs presentational, con có điều kiện}
 ```
 
-#### 4.5.2 Component File Mapping
+#### 4.5.2 Ánh xạ file Component (Component File Mapping)
 
-| Component | Path | Type | Purpose |
+| Component | Path | Loại | Trách nhiệm |
 |-----------|------|------|---------|
-| `{Component}` | `{path}` | {Feature/Child} | {responsibility} |
+| `{Component}` | `{path}` | {Feature/Child} | {trách nhiệm} |
 
-#### 4.5.3 State Management ({state primitive})
+#### 4.5.3 Quản lý State (State Management) ({state primitive})
 
-<!-- State shape derived from System BDD Then-clauses + response shapes from §4.2.
-     Show derived/computed values and their inputs. -->
+<!-- Shape state suy từ mệnh đề Then của System BDD + shape response từ §4.2.
+     Thể hiện giá trị dẫn xuất/tính toán và input của chúng. -->
 
 ```{lang}
-{state declarations with source comments (which BDD field / BE field each maps to)}
+{khai báo state kèm comment nguồn (mỗi cái map tới field BDD / field BE nào)}
 ```
 
-#### 4.5.4 API Integration Layer (port/adapter)
+#### 4.5.4 Tầng tích hợp API (API Integration Layer — port/adapter)
 
-<!-- Modal/route config + API-integration map: each client service method → a
-     REAL endpoint from §4.1 (do not invent endpoints). Error → UI state per SC.
-     This table is what /generate-code --phase=integration reads to wire the real adapter. -->
+<!-- Cấu hình modal/route + bản đồ tích hợp API: mỗi method service client → một
+     endpoint THẬT từ §4.1 (đừng bịa endpoint). Lỗi → state UI theo từng SC.
+     Bảng này là thứ /generate-code --phase=integration đọc để wire adapter thật. -->
 
-| Client method | Endpoint (§4.1) | Request map | Response → model | Error → UI |
+| Method client | Endpoint (§4.1) | Map request | Response → model | Lỗi → UI |
 |---------------|-----------------|-------------|------------------|-----------|
 | {svc.getX()} | {GET /…} | {params} | {DTO → ViewModel} | {4xx → state/toast} |
 
-#### 4.5.5 Figma → Design System Mapping
+#### 4.5.5 Ánh xạ Figma → Design System
 
-| Figma element | Design system class/token | Notes |
+| Element Figma | Class/token design system | Ghi chú |
 |---------------|---------------------------|-------|
-| {element} | {class / token} | {size, color, state} |
+| {element} | {class / token} | {size, màu, state} |
 
-#### 4.5.6 Test Selectors — element IDs for actionable elements (QC contract)
+#### 4.5.6 Test Selectors — id element cho phần tử có action (hợp đồng QC)
 
-<!-- Stable test-id per interactive element so QC locates directly (no runtime
-     scan). Convention: {uc-lower}-{screen}-{element}-{type}; DO NOT embed
-     scenario numbers. Attribute per platform: web data-testid · RN testID ·
-     Flutter Key/Semantics · iOS accessibilityIdentifier. Reuse the same id
-     VALUE across web/app for the same logical element.
-     ONE shared table for the whole platform group (covers every screen/UC of this
-     platform). The "Serves SC" column carries (UC · SC) so a per-UC consumer
-     (generate-code / qc) filters to its own rows via §10. This §4.5 group is
-     already platform-scoped, so the platform is implicit (web block → web · SC). -->
+<!-- Test-id ổn định cho mỗi element tương tác để QC định vị trực tiếp (không scan
+     runtime). Quy ước: {uc-lower}-{screen}-{element}-{type}; ĐỪNG nhúng số scenario.
+     Attribute theo platform: web data-testid · RN testID · Flutter Key/Semantics ·
+     iOS accessibilityIdentifier. Dùng lại CÙNG giá trị id trên web/app cho cùng một
+     element logic.
+     MỘT bảng dùng chung cho cả nhóm platform (phủ mọi màn hình/UC của platform này).
+     Cột "Phục vụ SC" mang (UC · SC) để consumer per-UC (generate-code / qc) lọc row
+     của mình qua §10. Nhóm §4.5 này vốn đã theo platform, nên platform là ngầm định
+     (khối web → web · SC). -->
 
-| Test-ID | Element | Component (§4.5.1.x) | Action | Serves SC (UC · SC) |
+| Test-ID | Element | Component (§4.5.1.x) | Action | Phục vụ SC (UC · SC) |
 |---------|---------|----------------------|--------|---------------------|
-| `{uc}-{screen}-{element}-{type}` | {Submit button} | {Component} | {submit} | {UC1 · SC1, UC1 · SC3} |
+| `{uc}-{screen}-{element}-{type}` | {Nút submit} | {Component} | {submit} | {UC1 · SC1, UC1 · SC3} |
 
 ---
 
-## 5. Key Flows (Sequence Diagrams)
+## 5. Luồng chính (Key Flows — Sequence Diagrams)
 
-<!-- ONE mermaid sequence diagram per meaningful scenario. Participants span tiers:
-     client component → service → API → external API → DB.
-     ⚠ SC ids are unique only within (UC × platform): `{UC}-SC1` on `system` and
-     `{UC}-SC1` on `web` are DIFFERENT scenarios. So group flows into PLATFORM LANES
-     (5.A system · 5.B web · 5.C app) and ALWAYS pair the SC with its platform,
-     e.g. "(web · UC1-SC1)". Never write a bare "UC1-SC1" here — it is ambiguous.
-     Only include the lanes whose BDD exists in this PRD. -->
+<!-- MỘT mermaid sequence diagram cho mỗi scenario đáng kể. Participant xuyên tầng:
+     component client → service → API → API ngoài → DB.
+     ⚠ id SC chỉ duy nhất trong phạm vi (UC × platform): `{UC}-SC1` ở `system` và
+     `{UC}-SC1` ở `web` là HAI scenario KHÁC nhau. Nên gom luồng vào các LANE PLATFORM
+     (5.A system · 5.B web · 5.C app) và LUÔN ghi kèm platform với SC, vd
+     "(web · UC1-SC1)". Đừng bao giờ viết "UC1-SC1" trơ ở đây — mơ hồ.
+     Chỉ đưa các lane có BDD tồn tại trong PRD này. -->
 
-### 5.A System flows
+### 5.A Luồng System
 
-<!-- One diagram per system-BDD scenario. Skip this lane if no system/ BDD. -->
+<!-- Một diagram cho mỗi scenario system-BDD. Bỏ lane này nếu không có BDD system/. -->
 
-#### 5.A.1 {name} (system · {UC}-SC…)
+#### 5.A.1 {tên} (system · {UC}-SC…)
 
 ```mermaid
 sequenceDiagram
@@ -896,147 +907,147 @@ sequenceDiagram
     {…}
 ```
 
-### 5.B Web flows
+### 5.B Luồng Web
 
-<!-- One diagram per web-BDD scenario. Skip this lane if no web/ BDD. -->
+<!-- Một diagram cho mỗi scenario web-BDD. Bỏ lane này nếu không có BDD web/. -->
 
-#### 5.B.1 {name} (web · {UC}-SC…)
+#### 5.B.1 {tên} (web · {UC}-SC…)
 
 ```mermaid
 sequenceDiagram
     {…}
 ```
 
-### 5.C App flows
+### 5.C Luồng App
 
-<!-- One diagram per app-BDD scenario. Skip this lane if no app/ BDD. -->
+<!-- Một diagram cho mỗi scenario app-BDD. Bỏ lane này nếu không có BDD app/. -->
 
-#### 5.C.1 {name} (app · {UC}-SC…)
+#### 5.C.1 {tên} (app · {UC}-SC…)
 
 ```mermaid
 sequenceDiagram
     {…}
 ```
 
-<!-- Number within each lane: 5.A.1, 5.A.2 … / 5.B.1 … / 5.C.1 …. For a scenario
-     whose effect crosses into another module, note "(covered by {OTHER-UC})". -->
+<!-- Đánh số trong từng lane: 5.A.1, 5.A.2 … / 5.B.1 … / 5.C.1 …. Với scenario mà
+     hiệu ứng lấn sang module khác, ghi "(covered by {OTHER-UC})". -->
 
-**Key integration points (optional table per flow):**
+**Điểm tích hợp chính (bảng tuỳ chọn cho mỗi luồng):**
 
-| Step | State transition | Verified by (platform · SC) |
+| Bước | Chuyển trạng thái | Verify bởi (platform · SC) |
 |------|------------------|-----------------------------|
-| {step} | {before → after} | {web · UC1-SC…} |
+| {bước} | {trước → sau} | {web · UC1-SC…} |
 
 ---
 
-## 6. Integration Points
+## 6. Điểm tích hợp (Integration Points)
 
-| Integration | Direction | Method | Description |
+| Tích hợp | Chiều | Phương thức | Mô tả |
 |-------------|-----------|--------|-------------|
-| {Client → API} | Outbound (client) | {REST/Bearer} | {what} |
-| {API → External} | Outbound (server) | {REST + header} | {what, cache TTL} |
+| {Client → API} | Outbound (client) | {REST/Bearer} | {gì} |
+| {API → Ngoài} | Outbound (server) | {REST + header} | {gì, cache TTL} |
 
 ### 6.1 Event Bus / Messaging
 
-<!-- Kafka/queue events produced/consumed by this feature. "N/A — no events" if none. -->
+<!-- Event Kafka/queue mà feature này produce/consume. "N/A — no events" nếu không có. -->
 
-{events, or N/A}
+{events, hoặc N/A}
 
-### 6.2 Cross-Service Dependencies
+### 6.2 Phụ thuộc Cross-Service (Cross-Service Dependencies)
 
-| Dependent service | What's needed | Contract | Status |
+| Service phụ thuộc | Cần gì | Contract | Trạng thái |
 |-------------------|---------------|----------|--------|
-| {service} | {need} | {endpoint} | {✅ Exists / ⚠️ pending} |
+| {service} | {cần} | {endpoint} | {✅ Có / ⚠️ pending} |
 
 ---
 
-## 7. Security & Authorization
+## 7. Bảo mật & Phân quyền (Security & Authorization)
 
-### 7.1 Authentication
+### 7.1 Xác thực (Authentication)
 
-{Auth flow + token type/TTL. Source: PRD auth + project rules.}
+{Luồng auth + loại token/TTL. Nguồn: auth PRD + rule dự án.}
 
-### 7.2 Authorization Rules
+### 7.2 Quy tắc Phân quyền (Authorization Rules)
 
-| Action | Required role/permission | Description | Trace |
+| Action | Role/quyền yêu cầu | Mô tả | Trace |
 |--------|--------------------------|-------------|-------|
-| {action} | {role} | {how enforced, where} | {UC1-SC… / out of scope} |
+| {action} | {role} | {enforce thế nào, ở đâu} | {UC1-SC… / ngoài phạm vi} |
 
 ---
 
-## 8. Error Handling & Edge Cases
+## 8. Xử lý lỗi & Trường hợp biên (Error Handling & Edge Cases)
 
-<!-- One row per error / edge / negative scenario in the BDD. This must line up
-     with §4.3 error codes and the §5 error sequence diagrams. -->
+<!-- Một row cho mỗi scenario lỗi / biên / âm trong BDD. Phải khớp với mã lỗi §4.3
+     và các sequence diagram lỗi §5. -->
 
-| Scenario | Strategy | Details | Trace |
+| Scenario | Chiến lược | Chi tiết | Trace |
 |----------|----------|---------|-------|
-| {condition} | {approach} | {behavior, message, side effect} | {UC1-SC…, BR…} |
+| {điều kiện} | {cách xử lý} | {hành vi, message, side effect} | {UC1-SC…, BR…} |
 
 ---
 
-## 9. Design Decisions
+## 9. Quyết định Thiết kế (Design Decisions)
 
-<!-- The "why" behind non-obvious choices, with alternatives considered. Source:
-     PRD alternatives/assumptions + reasoning during generation. This is what lets
-     a reviewer trust the design. -->
+<!-- Cái "vì sao" đằng sau các lựa chọn không hiển nhiên, kèm phương án đã cân nhắc.
+     Nguồn: alternatives/assumptions của PRD + lập luận lúc sinh. Đây là thứ giúp
+     reviewer tin tưởng thiết kế. -->
 
-| # | Decision | Rationale | Alternatives considered |
+| # | Quyết định | Lý do | Phương án đã cân nhắc |
 |---|----------|-----------|-------------------------|
-| 1 | **{decision}** | {why} | {alt — why rejected} |
+| 1 | **{quyết định}** | {vì sao} | {phương án — vì sao loại} |
 
-### NFR-to-Design Mapping
+### Ánh xạ NFR → Thiết kế (NFR-to-Design Mapping)
 
-| NFR category | PRD requirement | Design decision |
+| Nhóm NFR | Yêu cầu PRD | Quyết định thiết kế |
 |--------------|-----------------|-----------------|
-| {e.g. Multi-tenant isolation} | {requirement} | {mechanism} |
+| {vd Cách ly multi-tenant} | {yêu cầu} | {cơ chế} |
 
 ---
 
-## 10. UC Coverage
+## 10. Độ phủ UC (UC Coverage)
 
-<!-- THE APPEND ANCHOR **and the INDEX for per-UC consumers**. Every UC of the PRD
-     gets a row; every scenario maps to the section(s) that design it.
-     - /generate-tech-docs uses it to detect what is already covered vs missing.
-     - /generate-code, /map-testids, /qc-* work on ONE UC of a PRD-level doc — they
-       look this UC up HERE first to locate its scenarios → the sections/§5-lanes
-       (and thus the §4.1 endpoints its §5 flows call) that belong to it. Don't
-       pull another UC's endpoints/sections.
-     ⚠ Scenario coverage is keyed by (platform, SC) because SC ids repeat across
-     platforms — the Platform column disambiguates. -->
+<!-- ĐIỂM NEO ĐỂ APPEND **và là MỤC LỤC cho consumer per-UC**. Mọi UC của PRD có một
+     row; mọi scenario map tới (các) section thiết kế nó.
+     - /generate-tech-docs dùng nó để phát hiện cái gì đã phủ vs còn thiếu.
+     - /generate-code, /map-testids, /qc-* làm việc trên MỘT UC của doc cấp-PRD — chúng
+       tra UC này Ở ĐÂY trước để định vị scenario của nó → các section/lane-§5 (và do đó
+       các endpoint §4.1 mà luồng §5 của nó gọi) thuộc về nó. Đừng lấy
+       endpoint/section của UC khác.
+     ⚠ Độ phủ scenario khoá theo (platform, SC) vì id SC lặp giữa các platform —
+     cột Platform để phân biệt. -->
 
-| UC | Feature | Platforms | Sections covered | Status |
+| UC | Feature | Platforms | Section phủ | Trạng thái |
 |----|---------|-----------|------------------|--------|
 | {TICKET-ID}-UC1 | {title} | {system, web, app} | §… | ✅ Covered |
 
-### UC1 Scenario Coverage
+### Độ phủ Scenario UC1
 
-<!-- One row per (platform, SC). Same SC number on different platforms = different
-     scenarios → separate rows. -->
+<!-- Một row cho mỗi (platform, SC). Cùng số SC ở platform khác nhau = scenario khác
+     nhau → row riêng. -->
 
 | Platform | Scenario | Section | Business rule |
 |----------|----------|---------|---------------|
-| system | {UC}-SC1: {name} | §5.A.1 | {BR…} |
-| web | {UC}-SC1: {name} | §4.5 (web), §5.B.1 | {BR…} |
+| system | {UC}-SC1: {tên} | §5.A.1 | {BR…} |
+| web | {UC}-SC1: {tên} | §4.5 (web), §5.B.1 | {BR…} |
 
-<!-- Repeat a scenario-coverage block per UC. -->
+<!-- Lặp một khối scenario-coverage cho mỗi UC. -->
 
 ---
 
-## 11. Cross-cutting & Assumptions (Out-of-Scope Reference)
+## 11. Cross-cutting & Giả định (Tham chiếu ngoài phạm vi)
 
-<!-- Upstream concerns this PRD DEPENDS ON but does not implement (admin gate,
-     downstream UI in another module, order snapshotting…). Keep for cross-team
-     context. Reference the owning UC/team + doc. Source: PRD out-of-scope +
-     BDD BR "out of scope" notes. -->
+<!-- Các mối lo upstream mà PRD này PHỤ THUỘC VÀO nhưng không implement (cổng admin,
+     UI downstream ở module khác, snapshot đơn hàng…). Giữ để có bối cảnh liên team.
+     Tham chiếu UC/team sở hữu + doc. Nguồn: out-of-scope của PRD + ghi chú BR
+     "out of scope" trong BDD. -->
 
-### 11.1 {Concern}
+### 11.1 {Mối lo}
 
-> {Quote the BDD/PRD line that scopes it out.}
+> {Trích câu BDD/PRD đã scope nó ra ngoài.}
 
-{Explanation of the boundary + a reference sequence diagram if useful.}
+{Giải thích ranh giới + một sequence diagram tham chiếu nếu hữu ích.}
 
-**Owned by:** {team / module}. See {link}.
+**Sở hữu bởi:** {team / module}. Xem {link}.
 
 ---
 
@@ -1069,9 +1080,9 @@ sequenceDiagram
 
 ---
 
-## Figma Design References
+## Tham chiếu Thiết kế Figma (Figma Design References)
 
-<!-- @figma.url: {node-level figma url per screen} -->
+<!-- @figma.url: {url figma cấp node cho mỗi màn hình} -->
 - {Screen}: [Figma — {frame}]({url})
 - Exported: {YYYY-MM-DD}
 
@@ -1079,10 +1090,10 @@ sequenceDiagram
 
 ## Changelog
 
-| Revision | Date | Changes |
+| Revision | Ngày | Thay đổi |
 |----------|------|---------|
-| 1 | {YYYY-MM-DD} | Initial generation from {TICKET-ID} BDD (v{bdd_version}): {list UCs covered} |
-<!-- On append: add a row per extension, e.g. "2 | {date} | Added UC3 (§5.9, §10) from new BDD v{n}" -->
+| 1 | {YYYY-MM-DD} | Sinh lần đầu từ BDD {TICKET-ID} (v{bdd_version}): {liệt kê UC đã phủ} |
+<!-- Khi append: thêm một row cho mỗi lần mở rộng, vd "2 | {ngày} | Thêm UC3 (§5.9, §10) từ BDD mới v{n}" -->
 
 
 ---
@@ -1100,6 +1111,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.