@edupia-tutor/spec-driven-docs 0.14.0 → 0.14.2

package/commands/generate-code.tmpl

@@ -1,9 +1,9 @@
-# /generate-code — Generate Implementation Code
+# /generate-code — Sinh Implementation Code
 
 ## Gate
 {{include:steps/gate.md}}
 
-*Note: For this command, the target in Step 1 is a `.feature` file or UC-ID. If `$ARGUMENTS` is a UC-ID, find the matching feature file by globbing `{paths.specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` (wildcard `*` for the unknown prd-slug, recursive `**` to cover the `web/`·`app/`·`system/` platform subfolders); take `domain` + `prd_slug` from the matched path. Also check `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv` for drift (new vs drifted vs synced).*
+*Lưu ý: Với lệnh này, target ở Bước 1 là một file `.feature` hoặc UC-ID. Nếu `$ARGUMENTS` là UC-ID, tìm file feature khớp bằng cách glob `{paths.specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` (wildcard `*` cho prd-slug chưa biết, `**` đệ quy để phủ các thư mục con platform `web/`·`app/`·`system/`); lấy `domain` + `prd_slug` từ path khớp. Cũng kiểm tra `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv` tìm drift (new vs drifted vs synced).*
 
 ## Context
 {{include:steps/context-loader.md}}
@@ -12,303 +12,301 @@
 
 ## Scope Lock
 
-This command is strictly scoped to the **single feature file** passed as `$ARGUMENTS`:
+Lệnh này giới hạn nghiêm ngặt trong **một file feature** được truyền qua `$ARGUMENTS`:
 
