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

package/commands/generate-tech-docs.tmpl

@@ -1,29 +1,29 @@
-# /generate-tech-docs — Generate Technical Design Document
+# /generate-tech-docs — Sinh Technical Design Document
 
 ## 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 bare UC-ID, locate the feature by globbing `{paths.specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` (wildcard `*` for the unknown prd-slug, recursive `**` for the `web/`·`app/`·`system/` subfolders — a BE tech-doc resolves from the `system/` BDD); take `domain` + `prd_slug` from the matched path. All outputs below then use that resolved `{prd-slug}`.*
+*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 trần, định vị feature bằng cách glob `{paths.specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` (wildcard `*` cho prd-slug chưa biết, `**` đệ quy cho thư mục con `web/`·`app/`·`system/` — BE tech-doc phân giải từ BDD `system/`); lấy `domain` + `prd_slug` từ path khớp. Mọi output bên dưới dùng `{prd-slug}` đã phân giải đó.*
 
-**Quality Gate**: Before generating, check the BDD findings file:
+**Quality Gate**: Trước khi sinh, kiểm tra file BDD findings:
 
-1. Look for `{paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml`.
-2. **If file does not exist** → warn and ask:
+1. Tìm `{paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml`.
+2. **Nếu file không tồn tại** → cảnh báo và hỏi:
    ```
-   ⚠️  /review-context has not been run for this feature file.
-   Recommended: run /review-context {feature-file} first to verify BDD quality.
-   Continue without review? (Y/N)
+   ⚠️  /review-context chưa chạy cho file feature này.
+   Khuyến nghị: chạy /review-context {feature-file} trước để kiểm tra chất lượng BDD.
+   Tiếp tục mà không review? (Y/N)
    ```
-   - Y → proceed (accept risk)
-   - N → stop; run `/review-context {feature-file}` first
-3. **If file exists** → check for unresolved `status: "pending"` critical findings.
-   If any found → **HALT** and print:
+   - Y → tiếp tục (chấp nhận rủi ro)
+   - N → dừng; chạy `/review-context {feature-file}` trước
+3. **Nếu file tồn tại** → kiểm tra các finding critical `status: "pending"` chưa giải quyết.
+   Nếu có → **HALT** và in:
    ```
    ❌ Quality Gate Failed — {feature-file}
-   Unresolved critical BDD findings detected.
-   Run: /review-context --fix {feature-file}   ← auto-fix what's possible
-   Then: /review-context --resume {feature-file}  ← apply remaining accepted findings
-   Then re-run: /generate-tech-docs {feature-file}
+   Phát hiện finding BDD critical chưa giải quyết.
+   Chạy: /review-context --fix {feature-file}   ← auto-fix những gì có thể
+   Rồi: /review-context --resume {feature-file}  ← áp dụng các finding được chấp nhận còn lại
+   Rồi chạy lại: /generate-tech-docs {feature-file}
    ```
 
 ## Context
@@ -31,74 +31,74 @@
 
 ---
 
-## Step 0 — Detect Platform & Route Output
+## Step 0 — Phát hiện Platform & Route Output
 
-Read `@trace.platform` from the feature file header (`web` | `app` | `system`). If absent, fall back to `platform_type` from context (`web-frontend`/`mobile` → FE; `backend` → BE).
+Đọc `@trace.platform` từ header file feature (`web` | `app` | `system`). Nếu vắng, fallback về `platform_type` từ context (`web-frontend`/`mobile` → FE; `backend` → BE).
 
 | Platform | `active_tech_design` | Output file |
 |----------|----------------------|-------------|
-| `system` / backend | **`be`** — the cross-team **API contract** (authoritative) | `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md` |
-| `web` / `app` (web-frontend / mobile) | **`fe`** — the **client technical design** (consumes the BE contract) | `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md` |
+| `system` / backend | **`be`** — **API contract** liên team (authoritative) | `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md` |
+| `web` / `app` (web-frontend / mobile) | **`fe`** — **client technical design** (tiêu thụ BE contract) | `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md` |
 
