@edupia-tutor/spec-driven-docs 0.14.0

package/commands/generate-tech-docs.tmpl

@@ -0,0 +1,355 @@
+# /generate-tech-docs — Generate 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}`.*
+
+**Quality Gate**: Before generating, check the BDD findings file:
+
+1. Look for `{paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml`.
+2. **If file does not exist** → warn and ask:
+   ```
+   ⚠️  /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)
+   ```
+   - 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:
+   ```
+   ❌ 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}
+   ```
+
+## Context
+{{include:steps/context-loader.md}}
+
+---
+
+## Step 0 — Detect 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).
+
+| 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` |
+
+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.
+
+---
+
+## Step 0.5 — FE/App Precondition Gate
+
+*Skip this entire step for 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:
+
+1. **System BDD** — locate `{paths.specs_dir}/{domain}/{prd-slug}/bdd/system/{TICKET-ID}*.feature`.
+   If not found → 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)
+   ```
+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:
+     ```
+     ❌ 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
+     ```
+   - Found but `@trace.status` ≠ `approved` → WARN and ask:
+     ```
+     ⚠️  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)
+     ```
+     - Y → proceed (accept risk) · N → stop, wait for BE to approve.
+
+Store `system_bdd_path` and `be_contract_path` — they are the primary inputs for the FE §3/§4 below.
+
+---
+
+## Brownfield Check
+
+*BE (`active_tech_design = be`) only — for FE the "existing contract" is the BE doc loaded in Step 0.5.*
+
+Read the source `.feature` file header for `@trace.api_source`.
+Also check the source PRD Metadata table for `| **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}`.
+
+If `active_mode = reverse-document` → load 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:
+
+**If `active_tech_design = be`:**
+```
+Tech Design Plan — {UC-ID}  (BE · API contract)
+──────────────────────────────────────────────────────
+UC       : {UC-ID} — {feature title}
+Service  : {trace.service}
+Module   : {trace.module}
+Mode     : {Reverse-document (API đã tồn tại) | Greenfield (thiết kế mới)}
+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:
+  §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})
+  §4 Service Flow
+  §5 Business Rules  ({N} BRs from feature header)
+  §6 Error Handling
+  §7 Database Changes
+  §8 Caching Strategy
+  §9 Cross-Service Dependencies
+──────────────────────────────────────────────────────
+Proceed? (Y/N)
+```
+
+**If `active_tech_design = fe`:**
+```
+Tech Design Plan — {UC-ID}  (FE · {platform} · client design)
+──────────────────────────────────────────────────────
+UC        : {UC-ID} — {feature title}
+Service   : {trace.service}    Module: {trace.module} ({platform})
+Inputs    : System BDD  → {system_bdd_path}
+            BE contract → {be_contract_path}  (status: {be status})
+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)
+  §3 State Management    (store/slices/state shape ← System BDD Then-clauses)
+  §4 API Integration Layer   (port/adapter: each 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)
+  §8 Cross-Cutting       (auth token, i18n, feature flags)
+  {§9 Offline / platform specifics — app only}
+──────────────────────────────────────────────────────
+Proceed? (Y/N)
+```
+
+Wait for explicit "Y" before generating.
+
+---
+
+## Generate
+
+Generate the document for the resolved `active_tech_design`.
+
+### Path A — BE API contract  (`active_tech_design = be`)
+
+Write `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md`:
+
+```markdown
+# Technical Design — {UC-ID}: {Feature}
+
+---
+@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.prd: {TICKET-ID}
+@trace.bdd_version: {read @trace.bdd_version from the .feature file header}
+@trace.revision: 1
+@trace.status: draft
+@trace.api_source: {existing | —}
+@trace.generated_at: {YYYY-MM-DD}
+---
+
+## §1. Overview
+
+{Tóm tắt ngắn: UC này implement gì, scope kỹ thuật chính.}
+
+## §2. API Endpoints
+
+*Greenfield:* endpoints được infer từ BDD scenarios — thiết kế mới.
+*Reverse-document:* mô tả lại API đã tồn tại từ bảng "Existing API Contract" trong PRD. Ghi chú gaps nếu contract thực tế khác với BDD expectations.
+
+| Method | Path | Auth/Role | Request | Response |
+|--------|------|-----------|---------|----------|
+| {GET/POST/PUT/DELETE} | {/api/v1/...} | {Bearer / role} | `{ field: type }` | `{ field: type }` |
+
+## §3. Data Model
+
+Key entities and relationships.
+
+## §4. Service Flow
+
+{Client} → Controller → {Facade/Service} → {Repository}
+
+## §5. Business Rules Implementation
+
+| BR-ID | Rule | Implementation approach |
+|-------|------|-------------------------|
+| {UC-ID}-BR1 | {rule} | {approach} |
+
+## §6. Error Handling
+
+| Scenario | Exception | HTTP Status |
+|----------|-----------|-------------|
+| {scenario} | {ExceptionClass} | {4xx/5xx} |
+
+## §7. Database Changes
+
+Migration scripts or schema changes.
+
+## §8. Caching Strategy
+
+What to cache, TTL, invalidation triggers.
+
+## §9. Cross-Service Dependencies
+
+External calls, events produced/consumed.
+
+## Changelog
+
+| Revision | Date | Changes |
+|----------|------|---------|
+| 1 | {YYYY-MM-DD} | Initial generation from {UC-ID}.feature (BDD v{bdd_version}) |
+```
+
+### 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.
+
+```markdown
+# FE Technical Design — {UC-ID} ({platform}): {Feature}
+
+---
+@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.prd: {TICKET-ID}
+@trace.bdd_version: {read @trace.bdd_version from the FE .feature header}
+@trace.system_bdd: {system_bdd_path}
+@trace.be_contract: {UC-ID}-tech-design.md   # the BE API contract this design consumes
+@trace.testid_attr: {data-testid (web) | testID (react-native) | Key/Semantics (flutter) | accessibilityIdentifier (native-ios)}
+@trace.revision: 1
+@trace.status: draft
+@trace.generated_at: {YYYY-MM-DD}
+---
+
+## §1. Overview
+
+{FE scope của UC: màn hình/luồng nào, render gì, tích hợp API nào. Nêu rõ design này map theo BE contract {UC-ID}-tech-design.md.}
+
+## §2. Component Architecture
+
+Component tree (container vs presentational). Ưu tiên tái dùng từ figma-components catalog (Step 6-B context); chỉ tạo mới khi không có sẵn.
+
+| Component | Type | Reuse (catalog) / New | Responsibility |
+|-----------|------|-----------------------|----------------|
+| {Name} | container/presentational | {catalog name \| NEW} | {what it renders / handles} |
+
+## §2b. Test Selectors — Element IDs cho element CÓ ACTION (QC contract)
+
+Mỗi element tương tác (button, input, link, select, toggle, form-submit…) được gán **test-id ổn định** để QC locate **trực tiếp** — không scan/giả lập runtime. Đây là contract giữa FE code (emit id) và QC Page Object (đọc id).
+
+- **Quy ước (semantic-stable):** `{uc-lower}-{screen}-{element}-{type}` — vd `ft001-login-submit-btn`, `ft001-login-email-input`. **KHÔNG** nhúng số scenario (đổi khi renumber).
+- **Attribute theo platform** (`@trace.testid_attr`): web `data-testid` · React Native `testID` · Flutter `Key('id')` + `Semantics(identifier:)` · native iOS `accessibilityIdentifier`.
+- **Cross-platform (web ↔ app):** cùng một element logic dùng **CÙNG test-id value** trên cả web và app — chỉ *attribute* khác theo platform. Mỗi platform có file tech-design riêng (`-web.md` / `-app.md`) với §2b riêng, nhưng id value phải khớp để QC tái dùng logic test và 2 doc không lệch. Khi gen platform thứ hai, **đọc §2b của file platform kia** và tái dùng id đã có; chỉ thêm id cho element mà platform này có riêng.
+- Chỉ gán cho element **có action**; element tĩnh (label, text thuần) không cần.
+
+| Test-ID | Element | Component (§2) | Action | Serves SC |
+|---------|---------|----------------|--------|-----------|
+| `{uc}-{screen}-{element}-{type}` | {Submit button} | {LoginForm} | {submit login} | SC1, SC3 |
+
+> QC: Page Object locator lấy test-id từ bảng này (ưu tiên `data-testid`/attribute tương ứng). Element có action mà **chưa** có test-id ở đây → QC fallback role/text (chậm hơn) và nên bổ sung vào bảng này.
+>
+> **Element từ component reuse / code có sẵn (brownfield):** id sống ở **usage site**, component dùng chung phải *forward* được test-id. Đừng tự bịa ở đây — chạy `/map-testids {UC-ID}` để reverse-document id đang có, gán id còn thiếu, patch forwarding + ghi catalog, rồi điền §2b này. Lệnh này chỉ tự gán id cho component **mới**.
+
+## §3. State Management
+
+State shape suy ra từ System BDD `Then` clauses + response shapes trong BE contract. Nêu store/slices, server-state vs UI-state.
+
+| Slice / Key | Shape | Nguồn (BE field / local) | Updated by |
+|-------------|-------|--------------------------|------------|
+
+## §4. API Integration Layer (port/adapter)
+
+**Mỗi method phải map tới một endpoint CÓ THẬT trong BE contract `{UC-ID}-tech-design.md`.** Đây là hợp đồng thay thế mock adapter của `/generate-code --phase=ui`.
+
+| FE service method | BE endpoint (từ contract) | Request map | Response → model | Error → UI |
+|-------------------|---------------------------|-------------|------------------|-----------|
+| {svc.getX()} | {GET /api/v1/...} | {params} | {DTO → ViewModel} | {4xx/5xx → state/toast} |
+
+## §5. Routing / Navigation
+
+Routes / màn hình, params, guards (auth/role), lazy-load.
+
+## §6. Data Fetching & Client Caching
+
+Query keys, cache invalidation triggers, optimistic updates, refetch policy (client-side — KHÔNG phải server cache).
+
+## §7. Error & Loading States
+
+| Scenario (BDD) | Loading UI | Error UI | Empty state |
+|----------------|-----------|----------|-------------|
+
+## §8. Cross-Cutting
+
+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.}
+
+## Changelog
+
+| Revision | Date | Changes |
+|----------|------|---------|
+| 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)
+
+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:
+
+```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
+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.
+
+## Output
+
+{{include:steps/report-footer.md}}
+
+```
+/generate-tech-docs Complete — {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:
+          BE → /generate-code {system .feature}
+          FE → /generate-code {web|app .feature} --phase=integration   (wires real API per §4 of this doc)
+```