-- Feature file: `{exact path from $ARGUMENTS}`
-- UC: `{UC-ID}` (read from `@trace.id` in that file's header)
+- File feature: `{path chính xác từ $ARGUMENTS}`
+- UC: `{UC-ID}` (đọc từ `@trace.id` trong header file đó)
 
-**Do NOT read or implement scenarios from any other `.feature` file** in the same domain folder, even if they share the same entity, domain concept, or service name.
+**KHÔNG đọc hay implement scenario từ bất kỳ file `.feature` nào khác** trong cùng folder domain, kể cả khi chúng dùng chung entity, khái niệm domain, hay tên service.
 
 ---
 
-## Context Load (additional)
+## Context Load (bổ sung)
 
-Read:
-1. The scoped `.feature` file only
-2. Tech-doc at `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md` (if exists)
+Đọc:
+1. Chỉ file `.feature` đã giới hạn scope
+2. Tech-doc tại `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md` (nếu tồn tại)
 3. CLAUDE.md §architecture + §coding_standards
-4. **(FE/App only)** Design Spec at `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-*{slug}.md` (if exists) — source of screens, component inventory, and the per-screen Figma frame links.
+4. **(chỉ FE/App)** Design Spec tại `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-*{slug}.md` (nếu tồn tại) — nguồn của màn hình, component inventory, và link Figma frame từng-màn.
 
 ---
 
 ## Phase Detection
 
-Parse `$ARGUMENTS` for a `--phase` flag:
+Parse `$ARGUMENTS` tìm flag `--phase`:
 
-| Flag | Meaning |
+| Flag | Ý nghĩa |
 |---|---|
-| `--phase=ui` | FE Phase 1 — generate UI + mock API layer from System BDD contract |
-| `--phase=integration` | FE Phase 2 — replace mock adapter with real API calls from tech docs |
-| *(none)* | Default — full implementation (BE or full-stack without mock split) |
-
-**If `--phase` is set — confirm platform:**
-Read `@trace.platform` from the feature file header.
-- If `system` → warn: "`--phase` flag is not applicable for system BDD (BE-facing). Proceeding with default mode." Treat as no flag.
-- If `web` or `app` → continue with phase logic below.
-
-**If `--phase=ui`:**
-Resolve the **mock shape source** (hybrid — prefer the real contract, fall back to System BDD):
-- **BE contract** `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md` — if it exists, the mock adapter's port/DTO **shape** (request/response fields, types, error codes) comes from here → `mock_source = contract`. Most accurate; no shape rework at integration.
-- **System BDD** `{paths.specs_dir}/{domain}/{prd-slug}/bdd/system/{TICKET-ID}*.feature` — always load `Then` clauses for **behavior + fixture values**. If no BE contract, the shape is inferred from these too → `mock_source = system-bdd`, and WARN:
+| `--phase=ui` | FE Phase 1 — sinh UI + layer mock API từ System BDD contract |
+| `--phase=integration` | FE Phase 2 — thay mock adapter bằng lời gọi API thật từ tech docs |
+| *(không có)* | Default — full implementation (BE hoặc full-stack không tách mock) |
+
+**Nếu `--phase` được set — xác nhận platform:**
+Đọc `@trace.platform` từ header file feature.
+- Nếu `system` → cảnh báo: "Flag `--phase` không áp dụng cho system BDD (hướng BE). Tiếp tục với chế độ default." Coi như không có flag.
+- Nếu `web` hoặc `app` → tiếp tục logic phase bên dưới.
+
+**Nếu `--phase=ui`:**
+Phân giải **nguồn shape của mock** (hybrid — ưu tiên contract thật, fallback về System BDD):
+- **BE contract** `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md` — nếu tồn tại, **shape** port/DTO của mock adapter (field request/response, type, error code) lấy từ đây → `mock_source = contract`. Chính xác nhất; không phải rework shape lúc integration.
+- **System BDD** `{paths.specs_dir}/{domain}/{prd-slug}/bdd/system/{TICKET-ID}*.feature` — luôn nạp mệnh đề `Then` để lấy **behavior + giá trị fixture**. Nếu không có BE contract, shape cũng được infer từ đây → `mock_source = system-bdd`, và WARN:
   ```
-  ⚠ BE contract not found — mock shape inferred from System BDD only.
-    System BDD describes behavior, not full request/response shape — the mock
-    may differ from the real API; expect adjustment at --phase=integration.
-    (Recommended: have BE publish {prd-slug}/tech-docs/{UC-ID}-tech-design.md first for an accurate mock.)
+  ⚠ Không tìm thấy BE contract — shape mock được infer chỉ từ System BDD.
+    System BDD mô tả behavior, không phải full request/response shape — mock
+    có thể khác API thật; dự kiến điều chỉnh ở --phase=integration.
+    (Khuyến nghị: để BE publish {prd-slug}/tech-docs/{UC-ID}-tech-design.md trước để có mock chính xác.)
   ```
-- If System BDD is also missing → warn "System BDD not found — mock layer will use placeholder fixtures." Continue.
+- Nếu System BDD cũng thiếu → cảnh báo "Không tìm thấy System BDD — layer mock sẽ dùng fixture placeholder." Tiếp tục.
 
-Store `mock_source` (`contract` | `system-bdd`) for the mock tags below.
+Lưu `mock_source` (`contract` | `system-bdd`) cho các tag mock bên dưới.
 
-**Then run the Figma Dev Mode MCP Check below** before generating any UI — the Design
-Spec's frame links are the visual contract, and the local MCP reads them with far more
-fidelity than a plain web link.
+**Rồi chạy Figma Dev Mode MCP Check bên dưới** trước khi sinh UI — link frame của Design
+Spec là visual contract, và MCP local đọc chúng với độ trung thực cao hơn nhiều so với link web trần.
 
 ---
 
-## Figma Dev Mode MCP Check *(FE/App UI generation only)*
+## Figma Dev Mode MCP Check *(chỉ sinh UI FE/App)*
 
-*Run this only when `platform` is `web`/`app` AND generating UI (`--phase=ui`, or default
-mode for an FE/App feature). Skip entirely for BE / `system` platform.*
+*Chỉ chạy khi `platform` là `web`/`app` VÀ đang sinh UI (`--phase=ui`, hoặc chế độ default
+cho feature FE/App). Bỏ qua hoàn toàn với BE / platform `system`.*
 
-The PO authored the Design Spec from **Figma web links** (read-only, limited). For
-codegen, the **local Figma Dev Mode MCP server** (built into the Figma **desktop app**)
-gives far more: exact layout, design **variables/tokens**, **Code Connect** component
-mappings, selection context, and code snippets — things a web URL alone cannot return.
+PO viết Design Spec từ **link web Figma** (read-only, giới hạn). Để codegen,
+**Figma Dev Mode MCP server local** (tích hợp trong **app desktop** Figma) cho nhiều hơn
+nhiều: layout chính xác, **variable/token** design, mapping component **Code Connect**,
+selection context, và code snippet — những thứ một URL web đơn không trả về được.
 
-**Step 1 — Detect the local MCP.** Check whether a Figma Dev Mode MCP server is connected
-(a `get_design_context` / `get_code` style Figma tool is available via MCP).
+**Step 1 — Phát hiện MCP local.** Kiểm tra xem Figma Dev Mode MCP server có kết nối không
+(một Figma tool kiểu `get_design_context` / `get_code` sẵn có qua MCP).
 
-**Step 2 — If NOT connected → suggest the dev enable it, then wait:**
+**Step 2 — Nếu CHƯA kết nối → gợi ý dev bật nó, rồi chờ:**
 
 ```
-🎨 Figma Dev Mode MCP not detected.
-   For accurate FE code (real tokens, components, Code Connect), use the LOCAL server:
-
-   1. Open the Figma DESKTOP app (not the browser)
-   2. Open the file/frame for this feature
-   3. Enable the Dev Mode MCP server:
-        Figma menu → Preferences → "Enable Dev Mode MCP Server"
-        (requires Dev or Full seat; server runs at http://127.0.0.1:3845)
-   4. Make sure this MCP server is added in your Claude Code MCP config
-   5. Select the frame for the screen you're implementing, then continue
-
-   Type C to continue once enabled, or S to skip (fall back to web links + text spec).
+🎨 Không phát hiện Figma Dev Mode MCP.
+   Để có code FE chính xác (token, component, Code Connect thật), dùng server LOCAL:
+
+   1. Mở app Figma DESKTOP (không phải browser)
+   2. Mở file/frame của feature này
+   3. Bật Dev Mode MCP server:
+        Menu Figma → Preferences → "Enable Dev Mode MCP Server"
+        (cần Dev hoặc Full seat; server chạy ở http://127.0.0.1:3845)
+   4. Đảm bảo MCP server này đã được thêm vào config MCP của Claude Code
+   5. Chọn frame của màn bạn đang implement, rồi tiếp tục
+
+   Gõ C để tiếp tục khi đã bật, hoặc S để skip (fallback về link web + text spec).
 ```
 
-- `C` → re-detect; if now connected → proceed using the local MCP.
-- `S` → proceed in **fallback mode**: use the Design Spec's web frame links + textual spec
-  only; add a ⚠️ note in the final report that UI was generated without local Figma fidelity.
+- `C` → phát hiện lại; nếu giờ đã kết nối → tiếp tục dùng MCP local.
+- `S` → tiếp tục ở **fallback mode**: chỉ dùng link frame web + text spec của Design Spec;
+  thêm note ⚠️ trong report cuối rằng UI được sinh mà không có độ trung thực Figma local.
 
-**Step 3 — When the local MCP IS connected:** for each screen being implemented, pull the
-selected frame via the Figma MCP and ground the UI on the returned layout, variables, and
-Code Connect mappings. Prefer Code-Connect-mapped components over inventing markup; use the
-real token names, not hardcoded values.
+**Step 3 — Khi MCP local ĐÃ kết nối:** với mỗi màn đang implement, pull frame được chọn
+qua Figma MCP và ground UI trên layout, variable, và mapping Code Connect trả về. Ưu tiên
+component được map Code-Connect hơn là bịa markup; dùng tên token thật, không phải giá trị hardcode.
 
-**If `--phase=integration`:**
-Resolve the design that drives the adapter (two layers):
-- **FE tech-design** (preferred — the port→endpoint→DTO mapping): `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md` §4, produced by `/generate-tech-docs` (FE path).
-- **BE API contract** (endpoint/shape source): `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md`.
+**Nếu `--phase=integration`:**
+Phân giải design điều khiển adapter (hai tầng):
+- **FE tech-design** (ưu tiên — mapping port→endpoint→DTO): `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md` §4, sinh bởi `/generate-tech-docs` (path FE).
+- **BE API contract** (nguồn endpoint/shape): `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md`.
 
-Read `@trace.status` of whichever drives the adapter (the FE doc if present, else the BE contract).
-If `draft` or `in-review` → warn:
+Đọc `@trace.status` của cái nào điều khiển adapter (doc FE nếu có, else BE contract).
+Nếu `draft` hoặc `in-review` → cảnh báo:
 ```
-⚠ Tech design for {UC-ID} ({platform}) is {status}.
-  Contract / adapter mapping may still change.
-  Proceeding — ensure BE endpoint is deployed or confirm the mapping manually.
+⚠ Tech design cho {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.
 ```
-If the FE tech-design is **missing** → warn: "No FE tech-design found — falling back to the BE contract directly (adapter mapping inferred). Recommended: run `/generate-tech-docs {web|app .feature}` first."
-Locate existing mock adapter from `--phase=ui` run (search for `{UC-ID}MockApiAdapter` in `{paths.src_dir}/{domain}/`).
-If not found → warn: "Mock adapter not found — generating real API adapter from scratch using tech-doc contract."
+Nếu FE tech-design **thiếu** → cảnh báo: "Không tìm thấy FE tech-design — fallback về BE contract trực tiếp (mapping adapter được infer). Khuyến nghị: chạy `/generate-tech-docs {web|app .feature}` trước."
+Đị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."
 
 ---
 
 ## Read Trace State
 
-Read `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv` if it exists. For each scenario row, note its current `status`:
+Đọc `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv` nếu tồn tại. Với mỗi scenario row, ghi nhận `status` hiện tại:
 
-| Status | Meaning | Action in this run |
+| Status | Ý nghĩa | Hành động trong lần chạy này |
 |--------|---------|-------------------|
-| `UNTRACKED` | `implemented_by == —` | Generate — scenario has no code yet |
-| `DRIFT` | `spec_ver != gen_ver` | Regenerate — scenario updated since last codegen |
-| `OK` | implemented + tested | Skip unless explicitly re-generating |
-| `GAP` | implemented, no tests | Skip codegen — already coded; run `/dev-gen-test` instead |
+| `UNTRACKED` | `implemented_by == —` | Generate — scenario chưa có code |
+| `DRIFT` | `spec_ver != gen_ver` | Regenerate — scenario đã cập nhật từ lần codegen trước |
+| `OK` | đã implement + test | Skip trừ khi gen lại tường minh |
+| `GAP` | đã implement, chưa test | Skip codegen — đã code rồi; chạy `/dev-gen-test` thay vì |
 
-Use these statuses to populate the **Scenarios** count in the CHECKPOINT plan (`{X} new, {Y} drifted, {Z} synced-skip`).
-If `.tsv` does not exist → treat all scenarios as `UNTRACKED`.
+Dùng các status này để điền số **Scenarios** trong plan CHECKPOINT (`{X} new, {Y} drifted, {Z} synced-skip`).
+Nếu `.tsv` không tồn tại → coi mọi scenario là `UNTRACKED`.
 
 ---
 
 ## File Scan
 
-Before generating, determine which files will be needed for this UC's scenarios. Check whether each file already exists on disk.
+Trước khi sinh, xác định file nào cần cho các scenario của UC này. Kiểm tra mỗi file đã tồn tại trên disk chưa.
 
-Classify each file:
+Phân loại mỗi file:
 
-| Status | Meaning | Action |
+| Status | Ý nghĩa | Hành động |
 |--------|---------|--------|
-| `CREATE` | File does not exist | Generate full new file |
-| `EXTEND` | File exists, new methods needed | Add new methods only — do NOT rewrite existing code |
-| `SKIP` | File exists and already covers all UC scenarios | Leave untouched |
+| `CREATE` | File chưa tồn tại | Sinh file mới đầy đủ |
+| `EXTEND` | File tồn tại, cần method mới | Chỉ thêm method mới — KHÔNG viết lại code có sẵn |
+| `SKIP` | File tồn tại và đã phủ tất cả scenario của UC | Để nguyên |
 
-> **EXTEND rule:** Read the existing file fully. Locate the correct class/interface. Add only the methods required by `{UC-ID}` scenarios. Preserve all existing methods, fields, and annotations exactly as-is. Attach `@trace.implements={UC-ID}-SC{N}` on each new method.
+> **Quy tắc EXTEND:** Đọc file có sẵn đầy đủ. Định vị đúng class/interface. Chỉ thêm các method mà scenario `{UC-ID}` cần. Giữ nguyên mọi method, field, annotation hiện có y như cũ. Gắn `@trace.implements={UC-ID}-SC{N}` lên mỗi method mới.
 
 ---
 
 ## CHECKPOINT — Code Generation Plan
 
-Before generating any code, show:
+Trước khi sinh code, hiện:
 
 ```
 Code Generation Plan — {UC-ID}
 ──────────────────────────────────────────────────────
 Feature  : {name}
-Ticket   : {TICKET_ID if known}
+Ticket   : {TICKET_ID nếu biết}
 Domain   : {domain}
-UC       : {UC-ID} only  ← other feature files in this folder are NOT read
+UC       : chỉ {UC-ID}  ← các file feature khác trong folder này KHÔNG được đọc
 Tech     : {language} / {framework}
-Phase    : {UI — mock layer | Integration — real API | Default — full}   ← omit if no --phase flag
+Phase    : {UI — mock layer | Integration — real API | Default — full}   ← bỏ nếu không có flag --phase
 Scenarios: {N} total ({X} new, {Y} drifted, {Z} synced-skip)
-Layer    : {from CLAUDE.md §2}
+Layer    : {từ CLAUDE.md §2}
 
 Files:
-  CREATE  {N} new files
+  CREATE  {N} file mới
     + {path/FileName.ext}
-  EXTEND  {M} existing files  (add methods only)
-    ~ {path/FileName.ext}  — adding: {methodA}, {methodB}
-  SKIP    {K} files  (no change needed)
+  EXTEND  {M} file có sẵn  (chỉ thêm method)
+    ~ {path/FileName.ext}  — thêm: {methodA}, {methodB}
+  SKIP    {K} file  (không cần đổi)
     = {path/FileName.ext}
 ──────────────────────────────────────────────────────
 Proceed? (Y/N)
 ```
 
-Wait for explicit "Y" before generating.
+Chờ "Y" rõ ràng trước khi sinh.
 
 ## Branch
 ```bash
 git checkout -b feature/{TICKET_ID}-{slug}
 ```
 
-## Generate (layer order from CLAUDE.md §2)
+## Generate (thứ tự layer từ CLAUDE.md §2)
 
-Default order (override from CLAUDE.md if different):
-DTOs → Entity/Model → Repository → Service interface → Service impl → Facade (if applicable) → Controller
+Thứ tự mặc định (override từ CLAUDE.md nếu khác):
+DTOs → Entity/Model → Repository → Service interface → Service impl → Facade (nếu áp dụng) → Controller
 
-**For `CREATE` files:** generate the full file.
+**Với file `CREATE`:** sinh file đầy đủ.
 
-**For `EXTEND` files:** open the existing file → add only the new methods for `{UC-ID}` → do not touch anything else.
+**Với file `EXTEND`:** mở file có sẵn → chỉ thêm method mới cho `{UC-ID}` → không đụng gì khác.
 
-**Traceability tags on controller/handler (adapt to your language's comment syntax):**
+**Tag traceability trên controller/handler (theo cú pháp comment của ngôn ngữ bạn):**
 ```
 @trace.implements={UC-ID}-SC{N}
-@trace.prd_version={read @trace.prd_version from the .feature file header}
-@trace.bdd_version={read @trace.bdd_version from the .feature file header}
-@trace.tech_doc_revision={read @trace.revision from tech-doc header, or omit if no tech-doc}
+@trace.prd_version={đọc @trace.prd_version từ header file .feature}
+@trace.bdd_version={đọc @trace.bdd_version từ header file .feature}
+@trace.tech_doc_revision={đọc @trace.revision từ header tech-doc, hoặc bỏ nếu không có tech-doc}
 @trace.source={paths.specs_dir}/{domain}/{prd-slug}/bdd/{UC-ID}-{slug}.feature
 ```
 
-`@trace.prd_version` records which PRD version this code was written against.
-`@trace.bdd_version` records which BDD version this code was generated from.
-`@trace.tech_doc_revision` records which tech-design revision this code follows.
-`/validate-traces` will flag drift if any upstream artifact is updated to a newer version.
+`@trace.prd_version` ghi code này được viết theo version PRD nào.
+`@trace.bdd_version` ghi code này được sinh từ version BDD nào.
+`@trace.tech_doc_revision` ghi code này theo revision tech-design nào.
+`/validate-traces` sẽ gắn cờ drift nếu bất kỳ artifact upstream nào được cập nhật lên version mới hơn.
 
-> **Entry-point rule:** `@trace.implements` must appear on the **entry-point layer** as defined in `CLAUDE.md §2`. For REST APIs → Controller. For event-driven modules → event handler / consumer class. For context-engineering → the prompt orchestration function. Never put it only on an inner layer.
+> **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.
 
-### Test Selectors — emit stable element IDs *(FE/App UI only)*
+### Test Selectors — emit element ID ổn định *(chỉ UI FE/App)*
 
-*Applies when `platform` is `web`/`app` and generating UI (`--phase=ui`, or default FE/App mode). Skip for BE.*
+*Áp dụng khi `platform` là `web`/`app` và đang sinh UI (`--phase=ui`, hoặc chế độ default FE/App). Bỏ qua với BE.*
 
-Every **actionable** element (button, input, link, select, toggle, form-submit) MUST carry a **stable test-id** so QC locates it directly (no runtime scan):
+Mỗi element **có action** (button, input, link, select, toggle, form-submit) PHẢI mang một **test-id ổn định** để QC định vị trực tiếp (không scan runtime):
 
-1. **Source the id.** If the FE tech-design `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md` exists, take ids **verbatim** from its §2b Test Selectors table (the contract). If it does not exist yet (e.g. `--phase=ui` before the FE tech-design), **generate ids by the convention** `{uc-lower}-{screen}-{element}-{type}` (e.g. `ft001-login-submit-btn`) so QC still has stable handles — they will be reconciled to the tech-design's §2b at integration.
-2. **Emit via the platform attribute** (from `@trace.testid_attr`, or by module):
+1. **Nguồn id.** Nếu FE tech-design `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md` tồn tại, lấy id **nguyên văn** từ bảng §2b Test Selectors của nó (contract). Nếu chưa tồn tại (vd `--phase=ui` trước FE tech-design), **sinh id theo quy ước** `{uc-lower}-{screen}-{element}-{type}` (vd `ft001-login-submit-btn`) để QC vẫn có handle ổn định — chúng sẽ được đối chiếu với §2b của tech-design lúc integration.
+2. **Emit qua attribute platform** (từ `@trace.testid_attr`, hoặc theo module):
    - web (`react`/`nextjs`/`vue`/`angular`) → `data-testid="..."`
    - React Native → `testID="..."`
-   - Flutter → `Key('...')` (+ `Semantics(identifier: '...')` where the action needs it)
+   - Flutter → `Key('...')` (+ `Semantics(identifier: '...')` khi action cần)
    - native iOS → `accessibilityIdentifier = "..."`
-3. Only actionable elements; do not spam ids on static text. Keep ids identical to the tech-design map so QC Page Objects match on the first try.
-4. **Reused catalog component?** Pass the id via its **forwarding prop** (see the catalog `## Test-ID Forwarding` section — e.g. `<Button testId="ft001-login-submit-btn">`), not a raw attribute. If the component does not forward a test-id, or you are backfilling **existing/brownfield** screens (not freshly generated here), that is `/map-testids {UC-ID}`'s job — run it instead of editing shared components inline.
+3. Chỉ element có action; đừng spam id lên text tĩnh. Giữ id giống hệt map của tech-design để QC Page Object khớp ngay lần đầu.
+4. **Component catalog tái dùng?** Truyền id qua **forwarding prop** của nó (xem section catalog `## Test-ID Forwarding` — vd `<Button testId="ft001-login-submit-btn">`), không phải attribute thô. Nếu component không forward test-id, hoặc bạn đang backfill màn **existing/brownfield** (không phải sinh mới ở đây), đó là việc của `/map-testids {UC-ID}` — chạy nó thay vì sửa component dùng chung inline.
 
-## Mock API Layer (`--phase=ui` only)
+## Mock API Layer (chỉ `--phase=ui`)
 
-*Skip this section entirely if `--phase` is not `ui`.*
+*Bỏ qua hoàn toàn section này nếu `--phase` không phải `ui`.*
 
-Build the mock from the `mock_source` resolved in Phase Detection — **shape** from the BE contract when present, **fixture values + behavior** always from System BDD `Then` clauses:
+Dựng mock từ `mock_source` đã phân giải ở Phase Detection — **shape** từ BE contract khi có, **giá trị fixture + behavior** luôn từ mệnh đề `Then` của System BDD:
 
-1. **Define the port shape** `{UC-ID}ApiPort` (request/response DTOs + error codes):
-   - `mock_source = contract` → field names / types / error codes taken **verbatim from the BE contract** §2 (API Endpoints) / §3 (Data Model) — the real shape.
-   - `mock_source = system-bdd` → shape **inferred** from System BDD `Then` clauses (provisional — see warning above).
-2. **Extract fixture data** per scenario from System BDD `Then` clauses — success + error responses (BDD is the source of truth for *values / behavior*, regardless of shape source).
-3. **Generate mock adapter** at `{paths.src_dir}/{domain}/{UC-ID}MockApiAdapter.{ext}`:
-   - Implements interface `{UC-ID}ApiPort` (same interface the real adapter will implement)
-   - Each method returns fixture data matching the BDD `Then` clause, in the port shape
-   - Include both success and error states (map to error scenarios in BDD)
-   - Traceability tags:
+1. **Định nghĩa shape port** `{UC-ID}ApiPort` (DTO request/response + error code):
+   - `mock_source = contract` → tên field / type / error code lấy **nguyên văn từ BE contract** §2 (API Endpoints) / §3 (Data Model) — shape thật.
+   - `mock_source = system-bdd` → shape **infer** từ mệnh đề `Then` của System BDD (tạm — xem cảnh báo ở trên).
+2. **Trích dữ liệu fixture** theo từng scenario từ mệnh đề `Then` của System BDD — response success + error (BDD là source of truth cho *giá trị / behavior*, bất kể nguồn shape).
+3. **Sinh mock adapter** tại `{paths.src_dir}/{domain}/{UC-ID}MockApiAdapter.{ext}`:
+   - Implements interface `{UC-ID}ApiPort` (cùng interface mà real adapter sẽ implement)
+   - Mỗi method trả về fixture data khớp mệnh đề `Then` của BDD, theo shape của port
+   - Gồm cả trạng thái success và error (map sang các error scenario trong BDD)
+   - Tag traceability:
      ```
      @trace.mock_for={UC-ID}
      @trace.mock_source={contract | system-bdd}
      @trace.system_bdd={paths.specs_dir}/{domain}/{prd-slug}/bdd/system/{UC-ID}*.feature
-     {@trace.be_contract={UC-ID}-tech-design.md   # only when mock_source=contract}
+     {@trace.be_contract={UC-ID}-tech-design.md   # chỉ khi mock_source=contract}
      ```
-4. **Wire into service/hook layer** via environment flag or DI:
+4. **Wire vào layer service/hook** qua environment flag hoặc DI:
    ```
    const adapter = IS_MOCK ? new {UC-ID}MockApiAdapter() : new {UC-ID}ApiAdapter()
    ```
-   - `IS_MOCK` defaults to `true` in development/test env until real adapter is generated.
+   - `IS_MOCK` mặc định `true` ở môi trường development/test cho tới khi real adapter được sinh.
 
-> Tester uses the mock adapter to test all FE scenarios without waiting for BE to **deploy**.
-> Shape comes from the BE contract when available (accurate, no integration rework); else from System BDD (provisional — adjust at `--phase=integration`). Fixture *values* always come from System BDD — BDD is the source of truth for behavior.
+> Tester dùng mock adapter để test mọi FE scenario mà không cần đợi BE **deploy**.
+> Shape lấy từ BE contract khi có (chính xác, không rework integration); else từ System BDD (tạm — điều chỉnh ở `--phase=integration`). Giá trị fixture luôn từ System BDD — BDD là source of truth cho behavior.
 
 ---
 
-## Integration Phase (`--phase=integration` only)
+## Integration Phase (chỉ `--phase=integration`)
 
-*Skip this section entirely if `--phase` is not `integration`.*
+*Bỏ qua hoàn toàn section này nếu `--phase` không phải `integration`.*
 
-1. **Read the integration design.** Prefer the FE tech-design §4 (port→endpoint→DTO→error mapping) at `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md`, using the BE API contract `{UC-ID}-tech-design.md` as the endpoint / request-response / error-code source. If no FE tech-design exists, extract endpoints + shapes + error codes directly from the BE contract.
-2. **Read existing mock adapter** interface (`{UC-ID}ApiPort`) from the `--phase=ui` output.
-3. **Generate real API adapter** at `{paths.src_dir}/{domain}/{UC-ID}ApiAdapter.{ext}`:
-   - Implements the same `{UC-ID}ApiPort` interface as mock adapter
-   - Makes real HTTP calls to endpoints from tech-doc contract
-   - Maps response fields to the same shapes the mock adapter returned
-   - Traceability tags:
+1. **Đọc integration design.** Ưu tiên FE tech-design §4 (mapping port→endpoint→DTO→error) tại `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md`, dùng BE API contract `{UC-ID}-tech-design.md` làm nguồn endpoint / request-response / error-code. Nếu không có FE tech-design, trích endpoint + shape + error code trực tiếp từ BE contract.
+2. **Đọc mock adapter có sẵn** interface (`{UC-ID}ApiPort`) từ output `--phase=ui`.
+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
+   - Map field response sang cùng shape mà mock adapter trả về
+   - Tag traceability:
      ```
      @trace.implements={UC-ID}-SC{N}
-     @trace.tech_doc_revision={read from tech-doc header}
+     @trace.tech_doc_revision={đọc từ header tech-doc}
      ```
-4. **Flip wire-up**: switch DI binding / env flag so service/hook uses `{UC-ID}ApiAdapter` (real) instead of mock.
-5. **Do NOT delete mock adapter** — keep it for unit testing.
+4. **Lật wire-up**: chuyển DI binding / env flag để service/hook dùng `{UC-ID}ApiAdapter` (thật) thay vì mock.
+5. **KHÔNG xoá mock adapter** — giữ lại cho unit test.
 
 ---
 
-## Self-Review (3 rounds)
-- [ ] Every scenario has a corresponding endpoint
-- [ ] @trace.implements on every endpoint
-- [ ] Architecture layer rules respected (CLAUDE.md §2)
-- [ ] Error handling matches CLAUDE.md §5
-- [ ] No magic numbers, no debug logging
+## Self-Review (3 vòng)
+- [ ] Mỗi scenario có endpoint tương ứng
+- [ ] @trace.implements trên mọi endpoint
+- [ ] Tôn trọng quy tắc layer kiến trúc (CLAUDE.md §2)
+- [ ] Error handling khớp CLAUDE.md §5
+- [ ] Không magic number, không debug logging
 
 ## Build Verify
 ```bash
-{conventions.build_command}   # from project-context.yaml, max 3 retries
+{conventions.build_command}   # từ project-context.yaml, tối đa 3 retry
 ```
 
 ## Write Trace State
 
-Update `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv` — for each implemented scenario, find the existing row by `sc_id` and update only these columns. *(Umbrella + `spec_source`: `trace_dir` resolves to `{spec_source}/.trace` — this command runs from `service_root` but writes the trace row into the **spec repo** (cross-repo); commit/push the spec submodule for the trace update, alongside the 2-tier code push.)*
+Cập nhật `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv` — với mỗi scenario đã implement, tìm row có sẵn theo `sc_id` và chỉ cập nhật các cột sau. *(Umbrella + `spec_source`: `trace_dir` phân giải về `{spec_source}/.trace` — lệnh này chạy từ `service_root` nhưng ghi trace row vào **spec repo** (liên-repo); commit/push spec submodule cho lần cập nhật trace, cùng với push code 2 tầng.)*
 
-| Column | Value |
+| Cột | Giá trị |
 |--------|-------|
-| `gen_ver` | copy `spec_ver` from the current `.tsv` row (= scenario version at time of codegen) |
+| `gen_ver` | copy `spec_ver` từ row `.tsv` hiện tại (= version scenario tại thời điểm codegen) |
 | `implemented_by` | `{ControllerClass}.{methodName}` |
-| `bdd_version` | `@trace.bdd_version` from `.feature` header |
-| `tech_doc_revision` | `@trace.revision` from the **BE** contract `{UC-ID}-tech-design.md`, or `—` if none |
-| `fe_tech_doc_revision` | `@trace.revision` from the **FE** tech-design `{UC-ID}-tech-design-{platform}.md` when generating FE with `--phase=integration` (the doc whose §4 drove this adapter); `—` for BE, or for FE `--phase=ui` / no FE tech-design |
-| `fe_phase` | `ui` if `--phase=ui` \| `integrated` if `--phase=integration` \| `—` if no phase flag |
-| `last_updated` | today `YYYY-MM-DD` |
+| `bdd_version` | `@trace.bdd_version` từ header `.feature` |
+| `tech_doc_revision` | `@trace.revision` từ **BE** contract `{UC-ID}-tech-design.md`, hoặc `—` nếu không có |
+| `fe_tech_doc_revision` | `@trace.revision` từ **FE** tech-design `{UC-ID}-tech-design-{platform}.md` khi sinh FE với `--phase=integration` (doc có §4 điều khiển adapter này); `—` cho BE, hoặc cho FE `--phase=ui` / không có FE tech-design |
+| `fe_phase` | `ui` nếu `--phase=ui` \| `integrated` nếu `--phase=integration` \| `—` nếu không có flag phase |
+| `last_updated` | hôm nay `YYYY-MM-DD` |
 
-Leave all other columns (`sc_title`, `spec_ver`, `prd_version`, `prd_status`, `uc_status`, `test_count`, `test_classes`, `dev_selftest`, `dev_selftest_at`, `qc_status`, `qc_run_at`, `qc_owner`, `qc_blocked_by`) unchanged.
-`status` is computed by `/validate-traces` — do not set here.
+Giữ nguyên mọi cột khác (`sc_title`, `spec_ver`, `prd_version`, `prd_status`, `uc_status`, `test_count`, `test_classes`, `dev_selftest`, `dev_selftest_at`, `qc_status`, `qc_run_at`, `qc_owner`, `qc_blocked_by`).
+`status` được tính bởi `/validate-traces` — không set ở đây.
 
 ## Refresh Panel Mirror
 {{include:steps/trace-mirror.md}}
@@ -324,26 +322,26 @@ git commit -m "{commit_format}: {description}"
 {{include:steps/report-footer.md}}
 
 ```
-/generate-code Complete — {UC-ID}
+/generate-code Hoàn tất — {UC-ID}
 Files: created={N}, extended={M}, skipped={K} | Build: SUCCESS
 Branch: feature/{TICKET_ID}-{slug}
 Phase    : {UI (mock layer) | Integration (real API) | Default (full)}
 fe_phase : {ui | integrated | —}
-Figma    : {local Dev Mode MCP (grounded) | ⚠️ web links + text spec only (no local MCP) | n/a for BE}   ← FE/App UI only
+Figma    : {Dev Mode MCP local (grounded) | ⚠️ chỉ link web + text spec (không có MCP local) | n/a cho BE}   ← chỉ UI FE/App
 
 Next:
-  --phase=ui done:
-    → Notify tester: FE is testable via mock adapter
-    → Collect BE sign-offs → /review-tech-docs {tech-design-file}
-    → When BE ready → /generate-code {feature-file} --phase=integration
+  --phase=ui xong:
+    → Báo tester: FE test được qua mock adapter
+    → Thu sign-off BE → /review-tech-docs {tech-design-file}
+    → Khi BE sẵn sàng → /generate-code {feature-file} --phase=integration
 
-  --phase=integration done:
-    → /review-code {UC-ID}   ← code review required
-    → /dev-gen-test {UC-ID}  ← integration test suite
+  --phase=integration xong:
+    → /review-code {UC-ID}   ← cần code review
+    → /dev-gen-test {UC-ID}  ← bộ integration test
 
-  Default (no phase flag):
-    → /review-code {UC-ID}   ← code review required before tests
+  Default (không có flag phase):
+    → /review-code {UC-ID}   ← cần code review trước khi test
     → /dev-gen-test {UC-ID}
 
-📊 Living Docs: run /validate-traces (or /sync) to push this trace to the spec-module dashboard.
+📊 Living Docs: chạy /validate-traces (hoặc /sync) để push trace này lên dashboard spec-module.
 ```