-Store `active_tech_design` and `tech_design_path`. The `-{platform}` suffix (mirroring design-spec) keeps the FE doc from colliding with the BE contract — both live in the shared spec repo when `spec_source` is set.
+Lưu `active_tech_design` và `tech_design_path`. Hậu tố `-{platform}` (giống design-spec) giữ doc FE không đụng độ BE contract — cả hai sống trong spec repo dùng chung khi `spec_source` được set.
 
 ---
 
 ## Step 0.5 — FE/App Precondition Gate
 
-*Skip this entire step for BE (`active_tech_design = be`).*
+*Bỏ qua toàn bộ step này cho BE (`active_tech_design = be`).*
 
-An FE/App technical design is a **derived** artifact: its API-integration layer maps onto the locked BE contract, and its state/error model comes from the system behavior. Both upstream inputs MUST exist first — **HALT** if either is missing:
+Một FE/App technical design là artifact **dẫn xuất**: layer tích hợp API của nó map lên BE contract đã chốt, và state/error model đến từ system behavior. Cả hai input upstream PHẢI tồn tại trước — **HALT** nếu thiếu một trong hai:
 
-1. **System BDD** — locate `{paths.specs_dir}/{domain}/{prd-slug}/bdd/system/{TICKET-ID}*.feature`.
-   If not found → HALT:
+1. **System BDD** — định vị `{paths.specs_dir}/{domain}/{prd-slug}/bdd/system/{TICKET-ID}*.feature`.
+   Nếu không tìm thấy → HALT:
    ```
-   ❌ Cannot generate FE tech-design — System BDD not found for {TICKET-ID}.
-   The FE design needs the system-level (BE-facing) behavior first.
-   → PO/BE: /generate-bdd {prd-file}  (produces the `system/` platform BDD)
+   ❌ Không thể sinh FE tech-design — không tìm thấy System BDD cho {TICKET-ID}.
+   FE design cần behavior mức system (đối diện BE) trước.
+   → PO/BE: /generate-bdd {prd-file}  (sinh BDD platform `system/`)
    ```
-2. **BE tech-docs (API contract)** — locate the BE doc `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md` and read its `@trace.status`.
-   - Not found → HALT:
+2. **BE tech-docs (API contract)** — định vị doc BE `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md` và đọc `@trace.status` của nó.
+   - Không tìm thấy → HALT:
      ```
-     ❌ Cannot generate FE tech-design — BE API contract not found.
-     The FE integration layer maps to the BE contract; it must exist first.
-     → BE: /generate-tech-docs {system .feature} → /review-tech-docs (approve) → publish to spec repo
+     ❌ Không thể sinh FE tech-design — không tìm thấy BE API contract.
+     Layer tích hợp FE map tới BE contract; nó phải tồn tại trước.
+     → BE: /generate-tech-docs {system .feature} → /review-tech-docs (approve) → publish lên spec repo
      ```
-   - Found but `@trace.status` ≠ `approved` → WARN and ask:
+   - Tìm thấy nhưng `@trace.status` ≠ `approved` → WARN và hỏi:
      ```
-     ⚠️  BE contract {UC-ID}-tech-design.md is status: {status} (not approved) — it may still change.
-     Designing the FE integration against a non-final contract risks rework.
-     Continue anyway? (Y/N)
+     ⚠️  BE contract {UC-ID}-tech-design.md đang status: {status} (chưa approved) — nó còn có thể đổi.
+     Thiết kế FE integration dựa trên contract chưa chốt có rủi ro rework.
+     Vẫn tiếp tục? (Y/N)
      ```
-     - Y → proceed (accept risk) · N → stop, wait for BE to approve.
+     - Y → tiếp tục (chấp nhận rủi ro) · N → dừng, chờ BE approve.
 
-Store `system_bdd_path` and `be_contract_path` — they are the primary inputs for the FE §3/§4 below.
+Lưu `system_bdd_path` và `be_contract_path` — chúng là input chính cho FE §3/§4 bên dưới.
 
 ---
 
 ## Brownfield Check
 
-*BE (`active_tech_design = be`) only — for FE the "existing contract" is the BE doc loaded in Step 0.5.*
+*Chỉ BE (`active_tech_design = be`) — với FE thì "existing contract" là doc BE đã nạp ở Step 0.5.*
 
