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

package/commands/generate-prd.tmpl

@@ -1,254 +1,104 @@
-# /generate-prd — Generate Product Requirements Document
+# /generate-prd — Sinh Product Requirements Document
 
 ## Gate
 {{include:steps/gate.md}}
 
-*Note: For this command, the target file in Step 1 is a product-definition file in `{paths.product_definitions_dir}/`. Resolve it from `$ARGUMENTS` or list the directory and ask.*
+*Lưu ý: Với lệnh này, target file ở Bước 1 là một file product-definition trong `{paths.product_definitions_dir}/`. Phân giải từ `$ARGUMENTS` hoặc liệt kê thư mục và hỏi.*
 
 ## Context
 {{include:steps/context-loader.md}}
 
-*Additional context for this command: Read the full product-definition file. Extract: **TICKET-ID**, **domain**, **feature name**, Phases 1-7 data.*
+*Context bổ sung cho lệnh này: Đọc toàn bộ file product-definition. Trích xuất: **TICKET-ID**, **domain**, **tên feature**, dữ liệu Phase 1-7, và bảng **Chuẩn hoá thuật ngữ** (Terminology Map ở Phase 0 — các cặp `thuật ngữ PO → thuật ngữ chuẩn`). Lưu bản đồ này để áp dụng ở bước Quy tắc thuật ngữ. **Nếu Phase 7 (Validation Report) còn `Xung đột phát hiện` / `Mục còn thiếu` khác "None" → diễn đạt lại mỗi mục thành một câu hỏi theo format `Q… — [AI DRAFT]` của section "Giả định AI" (nêu rõ độ vênh + cần PO chốt điều gì), thay vì dán thô. AI không tự quyết thay PO.***
 
-CHECKPOINT before generating: "Generate PRD for **{TICKET-ID} — {feature}** (domain: {domain}). Continue? (Y/N)"
+CHECKPOINT trước khi sinh: "Sinh PRD cho **{TICKET-ID} — {feature}** (domain: {domain}). Tiếp tục? (Y/N)"
 
 ---
 
-## Terminology Rules *(apply if business-dictionary.md exists)*
+## Quy tắc thuật ngữ *(áp dụng nếu business-dictionary.md tồn tại)*
 
-- **Replace banned terms**: substitute every banned term with its canonical equivalent (see dictionary § Banned Terms).
-- **Use canonical terms**: only use terms defined in dictionary.
-- **NEW TERM DETECTION**: If a term from PO input appears ≥2 times and is NOT in dictionary → **STOP** and ask PO:
-  - What does that term mean in the system context?
-  - What should the English canonical term be?
-  - Should it be added to business-dictionary.md?
-  After PO confirms → update `business-dictionary.md` (if agreed) → continue generation.
-- If no banned terms found and all terms are canonical → proceed without interruption.
+- **Áp dụng Terminology Map từ product-definition**: với mỗi cặp `thuật ngữ PO → thuật ngữ chuẩn` trong bảng **Chuẩn hoá thuật ngữ** (Phase 0 của product-definition), dùng **thuật ngữ chuẩn** khi viết PRD. Đây là bản đồ PO đã xác nhận ở discovery — luôn ưu tiên áp dụng kể cả khi business-dictionary.md vắng mặt, để PRD nhất quán với product-definition. Nếu bảng trống/không có → bỏ qua âm thầm.
+- **Thay banned term**: thay mọi banned term bằng bản chuẩn tương đương (xem dictionary § Banned Terms).
+- **Dùng canonical term**: chỉ dùng các thuật ngữ được định nghĩa trong dictionary.
+- **NEW TERM DETECTION**: Nếu một thuật ngữ trong input PO xuất hiện ≥2 lần và KHÔNG có trong dictionary → **DỪNG** và hỏi PO:
+  - Thuật ngữ đó nghĩa là gì trong ngữ cảnh hệ thống?
+  - English canonical term nên dùng là gì?
+  - Có cần bổ sung vào business-dictionary.md không?
+  Sau khi PO confirm → cập nhật `business-dictionary.md` (nếu đồng ý) → tiếp tục sinh.
+- Nếu không có banned term và tất cả thuật ngữ đều chuẩn → tiếp tục không gián đoạn.
 
