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

package/core/templates/platform-guide.template.md

@@ -1,33 +1,33 @@
 # Platform Guide — {{SERVICE_NAME}}
 
-> This guide provides context that Claude uses when working in THIS service/repository.
-> Keep it concise and factual. Update when the architecture or domain model changes.
-> Reference: CLAUDE.md for project-wide standards. This file covers service-specific context.
+> Guide này cung cấp context mà Claude dùng khi làm việc trong service/repository NÀY.
+> Giữ ngắn gọn và đúng sự thật. Cập nhật khi kiến trúc hoặc domain model thay đổi.
+> Tham chiếu: CLAUDE.md cho chuẩn toàn dự án. File này phủ context riêng của service.
 
 ---
 
 # §1. Service Overview
 
-**Service name**: {{SERVICE_NAME}}
-**Purpose**: {{ONE_SENTENCE_PURPOSE}}
-**Bounded context**: {{BOUNDED_CONTEXT}}  # e.g., "Owns all order lifecycle logic. Does NOT own payments or inventory."
+**Tên service**: {{SERVICE_NAME}}
+**Mục đích**: {{ONE_SENTENCE_PURPOSE}}
+**Bounded context**: {{BOUNDED_CONTEXT}}  # vd: "Sở hữu toàn bộ logic vòng đời order. KHÔNG sở hữu payment hay inventory."
 **Team**: {{TEAM_NAME}}
 **Repository**: {{REPO_URL}}
 
-Primary responsibilities:
+Trách nhiệm chính:
 - {{RESPONSIBILITY_1}}
 - {{RESPONSIBILITY_2}}
 - {{RESPONSIBILITY_3}}
 
-This service does NOT handle:
-- {{OUT_OF_SCOPE_1}}  # e.g., "Payment processing → see payment-service"
+Service này KHÔNG xử lý:
+- {{OUT_OF_SCOPE_1}}  # vd: "Xử lý payment → xem payment-service"
 - {{OUT_OF_SCOPE_2}}
 
 ---
 
 # §2. Domain Model
 
-Key entities and their relationships:
+Các entity chính và quan hệ của chúng:
 
 ```
 {{ENTITY_1}} (aggregate root)
@@ -39,31 +39,31 @@ Key entities and their relationships:
 ```
 
 **{{ENTITY_1}}**:
-- Key fields: {{KEY_FIELDS}}
-- Status lifecycle: {{STATUS_1}} → {{STATUS_2}} → {{STATUS_3}}
-- Business rules: {{KEY_RULE_1}}
+- Field chính: {{KEY_FIELDS}}
+- Vòng đời status: {{STATUS_1}} → {{STATUS_2}} → {{STATUS_3}}
+- Business rule: {{KEY_RULE_1}}
 
 **{{ENTITY_2}}**:
-- Key fields: {{KEY_FIELDS}}
-- Relationships: {{RELATIONSHIP_DESCRIPTION}}
+- Field chính: {{KEY_FIELDS}}
+- Quan hệ: {{RELATIONSHIP_DESCRIPTION}}
 
 ---
 
 # §3. Common Patterns
 
-Patterns specific to this service (supplement the project-wide standards in CLAUDE.md):
+Các pattern riêng của service này (bổ sung cho chuẩn toàn dự án trong CLAUDE.md):
 
 ## {{PATTERN_NAME_1}}
 ```
-// When to use: {{USE_CASE}}
-// Example:
+// Khi nào dùng: {{USE_CASE}}
+// Ví dụ:
 {{CODE_EXAMPLE}}
 ```
 
 ## {{PATTERN_NAME_2}}
 ```
-// When to use: {{USE_CASE}}
-// Example:
+// Khi nào dùng: {{USE_CASE}}
+// Ví dụ:
 {{CODE_EXAMPLE}}
 ```
 