-Read the source `.feature` file header for `@trace.api_source`.
-Also check the source PRD Metadata table for `| **API Source** | existing |`.
+Đọc header file `.feature` nguồn tìm `@trace.api_source`.
+Cũng kiểm tra bảng Metadata của PRD nguồn tìm `| **API Source** | existing |`.
 
 | Value | Mode |
 |-------|------|
 | `existing` | **Reverse-document** — API đã tồn tại; mô tả lại as-is, note gaps, không cần design mới |
 | absent / other | **Greenfield** — thiết kế API từ đầu |
 
-Store `active_mode = {reverse-document | greenfield}`.
+Lưu `active_mode = {reverse-document | greenfield}`.
 
-If `active_mode = reverse-document` → load bảng "Existing API Contract" từ PRD làm input cho §2.
+Nếu `active_mode = reverse-document` → nạp bảng "Existing API Contract" từ PRD làm input cho §2.
 
 ---
 
 ## CHECKPOINT — Tech Design Plan
 
-Before generating, scan the feature file for scenario count, referenced BRs, and entities. Display the plan for the resolved `active_tech_design` and wait for Y:
+Trước khi sinh, quét file feature lấy số scenario, các BR tham chiếu, và entity. Hiện plan cho `active_tech_design` đã phân giải và chờ Y:
 
-**If `active_tech_design = be`:**
+**Nếu `active_tech_design = be`:**
 ```
 Tech Design Plan — {UC-ID}  (BE · API contract)
 ──────────────────────────────────────────────────────
@@ -110,12 +110,12 @@ Scenarios: {N} scenarios
 BDD ver  : {trace.bdd_version}
 Output   : {paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md
 
-Sections to generate:
+Section cần sinh:
   §1 Overview
   §2 API Endpoints   ({Reverse-document: mô tả lại từ PRD contract | Greenfield: infer từ scenarios})
-  §3 Data Model      ({entities from core-entities.md relevant to this UC})
+  §3 Data Model      ({entity từ core-entities.md liên quan UC này})
   §4 Service Flow
-  §5 Business Rules  ({N} BRs from feature header)
+  §5 Business Rules  ({N} BR từ header feature)
   §6 Error Handling
   §7 Database Changes
   §8 Caching Strategy
@@ -124,7 +124,7 @@ Sections to generate:
 Proceed? (Y/N)
 ```
 
-**If `active_tech_design = fe`:**
+**Nếu `active_tech_design = fe`:**
 ```
 Tech Design Plan — {UC-ID}  (FE · {platform} · client design)
 ──────────────────────────────────────────────────────
@@ -135,32 +135,32 @@ Inputs    : System BDD  → {system_bdd_path}
 Scenarios : {N} FE scenarios   |   BDD ver: {trace.bdd_version}
 Output    : {paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md
 
-Sections to generate:
-  §1 Overview            (FE scope of this UC)
-  §2 Component Architecture  (tree + reuse from figma-components catalog)
-  §2b Test Selectors     (stable test-id cho element có action — QC contract, attr theo platform)
+Section cần sinh:
+  §1 Overview            (scope FE của UC này)
+  §2 Component Architecture  (tree + reuse từ figma-components catalog)
+  §2b Test Selectors     (test-id ổn định cho element có action — QC contract, attr theo platform)
   §3 State Management    (store/slices/state shape ← System BDD Then-clauses)
-  §4 API Integration Layer   (port/adapter: each BE endpoint → FE service → DTO/model)
+  §4 API Integration Layer   (port/adapter: mỗi BE endpoint → FE service → DTO/model)
   §5 Routing / Navigation
   §6 Data Fetching & Client Caching  (query keys, invalidation, optimistic updates)
-  §7 Error & Loading States  (per scenario)
+  §7 Error & Loading States  (theo từng scenario)
   §8 Cross-Cutting       (auth token, i18n, feature flags)
-  {§9 Offline / platform specifics — app only}
+  {§9 Offline / platform specifics — chỉ app}
 ──────────────────────────────────────────────────────
 Proceed? (Y/N)
 ```
 