-## Cross-Reference Rule
+## Quy tắc Cross-Reference
 
-Any mention of another TICKET-ID anywhere in the PRD (pre-condition, BR, note, appendix) → **MUST** be an inline link:
+Bất kỳ chỗ nào nhắc tới một TICKET-ID khác trong PRD (pre-condition, BR, ghi chú, appendix) → **PHẢI** là inline link. Mỗi PRD sống trong feature-package riêng (`{paths.specs_dir}/{domain}/{prd-slug-khác}/`), nên link trỏ sang folder anh em:
 ```
-[TICKET-ID](./TICKET-ID-slug.md)
+[TICKET-ID khác](../{prd-slug-khác}/{TICKET-ID-khác}-{prd-slug-khác}.md)
 ```
-Never leave TICKET-ID as plain text if a corresponding PRD file exists in `{paths.specs_dir}/{domain}/{prd-slug}/`.
+Không bao giờ để TICKET-ID dạng plain text nếu file PRD tương ứng tồn tại trong `{paths.specs_dir}/{domain}/`.
 
-## UC and BR Numbering Convention
+## Quy ước đánh số UC và BR
 
-- **UC ID**: `{TICKET-ID}-UC{N}` — N starts at 1, increments per use case.
-- **BR ID**: `{TICKET-ID}-UC{N}-BR{M}` — **M increments across the whole PRD** (does NOT reset per UC).
-  - Example: UC1 → BR1, BR2; UC2 → BR3, BR4 (NOT BR1, BR2 again).
+- **UC ID**: `{TICKET-ID}-UC{N}` — N bắt đầu từ 1, tăng theo từng use case.
+- **BR ID**: `{TICKET-ID}-UC{N}-BR{M}` — **M tăng liên tục trên toàn PRD** (KHÔNG reset theo từng UC).
+  - Ví dụ: UC1 → BR1, BR2; UC2 → BR3, BR4 (KHÔNG phải BR1, BR2 lại từ đầu).
 
 ---
 
-## Platform Strategy — PRD is platform-agnostic (Option C)
+## Platform Strategy — PRD là tài liệu nghiệp vụ (không technical)
 
-PRD mô tả **WHAT** (yêu cầu nghiệp vụ) — không phụ thuộc vào platform nào implement.
-Viết AC theo business outcome, không theo UI/API details:
+PRD mô tả **WHAT** (yêu cầu nghiệp vụ) — không nhét chi tiết **kỹ thuật** (API, token, endpoint, HTTP status, tên class/bảng/cột DB, query). Những thứ đó thuộc **Tech Docs**.
+PRD **được phép** có User Flow + Wireframe ở mức nghiệp vụ (§4) để BA/QC/Dev cùng hình dung; chỉ **chi tiết visual** (màu sắc, layout pixel, animation, micro-interaction) mới thuộc **Design Spec**.
 
-| ✅ Viết trong PRD (platform-agnostic) | ❌ Không viết trong PRD |
+| ✅ Viết trong PRD (nghiệp vụ) | ❌ KHÔNG viết trong PRD |
 |---|---|
-| "Đăng nhập thành công → truy cập được tính năng" | "Click button → show toast" ← Design Spec |
-| "Sai password 5 lần → khoá tài khoản 30 phút" | "API trả về JWT token" ← Tech Docs |
-| "Session hết hạn → yêu cầu xác thực lại" | "Hiển thị spinner khi loading" ← Design Spec |
+| "Đăng nhập thành công → truy cập được tính năng" | "API trả về JWT token" ← Tech Docs |
+| "Sai mật khẩu 5 lần → khoá tài khoản 30 phút" | "Hiển thị spinner khi loading" ← Design Spec |
+| Wireframe mức nghiệp vụ: màn hình có gì, hành động ra kết quả gì | "Animation fade 300ms, màu #FF0000" ← Design Spec |
 
 **Một PRD phục vụ tất cả platform:**
 - **FE/App team** → đọc PRD + Design Spec → `/generate-bdd` (UI-level scenarios)
 - **BE team** → đọc PRD trực tiếp → `/generate-bdd` (API-level scenarios)