@@ -71,30 +71,30 @@ Patterns specific to this service (supplement the project-wide standards in CLAU
 
 # §4. Integration Points
 
-## Upstream Dependencies (this service calls these)
+## Upstream Dependencies (service này gọi các bên dưới)
 
-| Service / System | What we call | Protocol | Auth |
+| Service / System | Cái ta gọi   | Protocol | Auth |
 |------------------|--------------|----------|------|
 | {{UPSTREAM_1}}   | {{WHAT}}     | REST/gRPC/Event | {{AUTH_METHOD}} |
 | {{UPSTREAM_2}}   | {{WHAT}}     | REST/gRPC/Event | {{AUTH_METHOD}} |
 
-## Downstream Consumers (these services call us or consume our events)
+## Downstream Consumers (các bên dưới gọi ta hoặc tiêu thụ event của ta)
 
-| Consumer | What they use | Protocol |
+| Consumer | Cái họ dùng   | Protocol |
 |----------|---------------|----------|
 | {{DOWNSTREAM_1}} | {{WHAT}} | REST/Event |
 | {{DOWNSTREAM_2}} | {{WHAT}} | REST/Event |
 
-## Events Produced
+## Event phát ra (Produced)
 
-| Event name | Trigger | Payload summary |
+| Tên event | Trigger | Tóm tắt payload |
 |------------|---------|-----------------|
 | {{EVENT_1}} | {{WHEN}} | {{PAYLOAD_FIELDS}} |
 | {{EVENT_2}} | {{WHEN}} | {{PAYLOAD_FIELDS}} |
 
-## Events Consumed
+## Event tiêu thụ (Consumed)
 
-| Event name | From service | What we do with it |
+| Tên event | Từ service | Ta làm gì với nó |
 |------------|-------------|-------------------|
 | {{EVENT_1}} | {{SOURCE}} | {{HANDLER_ACTION}} |
 
@@ -102,20 +102,20 @@ Patterns specific to this service (supplement the project-wide standards in CLAU
 
 # §5. Known Constraints
 
-## Performance Constraints
-- {{PERF_CONSTRAINT_1}}  # e.g., "Order list endpoint must respond < 200ms for up to 1000 orders"
+## Ràng buộc hiệu năng (Performance)
+- {{PERF_CONSTRAINT_1}}  # vd: "Endpoint danh sách order phải phản hồi < 200ms cho tới 1000 order"
 - {{PERF_CONSTRAINT_2}}
 
-## Business Rule Constraints
-- {{BUSINESS_CONSTRAINT_1}}  # e.g., "Cannot cancel an order after it has been shipped"
+## Ràng buộc business rule
+- {{BUSINESS_CONSTRAINT_1}}  # vd: "Không thể huỷ order sau khi đã ship"
 - {{BUSINESS_CONSTRAINT_2}}
 
-## External Dependencies
-- {{EXTERNAL_DEP_1}}  # e.g., "Requires inventory-service to be available for order creation"
+## Phụ thuộc bên ngoài (External)
+- {{EXTERNAL_DEP_1}}  # vd: "Cần inventory-service sẵn sàng để tạo order"
 - {{EXTERNAL_DEP_2}}
 
-## Known Technical Debt
-- {{TECH_DEBT_1}}  # e.g., "OrderItem.price is duplicated from catalog — sync via nightly job"
+## Technical Debt đã biết
+- {{TECH_DEBT_1}}  # vd: "OrderItem.price bị nhân bản từ catalog — đồng bộ qua job hằng đêm"
 
 ---
 
@@ -123,23 +123,23 @@ Patterns specific to this service (supplement the project-wide standards in CLAU
 
 ```
 {{SERVICE_ROOT}}/
-├── {{SOURCE_DIR}}/              # Main source code
-│   ├── {{LAYER_1}}/             # e.g., controller/ or handler/
+├── {{SOURCE_DIR}}/              # Code nguồn chính
+│   ├── {{LAYER_1}}/             # vd: controller/ hoặc handler/
 │   │   └── {{EXAMPLE_FILE}}
-│   ├── {{LAYER_2}}/             # e.g., service/ or usecase/
+│   ├── {{LAYER_2}}/             # vd: service/ hoặc usecase/
 │   │   └── {{EXAMPLE_FILE}}
-│   ├── {{LAYER_3}}/             # e.g., repository/ or repo/
+│   ├── {{LAYER_3}}/             # vd: repository/ hoặc repo/
 │   │   └── {{EXAMPLE_FILE}}
-│   └── {{LAYER_4}}/             # e.g., model/ or domain/
+│   └── {{LAYER_4}}/             # vd: model/ hoặc domain/
 │       └── {{EXAMPLE_FILE}}
-├── {{TEST_DIR}}/                # Tests mirroring src structure
-├── specs/                       # BDD feature files
+├── {{TEST_DIR}}/                # Test phản chiếu cấu trúc src
+├── specs/                       # File BDD feature
 │   └── bdd/
 │       └── {{DOMAIN}}/
 │           └── {{UC-ID}}-{{slug}}.feature
-└── {{CONFIG_FILE}}              # e.g., application.yaml / appsettings.json
+└── {{CONFIG_FILE}}              # vd: application.yaml / appsettings.json
 ```
 
-**Key conventions for this repo:**
-- {{CONVENTION_1}}  # e.g., "All DTOs are in the api/ package, not mixed with domain models"
-- {{CONVENTION_2}}  # e.g., "Integration tests are in src/test/java/.../integration/ with @Tag(\"integration\")"
+**Convention chính của repo này:**
+- {{CONVENTION_1}}  # vd: "Mọi DTO nằm trong package api/, không trộn với domain model"
+- {{CONVENTION_2}}  # vd: "Integration test nằm ở src/test/java/.../integration/ với @Tag(\"integration\")"

package/core/templates/prd.template.md

@@ -1,90 +1,60 @@
-# {TICKET-ID} Tên tính năng/Feature Name
+# {TICKET}-{N} {Feature Name}
 
 <!--
   Template này được sử dụng bởi workflow /generate-prd.
   AI Agent sẽ điền các section dựa trên input từ PO.
   Các placeholder {…} cần được thay thế bằng nội dung thực tế.
 
-  ╔══════════════════════════════════════════════════════════════════════╗
-  ║  TERMINOLOGY RULES — Business Dictionary Enforcement               ║
-  ║  Source: specs/domain-knowledge/business-dictionary.md              ║
-  ║  AI Agent PHẢI tuân thủ 100% khi sinh nội dung PRD.                ║
-  ╚══════════════════════════════════════════════════════════════════════╝
-
-  THUẬT NGỮ BẮT BUỘC (phải dùng đúng keyword):
-  ┌─────────────────────────┬──────────────────────────────────────────┐
-  │ Keyword chuẩn           │ Ngữ cảnh                                │
-  ├─────────────────────────┼──────────────────────────────────────────┤
-  │ Consumer                │ Khách hàng (global entity)              │
-  │ Merchant / Tenant       │ Merchant = nghiệp vụ, Tenant = kỹ thuật│
-  │ Online Storefront       │ Tính năng bán hàng trên Zalo Mini App   │
-  │ Branch                  │ Chi nhánh vật lý (projection từ KVS)    │
-  │ Loyalty Member          │ Quan hệ Consumer ↔ Merchant             │
-  │ Order                   │ Đơn hàng (chỉ completed → Loyalty)      │
-  │ OrderItem               │ Chi tiết dòng hàng trong Order           │
-  │ Product                 │ Hàng hóa (projection từ KVS)            │
-  │ ProductCategory         │ Nhóm hàng (hierarchical)                │
-  │ ProductAttribute        │ Định nghĩa loại thuộc tính              │
-  │ ProductAttributeMap     │ Mapping thuộc tính → sản phẩm cụ thể    │
-  │ ProductImage            │ Hình ảnh sản phẩm (nhiều ảnh, có rank)  │
-  │ Address                 │ Địa chỉ đa hình (polymorphic)           │
-  │ SourceSystem            │ Hệ thống partner (map → X-App-Id)       │
-  │ ExternalId              │ ID tham chiếu từ hệ thống nguồn (KVS)   │
-  │ Onboarding              │ Quy trình khởi tạo gian hàng lần đầu    │
-  │ revision                │ Row version — delta sync                 │
-  │ KVLoyalty Widget        │ Thư viện tích hợp frontend (JS qua CDN) │
-  └─────────────────────────┴──────────────────────────────────────────┘
-
-  THUẬT NGỮ BỊ CẤM — TUYỆT ĐỐI KHÔNG xuất hiện trong PRD:
-  ┌─────────────────────────┬─────────────────────────────────────────────────┐
-  │ ❌ KHÔNG dùng           │ ✅ Thay thế bằng                               │
-  ├─────────────────────────┼─────────────────────────────────────────────────┤
-  │ Customer                │ Consumer                                        │
-  │ SKU                     │ Product + ProductAttribute + ProductAttributeMap│
-  │ JS SDK / JavaScript SDK │ KVLoyalty Widget                                │
-  │ CDC                     │ Event bus (Kafka)                               │
-  │ primaryBranchId         │ Branch.isPrimary                                │
-  │ Cửa hàng (= storefront)│ Online Storefront / Gian hàng online            │
-  └─────────────────────────┴─────────────────────────────────────────────────┘
-
-  QUY TẮC BỔ SUNG:
-  - Luôn dùng SourceSystem cho partners, ExternalId cho external references.
-  - Status/Enum values → tham chiếu core-entities.md Global Enum Registry.
-  - Khi nhắc "SKU" → diễn giải bằng Product con (masterProductId) + ProductAttributeMap.
-  - Consumer là global entity — 1 Consumer có thể mua hàng ở nhiều Merchant.
-  - Nếu phát hiện banned term trong input PO → thay thế bằng term chuẩn và ghi chú trong "Giả định AI".
-  - CROSS-REFERENCE (BẮT BUỘC): Bất kỳ chỗ nào trong tài liệu có nhắc đến một tính năng/ticket khác
-    (dù là pre-condition, business rule, giả định, AC, hay bất kỳ section nào) → PHẢI gắn inline link:
+  FORMAT CHUẨN: Business Rule = bảng 3 cột
+  ID | Business Rule | Business Logic (KHÔNG tách Business Logic ra khối riêng).
+
+  TERMINOLOGY:
+  - Tuân thủ 100% từ điển project: specs/domain-knowledge/business-dictionary.md
+    (KHÔNG dùng từ điển của project khác). Thay banned term bằng canonical term;
+    nếu phát hiện banned term trong input PO → thay + ghi chú trong "Giả định AI".
+  - Status/Enum values → tham chiếu core-entities.md (Enum Registry).
+
+  CROSS-REFERENCE (BẮT BUỘC): Bất kỳ chỗ nào nhắc đến một tính năng/ticket khác
+    (pre-condition, business rule, giả định, AC, hay bất kỳ section nào) → PHẢI gắn inline link:
       [TICKET-ID](./TICKET-ID-slug.md)
-    Không được để TICKET-ID dạng plain text nếu tồn tại file PRD tương ứng.
+    Không để TICKET-ID dạng plain text nếu tồn tại file PRD tương ứng.
     Ngoài ra, ghi rõ quan hệ phụ thuộc trong "Tài liệu tham khảo" ở Appendix.
-  - NEW TERM DETECTION: Nếu trong input PO xuất hiện thuật ngữ CHƯA CÓ trong business-dictionary.md
-    và thuật ngữ đó lặp lại ≥ 2 lần → DỪNG lại, hỏi PO confirm trước khi tiếp tục:
-      + Thuật ngữ đó có nghĩa gì trong ngữ cảnh hệ thống?
+
+  NEW TERM DETECTION: Nếu input PO xuất hiện thuật ngữ CHƯA CÓ trong business-dictionary.md
+    và lặp lại ≥ 2 lần → DỪNG lại, hỏi PO confirm trước khi tiếp tục:
+      + Thuật ngữ đó nghĩa gì trong ngữ cảnh hệ thống?
       + English term chuẩn 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 PO đồng ý) rồi mới tiếp tục sinh PRD.
+    Sau khi PO confirm → cập nhật business-dictionary.md (nếu PO đồng ý) rồi mới tiếp tục.
+
+  NUMBERING:
+  - UC ID: {TICKET}-{N}-UC{n}  (n bắt đầu từ 1, tăng theo từng use case)
+  - BR ID: {TICKET}-{N}-UC{n}-BR{m}  (m tăng LIÊN TỤC xuyên suốt PRD, KHÔNG reset mỗi UC)
 -->
 
 ---
 
 ## Metadata
 
-| Field         | Value                           |
-|---------------|---------------------------------|
-| **PRD ID**    | {TICKET-ID}                     |
-| **Version**   | 1.0                             |
-| **Status**    | draft / review / approved       |
-| **Author**    | {PO name or "AI-assisted"}      |
-| **Domain**    | {domain: loyalty, identity, …}  |
-| **Created**   | {YYYY-MM-DD}                    |
-| **Updated**   | {YYYY-MM-DD}                    |
+| Field         | Value                                    |
+|---------------|------------------------------------------|
+| **PRD ID**    | {TICKET}-{N}                             |
+| **Version**   | 1.0                                      |
+| **Status**    | draft                                    |
+| **Author**    | AI-assisted                              |
+| **Domain**    | {domain}                                 |
+| **Created**   | {date}                                   |
+| **Updated**   | {date}                                   |
+| **Jira Ticket** | [{TICKET}-{N}]({ticket_url})            |
+| **API Source** | *(để trống nếu greenfield — chỉ điền `existing` khi PRD bọc một API đã chạy production)* |
 
 ---
 
 # Feature
 
-{Tên tính năng chính và mô tả capability hoặc chức năng mà sản phẩm cung cấp.}
+**{Feature Name}**
+
+{Đoạn mô tả tổng quan: feature làm gì, cho ai, giải quyết vấn đề gì — lấy từ product-definition.}
 
 ---
 
@@ -92,184 +62,83 @@
 
 ## a. User Story
 
-<!--
-  ĐỊNH NGHĨA: Mô tả ngắn gọn nhu cầu của người dùng theo góc nhìn nghiệp vụ.
-  Trả lời câu hỏi: "Ai cần gì và tại sao?" — KHÔNG mô tả kỹ thuật.
-
-  QUY TẮC VIẾT:
-  - {User role}     → Vai trò người dùng (ví dụ: Consumer, Merchant Admin, Cashier)
-  - {User goal}     → Mục tiêu người dùng muốn đạt được (hành động/chức năng cụ thể)
-  - {Business value}→ Giá trị nghiệp vụ mang lại (lý do tại sao người dùng cần điều này)
--->
-
-- **As a** {User role}
-- **I want to** {User goal}
-- **So that** {Business value}
+- **Là một (As a)** {persona}
+- **Tôi muốn (I want to)** {action}
+- **Để (So that)** {benefit}
 
 ## b. Phạm vi
 
-<!--
-  ĐỊNH NGHĨA: Liệt kê danh sách các chức năng thuộc feature này.
-  Trả lời câu hỏi: "Feature này làm gì?" — giúp xác định ranh giới, tránh scope creep.
-
-  QUY TẮC VIẾT:
-  - Mỗi dòng là một chức năng/capability cụ thể mà feature này cung cấp.
-  - Chỉ liệt kê những gì được làm trong ticket này. Nếu có chức năng liên quan nhưng
-    KHÔNG thuộc ticket này → KHÔNG đưa vào danh sách.
-  - Viết ngắn gọn, súc tích, đủ để người đọc hiểu mà không cần giải thích thêm.
--->
-
 **In Scope**
+- {hạng mục trong phạm vi 1}
+- {hạng mục trong phạm vi 2}
 
-- {Chức năng thuộc feature}
+**Out of Scope** *(chỉ thêm khi có ranh giới cần nói rõ)*
+- {hạng mục ngoài phạm vi + lý do / chủ sở hữu}
 
 ---
 
 # 2. Acceptance Criteria
 
-<!--
-  ĐỊNH NGHĨA: Danh sách điều kiện cần thỏa mãn để tính năng được coi là hoàn thành.
-  Trả lời câu hỏi: "Khi nào thì feature này được coi là DONE?" — tiêu chí để QA kiểm thử và PO sign-off.
-
-  QUY TẮC VIẾT:
-  - Viết theo góc nhìn người dùng: "Người dùng có thể...", "Hệ thống cho phép..."
-  - Mỗi AC phải testable (có thể kiểm tra được — pass hoặc fail rõ ràng).
-  - Chỉ ghi các tiêu chí CỐT LÕI — khi tính năng đạt được những điều này thì người dùng
-    đã có thể sử dụng được. Không ghi tiêu chí phụ hoặc edge case nhỏ.
-
-  KHÔNG viết AC về:
-  - UI/UX (màu sắc, vị trí nút, font chữ, animation) → thuộc Wireframe.
-  - Chi tiết kỹ thuật hoặc logic xử lý nội bộ → thuộc Business Rule / Business Logic.
--->
+**AC1:** {Tiêu chí nghiệm thu, văn xuôi, kiểm chứng được.}
 
-- **AC1:** {Điều kiện chấp nhận}
-- **AC2:** {Điều kiện chấp nhận}
-- **AC3:** {Điều kiện chấp nhận}
+**AC2:** {…}
 
 ---
 
 # 3. Use Case
 
-<!--
-  ĐỊNH NGHĨA — USE CASE (UC):
-  Mô tả một kịch bản nghiệp vụ cụ thể từ góc nhìn người dùng tương tác với hệ thống.
-  Trả lời câu hỏi: "Người dùng tương tác với hệ thống như thế nào trong từng tình huống?"
-  - Actor         → Ai thực hiện hành động trong kịch bản này
-  - Description   → Tóm tắt kịch bản bằng 1 câu
-  - Pre-condition → Điều kiện PHẢI đúng TRƯỚC KHI Use Case bắt đầu (trạng thái hệ thống, quyền, dữ liệu)
-  - Post-condition→ Trạng thái/kết quả SAU KHI Use Case hoàn thành thành công
-
-  ĐỊNH NGHĨA — BUSINESS RULE (BR):
-  Quy tắc nghiệp vụ mà hệ thống bắt buộc phải tuân theo — viết thành một câu rõ ràng, ngắn gọn, dễ hiểu.
-  Trả lời câu hỏi: "Hệ thống PHẢI làm gì / KHÔNG được làm gì?" (WHAT)
-  - Là ràng buộc không thể thương lượng, xuất phát từ yêu cầu nghiệp vụ.
-  - Mỗi BR chỉ phát biểu MỘT quy tắc duy nhất, không gộp nhiều quy tắc vào một dòng.
-
-  ĐỊNH NGHĨA — BUSINESS LOGIC (BL):
-  Cách thực thi cụ thể của một Business Rule — mô tả các điều kiện và logic chi tiết.
-  Trả lời câu hỏi: "Hệ thống thực hiện quy tắc đó cụ thể như thế nào?" (HOW)
-  - Các điều kiện rẽ nhánh (if/else, trường hợp A / trường hợp B)
-  - Công thức tính toán hoặc quy tắc áp dụng theo từng trường hợp
-  - Thứ tự xử lý, ưu tiên, các trường hợp ngoại lệ
-  - Đây là input trực tiếp để developer implement.
-
-  NUMBERING CONVENTION:
-  - UC ID: format {TICKET_ID}-UC{N}
-    + {TICKET_ID} = Jira Ticket ID (e.g., LOYAL-29)
-    + {N} = UC number within this PRD (1, 2, 3, ...)
-    + E.g.: LOYAL-29-UC1, LOYAL-29-UC2, LOYAL-29-UC3, ...
-  - BR ID: format {TICKET_ID}-UC{N}-BR{M}
-    + {M} = BR number incrementing from 1 across the PRD (not reset per UC, not global)
-    + E.g.: LOYAL-29-UC1-BR1, LOYAL-29-UC1-BR2, LOYAL-29-UC2-BR3, ...
--->
+#### {TICKET}-{N}-UC1: {Tên use case}
 
-#### {TICKET_ID}-UC1: {Tên Use Case}
+**Actor:** {actor}
 
-- **Actor:** {Người dùng thực hiện}
-- **Description:** {Mô tả ngắn gọn kịch bản nghiệp vụ}
-- **Pre-condition:** {Điều kiện cần trước khi Use Case bắt đầu}
-- **Post-condition:** {Kết quả sau khi Use Case hoàn thành}
+**Description:** {mô tả luồng}
 
-**Business Rule**
+**Pre-condition:**
+- {điều kiện trước 1}
 
-| ID | Business Rule |
-|----|---------------|
-| {TICKET_ID}-UC1-BR1 | |
+**Post-condition:**
+- {kết quả sau 1}
 
-**Business Logic**
+**Business Rule**
 
-**{TICKET_ID}-UC1-BR1:**
-- Logic 1
-- Logic 2
-- Logic 3
+| ID | Business Rule | Business Logic |
+|----|---------------|----------------|
+| {TICKET}-{N}-UC1-BR1 | {luật ngắn gọn} | - {logic chi tiết, xuống dòng bằng `<br/>`}<br/>- {…} |
+| {TICKET}-{N}-UC1-BR2 | {…} | - {…} |
 
 ---
 
-# 4. UI/UX Guidelines
-
-## a. User Flow
+#### {TICKET}-{N}-UC2: {Tên use case}
 
-<!--
-  ĐỊNH NGHĨA: Sơ đồ trực quan mô tả trình tự các bước và nhánh quyết định mà người dùng đi qua.
-  Trả lời câu hỏi: "Người dùng đi qua những bước nào và hệ thống phản hồi ra sao?"
+{lặp cấu trúc UC như trên; BR đánh số tiếp tục BR3, BR4…}
 
-  QUY TẮC VIẾT (Mermaid flowchart):
-  - Start/Entry  → Điểm vào: người dùng bắt đầu từ đâu (màn hình nào, hành động nào)
-  - Process      → Bước xử lý: hình chữ nhật [ ] — hành động hoặc hiển thị của hệ thống
-  - Decision     → Điểm rẽ nhánh: hình thoi { } — điều kiện dẫn đến kết quả khác nhau
-  - End State    → Trạng thái kết thúc: kết quả cuối cùng người dùng nhận được
+---
 
-  Mỗi nhánh Decision phải có label rõ ràng (|Có|, |Không|, |Thành công|, |Thất bại|...).
-  Bao gồm cả luồng lỗi / luồng ngoại lệ quan trọng (không chỉ happy path).
--->
+# 4. UI/UX Guidelines
 
-{Flowchart mô tả trình tự các bước và các nhánh quyết định (Start/Entry → Process → Decision → End State)}
+## a. User Flow
 
 ```mermaid
 flowchart TD
-    A[Bước 1: ...] --> B[Bước 2: ...]
-    B --> C{Điều kiện?}
-    C -->|Có| D[Bước 3a: ...]
-    C -->|Không| E[Bước 3b: ...]
+    START(["{điểm bắt đầu}"]) --> A{"{điểm quyết định}"}
+    A -->|{nhánh}| B["{bước}"]
 ```
 
 ## b. Wireframe
 
-<!--
-  ĐỊNH NGHĨA: Mô tả bố cục và thành phần UI của từng màn hình.
-  Trả lời câu hỏi: "Màn hình trông như thế nào và người dùng tương tác với nó ra sao?"
-  Là cầu nối giữa nghiệp vụ và thiết kế UI. Có thể kèm link Figma hoặc ảnh mockup.
-
-  CẤU TRÚC BẢNG CHUẨN (3 thành phần chính):
-  - Screen     → Tên màn hình / modal / trạng thái đang mô tả
-  - Components → Danh sách các thành phần UI hiển thị (button, label, list, input, bar...)
-  - Actions    → Hành động người dùng thực hiện và kết quả/màn hình tiếp theo tương ứng
-
-  LƯU Ý — CẤU TRÚC LINH HOẠT THEO ĐỘ PHỨC TẠP:
-  Với màn đơn giản → dùng bảng 3 cột chuẩn (Screen / Components / Actions) là đủ.
-  Với màn phức tạp (nhiều trạng thái, nhiều modal, nhiều luồng lỗi) → có thể mở rộng:
-  - Tách riêng từng màn / modal / trạng thái thay vì gộp chung một bảng.
-  - Thêm các field chi tiết hơn nếu cần (UI Pattern, Header, Footer, Toast, Entry Point...).
-  Nguyên tắc: ưu tiên sự rõ ràng hơn tuân thủ cứng nhắc cấu trúc —
-  miễn là designer, dev, QA đọc vào hiểu đúng ý định của màn hình đó.
--->
-
-**Screen N: {Tên màn hình}**
-
-**Screen:** {Tên màn hình}
+### Screen 1: {Tên màn}
 
-**Components:**
-- {Component 1}
-- {Component 2}
-- {Component 3}
+| Thành phần | Chi tiết |
+|------------|----------|
+| **Screen** | {tên/ngữ cảnh màn} |
+| **Components** | - {thành phần 1}<br/>- {thành phần 2} |
+| **Actions** | - {hành động 1 → kết quả}<br/>- {hành động 2 → kết quả} |
 
-**Actions:**
-- {Hành động 1} → {Kết quả}
-- {Hành động 2} → {Kết quả}
+---
 
-<!-- Figma Design: {Link Figma — xóa dòng này nếu không có URL} -->
+### Screen 2: {Tên màn}
 
-<!-- ![Wireframe mô tả](./assets/wireframe-name.png) -->
+{lặp bảng như trên cho từng màn}
 
 ---
 
@@ -277,51 +146,57 @@ flowchart TD
 
 ## Input gốc từ PO
 
-> Lưu lại nguyên văn input ban đầu (text + links đến hình ảnh).
-
-{Paste original input here}
+> {Trích nguyên văn input/ghi chú gốc của PO + đường dẫn product-definition nguồn.}
 
 ## Tài liệu tham khảo
 
+- [{TICKET liên quan}](./{file}.md) — {quan hệ: pre-condition / overlapping / related…}
+- Từ điển nghiệp vụ: `{path}/business-dictionary.md`
+- Domain knowledge: `{path}/{domain}.md`
+
+## Existing API Contract *(CHỈ brownfield — điền khi API Source = existing; greenfield BỎ QUA cả section này)*
+
 <!--
-  Cross-reference PRD liên quan dùng format: [TICKET-ID](./TICKET-ID-slug.md) — {quan hệ phụ thuộc}
-  Ví dụ:
-  - [LOYAL-23](./LOYAL-23-cau-hinh-chi-nhanh.md) — Pre-condition: Branch phải được cấu hình trước
-  - [LOYAL-10](./LOYAL-10-onboarding-merchant.md) — Entity dùng chung: Merchant/Tenant
+  Chỉ dùng khi PRD bọc một API đã tồn tại trên hệ thống. PO ghi lại contract để:
+  - /generate-bdd (system) dùng trực tiếp làm input — không cần tổng hợp từ FE/App BDD;
+  - /generate-tech-docs chạy mode reverse-document (mô tả lại as-is, không design mới);
+  - /review-tech-docs bỏ qua cổng T7 cross-team sign-off (contract đã cố định).
+  Nếu greenfield (thiết kế mới) → xoá toàn bộ section này.
 -->
 
-- {[TICKET-ID](./TICKET-ID-slug.md) — mô tả quan hệ phụ thuộc}
+| 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} |
 
 ## Giả định AI
 
-> Các giả định AI đưa ra khi PO chọn "skip" hoặc thông tin chưa đầy đủ.
-> Mỗi giả định cần được PO review và confirm.
+> {Giả định / độ vênh AI phát hiện khi đối chiếu product-definition với domain-knowledge — cần PO review. AI KHÔNG tự hoà giải.}
 
-- {Giả định 1 — [AI DRAFT]}
-- {Giả định 2 — [AI DRAFT]}
+- **Q1 — [AI DRAFT] {tiêu đề}:** {mô tả độ vênh + nguồn}. **Cần PO chốt {điều gì}.**
 
----
+_(Nếu không có độ vênh: ghi "Không có — toàn bộ nội dung đã được PO xác nhận qua Product Definition.")_
 
-## Changelog
+---
 
-<!--
-  Version history — mỗi lần PRD được cập nhật (qua /refine-prd --resume hoặc PO tự sửa)
-  → thêm 1 dòng mới vào đầu bảng này với version mới.
+# Change Log
 
-  Version bumping rules:
-  - Major (X.0 → X+1.0): thêm/xoá Use Case, thay đổi scope lớn, breaking BR change
-  - Minor (x.Y → x.Y+1): làm rõ AC/BR, thêm edge case, cập nhật wording
+### v1.0 — {mô tả} ({date})
 
-  BDD và Code đọc version này qua @trace.prd_version để detect drift.
--->
+| Mục | Thay đổi |
+|-----|----------|
+| — | Bản đầu — sinh từ product-definition. |
 
-| Version | Date | Changes |
-|---------|------|---------|
-| 1.0 | {YYYY-MM-DD} | Initial version |
+---
 
-<!-- 
+<!--
   NEXT STEPS:
   Khi PRD được approve (status: approved), chạy:
-  /generate-bdd "path/to/this-prd.md"
+  /generate-bdd "specs/{domain}/{prd-slug}/prd.md"
   để sinh BDD feature specs từ PRD này.
 -->