-Wait for explicit "Y" before generating.
+Chờ "Y" rõ ràng trước khi sinh.
 
 ---
 
 ## Generate
 
-Generate the document for the resolved `active_tech_design`.
+Sinh document cho `active_tech_design` đã phân giải.
 
 ### Path A — BE API contract  (`active_tech_design = be`)
 
-Write `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md`:
+Ghi `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md`:
 
 ```markdown
 # Technical Design — {UC-ID}: {Feature}
@@ -168,10 +168,10 @@ Write `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.m
 ---
 @trace.id: {UC-ID}
 @trace.domain: {domain}
-@trace.service: {read @trace.service from the .feature file header}
-@trace.module: {read @trace.module from the .feature file header}
+@trace.service: {đọc @trace.service từ header file .feature}
+@trace.module: {đọc @trace.module từ header file .feature}
 @trace.prd: {TICKET-ID}
-@trace.bdd_version: {read @trace.bdd_version from the .feature file header}
+@trace.bdd_version: {đọc @trace.bdd_version từ header file .feature}
 @trace.revision: 1
 @trace.status: draft
 @trace.api_source: {existing | —}
@@ -193,7 +193,7 @@ Write `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.m
 
 ## §3. Data Model
 
-Key entities and relationships.
+Các entity chính và quan hệ.
 
 ## §4. Service Flow
 
@@ -201,7 +201,7 @@ Key entities and relationships.
 
 ## §5. Business Rules Implementation
 
-| BR-ID | Rule | Implementation approach |
+| BR-ID | Rule | Cách implement |
 |-------|------|-------------------------|
 | {UC-ID}-BR1 | {rule} | {approach} |
 
@@ -213,15 +213,15 @@ Key entities and relationships.
 
 ## §7. Database Changes
 
-Migration scripts or schema changes.
+Migration script hoặc thay đổi schema.
 
 ## §8. Caching Strategy
 
-What to cache, TTL, invalidation triggers.
+Cache gì, TTL, trigger invalidation.
 
 ## §9. Cross-Service Dependencies
 
-External calls, events produced/consumed.
+Lời gọi ngoài, event phát ra/tiêu thụ.
 
 ## Changelog
 
@@ -232,7 +232,7 @@ External calls, events produced/consumed.
 
 ### Path B — FE/App client technical design  (`active_tech_design = fe`)
 
-Write `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md`. The §4 integration layer maps **directly onto the BE contract** loaded in Step 0.5 — every FE service method must trace to a real endpoint in `{be_contract_path}` (no invented endpoints). State and error models in §3/§7 derive from the **System BDD** `Then` clauses.
+Ghi `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md`. Layer tích hợp §4 map **trực tiếp lên BE contract** đã nạp ở Step 0.5 — mỗi FE service method phải trace tới một endpoint có thật trong `{be_contract_path}` (không bịa endpoint). State và error model ở §3/§7 dẫn xuất từ mệnh đề `Then` của **System BDD**.
 
 ```markdown
 # FE Technical Design — {UC-ID} ({platform}): {Feature}
@@ -241,12 +241,12 @@ Write `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{
 @trace.id: {UC-ID}
 @trace.domain: {domain}
 @trace.platform: {web | app}
-@trace.service: {read @trace.service from the .feature file header}
-@trace.module: {read @trace.module — e.g. react / nextjs / vue / angular / flutter}
+@trace.service: {đọc @trace.service từ header file .feature}
+@trace.module: {đọc @trace.module — vd react / nextjs / vue / angular / flutter}
 @trace.prd: {TICKET-ID}
-@trace.bdd_version: {read @trace.bdd_version from the FE .feature header}
+@trace.bdd_version: {đọc @trace.bdd_version từ header file .feature FE}
 @trace.system_bdd: {system_bdd_path}
-@trace.be_contract: {UC-ID}-tech-design.md   # the BE API contract this design consumes
+@trace.be_contract: {UC-ID}-tech-design.md   # BE API contract mà design này tiêu thụ
 @trace.testid_attr: {data-testid (web) | testID (react-native) | Key/Semantics (flutter) | accessibilityIdentifier (native-ios)}
 @trace.revision: 1
 @trace.status: draft
@@ -314,8 +314,8 @@ Query keys, cache invalidation triggers, optimistic updates, refetch policy (cli
 
 Auth token injection/refresh, i18n keys, feature flags, analytics events.
 
-{## §9. Offline / Platform Specifics   — app only}
-{Cached-data behavior, offline banner, background sync, platform permissions.}
+{## §9. Offline / Platform Specifics   — chỉ app}
+{Hành vi cached-data, banner offline, background sync, platform permission.}
 
 ## Changelog
 
@@ -324,32 +324,32 @@ Auth token injection/refresh, i18n keys, feature flags, analytics events.
 | 1 | {YYYY-MM-DD} | Initial FE design from {UC-ID} ({platform}) BDD v{bdd_version}, mapping BE contract {UC-ID}-tech-design.md |
 ```
 