-- Design Spec là tài liệu riêng cho FE/App — **không trộn vào PRD**
+- Design Spec là tài liệu **chi tiết visual** riêng cho FE/App — Wireframe nghiệp vụ trong PRD chỉ là khung.
 
-Khi viết AC, nếu PO đề cập chi tiết UI (màu sắc, layout, animation) → nhắc nhở:
-*"Chi tiết UI này thuộc về Design Spec, không thuộc PRD. Ghi nhận lại để tạo Design Spec sau."*
+Khi viết AC, nếu PO đề cập chi tiết visual (màu sắc, animation, layout pixel) → nhắc nhở:
+*"Chi tiết visual này thuộc về Design Spec, không thuộc PRD. Ghi nhận lại để tạo Design Spec sau."*
 
 ---
 
 ## Generate
 
-Write `{paths.specs_dir}/{domain}/{prd-slug}/prd.md` using the structure below.
+Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu trúc dưới đây.
 
----
-
-```markdown
-# {TICKET-ID} {Feature Name}
-
----
-
-## Metadata
-
-| Field         | Value                            |
-|---------------|----------------------------------|
-| **PRD ID**    | {TICKET-ID}                      |
-| **Version**   | 1.0                              |
-| **Status**    | draft                            |
-| **Author**    | {PO name or "AI-assisted"}       |
-| **Domain**    | {domain}                         |
-| **Created**   | {YYYY-MM-DD}                     |
-| **Updated**   | {YYYY-MM-DD}                     |
-| **API Source** | *(bỏ trống nếu greenfield — thêm `existing` nếu API đã tồn tại trên hệ thống)* |
-
----
-
-# Feature
-
-{Describe the capability or function this feature provides — 2-3 concise sentences.}
-
----
-
-# 1. Overview
-
-## a. User Story
-
-- **As a** {User role}
-- **I want to** {User goal}
-- **So that** {Business value}
-
-## b. Scope
-
-**In Scope**
-
-- {Function 1}
-- {Function 2}
-
----
-
-# 2. Acceptance Criteria
-
-- **AC1:** {Acceptance criterion — testable, observable, no UI details}
-- **AC2:** {Acceptance criterion}
-
----
-
-# 3. Use Case
-
-#### {TICKET-ID}-UC1: {Use Case Name}
-
-- **Actor:** {User performing the action}
-- **Description:** {Business scenario description — 1 sentence}
-- **Pre-condition:** {Condition that must be true BEFORE use case begins}
-- **Post-condition:** {State / result AFTER use case completes}
-
-**Business Rule**
-
-| ID | Business Rule |
-|----|---------------|
-| {TICKET-ID}-UC1-BR1 | {Rule — WHAT the system must do} |
-| {TICKET-ID}-UC1-BR2 | {Rule} |
-
-**Business Logic**
-
-**{TICKET-ID}-UC1-BR1:**
-- Logic 1
-- Logic 2
-- Logic 3
-
-**{TICKET-ID}-UC1-BR2:**
-- Logic
-
----
-
-# 4. UI/UX Guidelines
-
-## a. User Flow
-
-{Brief description of sequence and decision branches}
-
-```mermaid
-flowchart TD
-    A[Step 1: ...] --> B[Step 2: ...]
-    B --> C{Condition?}
-    C -->|Yes| D[Result A]
-    C -->|No| E[Result B]
-```
-
-## b. Wireframe
-
-**Screen 1: {Screen Name}**
-
-**Screen:** {Screen name}
-
-**Components:**
-- {Component 1}
-- {Component 2}
-- {Component 3}
-
-**Actions:**
-- {Action 1} → {Result}
-- {Action 2} → {Result}
+> **Quy ước tên file PRD:** `{TICKET-ID}-{prd-slug}.md` — vd `SEG01-segment-scoring-service.md`. KHÔNG đặt tên `prd.md`. Mỗi feature-package có đúng **một** file PRD ở cấp gốc folder (cạnh `bdd/`, `tech-docs/`, `design-spec/`); tính duy nhất nằm ở cả tên folder lẫn TICKET-ID trong tên file.
 
 ---
 
-# Appendix
-
-## Original PO Input
-
-> {Paste verbatim content from product-definition file — Context + Problem + Goal}
-
-## References
-
-- {[TICKET-ID](./TICKET-ID-slug.md) — relationship description}
-
-## Existing API Contract *(chỉ điền khi API Source = existing)*
-
-> API đã tồn tại trên hệ thống. PO ghi lại contract để BDD generation dùng trực tiếp —
-> không cần tổng hợp từ FE/App BDD, không cần T7 sign-off gate.
-
-| Method | Path | Auth | Request | Response |
-|--------|------|------|---------|----------|
-| {GET/POST/PUT/DELETE} | {/api/v1/path} | {Bearer / none} | `{ field: type }` | `{ field: type }` |
-
-**Error responses:**
-
-| HTTP Status | Error Code | Khi nào xảy ra |
-|-------------|------------|----------------|
-| {4xx/5xx} | {ERR_CODE} | {condition} |
-
----
-
-## AI Assumptions
-
-> Assumptions AI made when information was incomplete. Needs PO review and confirmation.
-
-- {Assumption 1 — [AI DRAFT]}
-```
+````markdown
+{{include:templates/prd.template.md}}
+````
 
 ---
 
-## Quality Checklist *(verify before writing)*
+## Quality Checklist *(kiểm tra trước khi ghi)*
 
-- [ ] Every AC is testable (clear pass/fail), no UI details (colors, fonts, button positions)
-- [ ] Each UC has Actor / Description / Pre-condition / Post-condition
-- [ ] Business Rule (WHAT) is separate from Business Logic (HOW)
-- [ ] BR ID increments across whole PRD — does not reset per UC
-- [ ] Every TICKET-ID cross-reference is an inline link `[TICKET-ID](./file.md)`
-- [ ] No banned terms (if dictionary exists)
-- [ ] User Flow includes error path / exception path
-- [ ] Wireframe covers all screens related to Use Cases
+- [ ] Mọi AC đều testable (pass/fail rõ ràng), không có chi tiết kỹ thuật (API/token/DB) hay visual chi tiết (màu sắc, font, animation)
+- [ ] Mỗi UC có Actor / Description / Pre-condition / Post-condition
+- [ ] Business Rule (WHAT) và Business Logic (HOW) nằm chung bảng 3 cột `ID | Business Rule | Business Logic`
+- [ ] BR ID tăng liên tục trên toàn PRD — không reset theo từng UC
+- [ ] Mọi cross-reference TICKET-ID đều là inline link `[TICKET-ID](./file.md)`
+- [ ] Không có banned term (nếu dictionary tồn tại)
+- [ ] User Flow có cả luồng lỗi / luồng ngoại lệ
+- [ ] Wireframe phủ tất cả màn hình liên quan tới Use Case
 - [ ] **Định dạng (readability)**: User Story / AC / các field của UC (Actor, Description, Pre/Post-condition) viết dạng bullet `- **Label:** …` — mỗi ý MỘT dòng, KHÔNG viết các dòng liền nhau (sẽ bị dồn thành 1 đoạn khi render); có một dòng trống trước và sau mỗi bảng
 
-## Changelog Section (append at end of PRD)
-
-Every PRD must end with this section. Start at v1.0:
-
-```markdown
----
-
-## Changelog
-
-| Version | Date | Changes |
-|---------|------|---------|
-| 1.0 | {YYYY-MM-DD} | Initial version |
-```
-
 ## Output
 
 {{include:steps/report-footer.md}}
 
 ```
-/generate-prd Complete — {TICKET-ID}
+/generate-prd Hoàn tất — {TICKET-ID}
 ---
 Status : ✅ Complete
 Output Artifacts:
-  created {paths.specs_dir}/{domain}/{prd-slug}/prd.md  (PRD v1.0)
-Next   : /refine-prd {paths.specs_dir}/{domain}/{prd-slug}/prd.md
-         → then /review-context {prd-file}   ← verify PRD quality before generating BDD
+  created {paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md  (PRD v1.0)
+Next   : /refine-prd {paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md
+         → rồi /review-context {prd-file}   ← kiểm tra chất lượng PRD trước khi sinh BDD
 ```