-## Publish — share the doc (umbrella + shared spec repo)
+## Publish — chia sẻ doc (umbrella + spec repo dùng chung)
 
-If `paths.tech_docs_dir` resolved **under `setup.spec_source`** (e.g. `{spec_source}/specs/{domain}/{prd-slug}/tech-docs`), the doc was just written **inside the spec submodule**. Publish it (2-layer commit) so the rest of the team reads it via `/sync` — the BE doc is the cross-team **API contract**; the FE doc is the **client design** other FE/App devs (and reviewers) consume:
+Nếu `paths.tech_docs_dir` phân giải **dưới `setup.spec_source`** (vd `{spec_source}/specs/{domain}/{prd-slug}/tech-docs`), doc vừa được ghi **bên trong spec submodule**. Publish nó (commit 2 tầng) để cả team đọc qua `/sync` — doc BE là **API contract** liên team; doc FE là **client design** mà các FE/App dev khác (và reviewer) tiêu thụ:
 
 ```bash
 cd {spec_source}
 git add {tech_design_path}              # be: {UC-ID}-tech-design.md · fe: {UC-ID}-tech-design-{platform}.md
 git commit -m "docs({UC-ID}): {be: tech design / API contract | fe: FE tech design ({platform})}"
-git push origin {spec_branch}          # the branch teammates track in .gitmodules
+git push origin {spec_branch}          # branch mà đồng đội track trong .gitmodules
 cd -
 git add {spec_source} && git commit -m "chore: bump spec pointer ({UC-ID} {be|fe} tech design)"
 ```
 
-If `tech_docs_dir` is **local** — i.e. no `setup.spec_source` (single-repo, or a pure multi-service BE repo with no shared spec module) — skip this; no cross-repo publish needed. Whenever `spec_source` is set, tech-docs route to the spec submodule and this publish step applies.
+Nếu `tech_docs_dir` là **local** — tức không có `setup.spec_source` (single-repo, hoặc repo BE đa-service thuần không có spec module dùng chung) — bỏ qua bước này; không cần publish liên-repo. Khi nào `spec_source` được set, tech-docs route vào spec submodule và bước publish này áp dụng.
 
 ## Output
 
 {{include:steps/report-footer.md}}
 
 ```
-/generate-tech-docs Complete — {UC-ID}  ({active_tech_design: BE API contract | FE {platform} client design})
+/generate-tech-docs Hoàn tất — {UC-ID}  ({active_tech_design: BE API contract | FE {platform} client design})
 File: {tech_design_path}
 Next: /review-tech-docs {tech_design_path}
-      ← SA/Lead review required before code generation
-      → if it lives in the shared spec repo: commit + push to the spec submodule (see Publish above) so teammates `/sync` can read it
-      → after approved:
+      ← cần SA/Lead review trước khi sinh code
+      → nếu nó sống trong spec repo dùng chung: commit + push lên spec submodule (xem Publish ở trên) để đồng đội `/sync` đọc được
+      → sau khi approved:
           BE → /generate-code {system .feature}
-          FE → /generate-code {web|app .feature} --phase=integration   (wires real API per §4 of this doc)
+          FE → /generate-code {web|app .feature} --phase=integration   (wire API thật theo §4 của doc này)
 ```