@educa-corp/sdd-framework 0.1.0

package/templates/feature.template

@@ -0,0 +1,120 @@
+# ============================================================
+# @trace.id: {TICKET-ID}-UC{N}
+# @trace.title: <Feature name>
+# @trace.revision: 1  ← field tĩnh; dùng @trace.bdd_version để theo dõi version (tăng bởi /review-context --fix hoặc --resume)
+# @trace.domain: <domain>
+# @trace.platform: {active_platform — web | app | system | (bỏ trong umbrella mode)}
+# @trace.service: {active_service — bỏ trong spec repo mode}
+# @trace.module: {active_module trong umbrella mode; "unknown" trong spec repo mode}
+# @trace.status: draft
+# @trace.author: AI-generated
+# @trace.created_at: {YYYY-MM-DD}
+# @trace.prd: {TICKET-ID}
+# @trace.prd_version: {đọc từ metadata PRD "| **Version** |"}
+# @trace.bdd_version: {1.0 nếu gen mới; tăng 0.1 khi gen lại — vd 1.0 → 1.1}
+# @trace.business_rules: {TICKET-ID}-UC{N}-BR1, {TICKET-ID}-UC{N}-BR2
+# @trace.dataset: {domain}.testdata.yaml
+# ============================================================
+
+# === CONTEXT ===
+# Actor:     <vai trò thực hiện hành động, vd: Consumer, Staff, System>
+# Screens:   <các màn liên quan, vd: Cart → Confirm Order → Order Detail>
+# Entities:  <business entity, vd: Order, OrderItem, Consumer>
+# Pre-state: <state dùng chung trước khi vào các scenario>
+
+# === SCOPE ===
+# In:  <UC này phủ gì>
+# Out: <cái gì KHÔNG thuộc UC này — link tới UC/feature khác (R10)>
+
+# === BUSINESS DEFINITION ===
+# Tham chiếu nhanh các term dùng trong feature này. Chi tiết SoT: business-dictionary.md
+# <Term 1>: <định nghĩa ngắn>
+# <Term 2>: <định nghĩa ngắn>
+#
+# --- Popup/Modal Lifecycle (tùy chọn — BẮT BUỘC nếu feature là popup/modal; Pre-merge yêu cầu) ---
+# - Open trigger:   <khi nào popup hiển thị, vd: click menu sidebar>
+# - Close trigger:  <khi nào popup đóng, vd: F5 / click X / ESC / navigate away>
+# - Refresh model:  <data refresh khi nào, vd: mỗi lần open (NO CACHE) / persisted / polling>
+# - State reset:    <state nào reset khi đóng/mở lại, vd: pagination, expand, dropdown selection>
+#
+# --- Display Logic Matrix (tùy chọn — BẮT BUỘC nếu display logic phụ thuộc ≥2 chiều; Pre-merge yêu cầu) ---
+# Liệt kê đủ ma trận N×M case + map mỗi case → SC. Tên SC theo pattern `<cấu trúc>: <outcome>` (KHÔNG dùng "(Case X)").
+# | # | Dim1 | Dim2 | Format hiển thị        | SC   |
+# |---|------|------|------------------------|------|
+# | 1 | 0    | 0    | `Tên hàng`             | SC{} |
+# | 2 | 0    | 1    | `Tên hàng (đơn vị)`    | SC{} |
+# | ... | ...  | ...  | ...                    | ...  |
+
+Feature: <Feature name>
+  As a <role>
+  I want to <action>
+  So that <business value>
+
+  Background:
+    Given <precondition dùng chung — dùng alias từ dataset, không phải ID kỹ thuật>
+
+  # ==========================================================
+  # NHÓM 1: <Business theme> (<BR refs>)
+  # ==========================================================
+
+  # Side-effects: <liệt kê ngắn các Then side-effect cần verify>
+  # @trace.scenario: {TICKET-ID}-UC{N}-SC1
+  # @trace.sc_version: 1.0
+  # @trace.business_rules: {TICKET-ID}-UC{N}-BR1
+  @happy
+  Scenario: <mô tả business outcome — dùng động từ chính xác: create/receive/assign/block>
+    Given <input state — alias từ dataset>
+    When <single action>
+    Then <main observable outcome>
+      And <side-effect 1 khai báo trong header>
+
+  # Side-effects: <...>
+  # @trace.scenario: {TICKET-ID}-UC{N}-SC2
+  # @trace.sc_version: 1.0
+  # @trace.business_rules: {TICKET-ID}-UC{N}-BR1
+  @happy @alternative
+  Scenario: <cùng theme NHÓM 1 nhưng path khác — vd: giá trị enum khác>
+    Given <state>
+    When <action>
+    Then <outcome>
+
+  # ==========================================================
+  # NHÓM 2: <Business theme 2> (<BR refs>)
+  # ==========================================================
+
+  # Side-effects: <...>
+  # @trace.scenario: {TICKET-ID}-UC{N}-SC3
+  # @trace.sc_version: 1.0
+  # @trace.business_rules: {TICKET-ID}-UC{N}-BR2
+  @edge
+  Scenario: <scenario boundary / error>
+    Given <state>
+    When <action>
+    Then <expected error handling>
+
+# === PRD COVERAGE (C.1 + C.2) ===
+# AC mapping:
+#   AC1 (...) → SC1, SC2
+#   AC2 (...) → SC3
+# BR mapping (mỗi bullet PHẢI có ≥1 SC — C.2):
+#   {TICKET-ID}-UC{N}-BR1 (...) → SC1, SC2
+#   {TICKET-ID}-UC{N}-BR2 (...) → SC3
+# Wireframe mapping (mỗi component/action ≥1 SC — C.1):
+#   Screen "<screen name>":
+#     [x] <action 1>  → SC1
+#     [x] <action 2>  → SC2
+#     [ ] <action 3>  → MISSING ← BLOCK MERGE
+# Design Spec coverage (chỉ FE/App — C.1 mở rộng; bỏ khối này nếu không nạp design-spec):
+#   Screen "<screen>": loading → SC?, error → SC?, empty → SC?
+#   AC-UI behavioral: AC-UI3 (lỗi+khôi phục) → SC?, AC-UI4 (empty CTA) → SC?
+#     (bỏ AC-UI visual thuần: AC-UI1 khớp Figma, AC-UI5 WCAG — Designer/QA review riêng)
+
+# === PRE-MERGE CHECKLIST ===
+# - [ ] Mỗi SC có Side-effects + @trace.scenario + @trace.sc_version + @trace.business_rules
+# - [ ] Coverage Matrix: 0 dòng MISSING (C.1)
+# - [ ] FE/App: mỗi Screen State (≠default) + AC-UI behavioral của design-spec có ≥1 SC (C.1 mở rộng)
+# - [ ] Mỗi AC/BR map tới ≥1 SC (C.2)
+# - [ ] 0 banned term (C.4) — grep file trước khi merge
+# - [ ] Feature ≥3 SC có NHÓM grouping theo business theme (C.5)
+# - [ ] Nếu popup/modal: khai báo Popup/Modal Lifecycle trong BUSINESS DEFINITION
+# - [ ] Nếu display logic ≥2 chiều: Display Logic Matrix trong BUSINESS DEFINITION

package/templates/platform-guide.template.md

@@ -0,0 +1,145 @@
+# Platform Guide — {{SERVICE_NAME}}
+
+> 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
+
+**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}}
+
+Trách nhiệm chính:
+- {{RESPONSIBILITY_1}}
+- {{RESPONSIBILITY_2}}
+- {{RESPONSIBILITY_3}}
+
+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
+
+Các entity chính và quan hệ của chúng:
+
+```
+{{ENTITY_1}} (aggregate root)
+  ├── {{CHILD_ENTITY_1}} (value object / child entity)
+  └── {{CHILD_ENTITY_2}}
+
+{{ENTITY_2}}
+  └── references {{ENTITY_1}} by ID
+```
+
+**{{ENTITY_1}}**:
+- Field chính: {{KEY_FIELDS}}
+- Vòng đời status: {{STATUS_1}} → {{STATUS_2}} → {{STATUS_3}}
+- Business rule: {{KEY_RULE_1}}
+
+**{{ENTITY_2}}**:
+- Field chính: {{KEY_FIELDS}}
+- Quan hệ: {{RELATIONSHIP_DESCRIPTION}}
+
+---
+
+# §3. Common Patterns
+
+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}}
+```
+// Khi nào dùng: {{USE_CASE}}
+// Ví dụ:
+{{CODE_EXAMPLE}}
+```
+
+## {{PATTERN_NAME_2}}
+```
+// Khi nào dùng: {{USE_CASE}}
+// Ví dụ:
+{{CODE_EXAMPLE}}
+```
+
+---
+
+# §4. Integration Points
+
+## Upstream Dependencies (service này gọi các bên dưới)
+
+| 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 (các bên dưới gọi ta hoặc tiêu thụ event của ta)
+
+| Consumer | Cái họ dùng   | Protocol |
+|----------|---------------|----------|
+| {{DOWNSTREAM_1}} | {{WHAT}} | REST/Event |
+| {{DOWNSTREAM_2}} | {{WHAT}} | REST/Event |
+
+## Event phát ra (Produced)
+
+| Tên event | Trigger | Tóm tắt payload |
+|------------|---------|-----------------|
+| {{EVENT_1}} | {{WHEN}} | {{PAYLOAD_FIELDS}} |
+| {{EVENT_2}} | {{WHEN}} | {{PAYLOAD_FIELDS}} |
+
+## Event tiêu thụ (Consumed)
+
+| Tên event | Từ service | Ta làm gì với nó |
+|------------|-------------|-------------------|
+| {{EVENT_1}} | {{SOURCE}} | {{HANDLER_ACTION}} |
+
+---
+
+# §5. Known Constraints
+
+## 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}}
+
+## Ràng buộc business rule
+- {{BUSINESS_CONSTRAINT_1}}  # vd: "Không thể huỷ order sau khi đã ship"
+- {{BUSINESS_CONSTRAINT_2}}
+
+## 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}}
+
+## Technical Debt đã biết
+- {{TECH_DEBT_1}}  # vd: "OrderItem.price bị nhân bản từ catalog — đồng bộ qua job hằng đêm"
+
+---
+
+# §6. Directory Structure
+
+```
+{{SERVICE_ROOT}}/
+├── {{SOURCE_DIR}}/              # Code nguồn chính
+│   ├── {{LAYER_1}}/             # vd: controller/ hoặc handler/
+│   │   └── {{EXAMPLE_FILE}}
+│   ├── {{LAYER_2}}/             # vd: service/ hoặc usecase/
+│   │   └── {{EXAMPLE_FILE}}
+│   ├── {{LAYER_3}}/             # vd: repository/ hoặc repo/
+│   │   └── {{EXAMPLE_FILE}}
+│   └── {{LAYER_4}}/             # vd: model/ hoặc domain/
+│       └── {{EXAMPLE_FILE}}
+├── {{TEST_DIR}}/                # Test phản chiếu cấu trúc src
+├── specs/                       # File BDD feature
+│   └── bdd/
+│       └── {{DOMAIN}}/
+│           └── {{UC-ID}}-{{slug}}.feature
+└── {{CONFIG_FILE}}              # vd: application.yaml / appsettings.json
+```
+
+**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/templates/prd.template.md

@@ -0,0 +1,224 @@
+# {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ế.
+
+  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 khác](../{prd-slug-khác}/{TICKET-ID-khác}-{prd-slug-khác}.md)
+    Không để TICKET-ID dạng plain text nếu tồn tại file PRD tương ứng. (Mỗi PRD nằm trong feature-package riêng nên link trỏ sang folder anh em `../{prd-slug-khác}/`.)
+    Ngoài ra, ghi rõ quan hệ phụ thuộc trong "Tài liệu tham khảo" ở Appendix.
+
+  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.
+
+  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}-{N}                             |
+| **Version**   | 1.0                                      |
+| **Status**    | draft                                    |
+| **Author**    | AI-assisted                              |
+| **PO**        | {tên PO}                                 |
+| **Domain**    | {domain}                                 |
+| **Created**   | {date}                                   |
+| **Updated**   | {date}                                   |
+| **Ticket**    | {TICKET}-{N}{ — nếu PO có link tracker thật, thêm bên cạnh: `{TICKET}-{N} ([Jira]({tracker_url}))`} |
+| **API Source** | *(để trống nếu greenfield — chỉ điền `existing` khi PRD bọc một API đã chạy production)* |
+
+---
+
+# Feature
+
+**{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.}
+
+---
+
+# 1. Tổng quan
+
+## a. User Story
+
+- **Là một (As a)** {persona}
+- **Tôi muốn (I want to)** {action}
+- **Để (So that)** {benefit}
+
+## b. Phạm vi
+
+> **Scope = ranh giới, KHÔNG phải đặc tả.** Mỗi mục một dòng ngắn "làm gì / không làm gì". Đừng nhét **cơ chế** (retry/timeout/nhánh lỗi → BR/BL) hay **định nghĩa thuật ngữ** (vd "điểm khởi tạo = …" → Business Definition / business-dictionary) vào đây.
+
+**In Scope**
+- {hạng mục trong phạm vi 1}
+- {hạng mục trong phạm vi 2}
+
+**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}
+
+## c. Phụ thuộc liên service *(mức nghiệp vụ — KHÔNG mô tả API/event/kỹ thuật)*
+
+> Kế thừa từ Product Definition Phase 1 ("Phụ thuộc liên service"). Nếu contract do đối tác phát triển song song (xem `API Source`), ghi phụ thuộc partner vào đây.
+
+- {Cần {dữ liệu/năng lực} từ {feature/team/partner} — vì {lý do nghiệp vụ}} — hoặc "Không có"
+
+---
+
+# 2. Acceptance Criteria
+
+> Mỗi AC kế thừa liên kết "Bắt nguồn từ BR" của Product Definition (Phase 6), remap sang BR ID của PRD. Vì BR ID đã chứa số UC nên ref BR truy ngược được tới đúng UC.
+>
+> **1 AC = 1 tiêu chí NGHIỆM THU (outcome quan sát/kiểm được) + ref BR.** KHÔNG viết cơ chế trong AC (số lần retry, timeout, tên/chủ cờ, nhánh lỗi chi tiết) — cái đó thuộc **BR/BL** ở §3, AC chỉ trỏ tới. Nếu tiêu chí có **nhiều nhánh** → tách **bullet con** (mỗi ý một dòng), đừng dồn thành câu dài. Khi `/refine-prd` làm rõ thêm: chi tiết cơ chế → đẩy sang BR/BL; ở tầng AC thì tách bullet/AC mới — KHÔNG nối mệnh đề vào câu cũ (tránh AC thành "đoạn văn" và trùng BR).
+
+**AC1:** {Tiêu chí nghiệm thu, văn xuôi, kiểm chứng được.} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
+
+**AC2:** {Tiêu chí có nhiều nhánh — tách bullet:} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
+  - {nhánh/điều kiện 1 → kết quả kỳ vọng}
+  - {nhánh/điều kiện 2 → kết quả kỳ vọng}
+
+---
+
+# 3. Use Case
+
+#### {TICKET}-{N}-UC1: {Tên use case}
+
+**Actor:** {actor}
+
+**Description:** {mô tả luồng}
+
+**Pre-condition:**
+- {điều kiện trước 1}
+
+**Post-condition:**
+- {kết quả sau 1}
+
+**AC liên quan:** AC{x}, AC{y}  *(các AC mà UC này thoả — phải đúng bằng tập AC có ref BR trỏ về UC này ở §2)*
+
+**Business Rule**
+
+| 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 | {…} | - {…} |
+
+---
+
+#### {TICKET}-{N}-UC2: {Tên use case}
+
+{lặp cấu trúc UC như trên; BR đánh số tiếp tục BR3, BR4…}
+
+---
+
+# 4. UI/UX Guidelines
+
+## a. User Flow
+
+```mermaid
+flowchart TD
+    START(["{điểm bắt đầu}"]) --> A{"{điểm quyết định}"}
+    A -->|{nhánh}| B["{bước}"]
+```
+
+## b. Wireframe
+
+### Screen 1: {Tên màn}
+
+| 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ả} |
+
+---
+
+### Screen 2: {Tên màn}
+
+{lặp bảng như trên cho từng màn}
+
+---
+
+# Appendix
+
+## Input gốc từ PO
+
+> {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}](../{prd-slug-khác}/{TICKET-ID-khác}-{prd-slug-khác}.md) — {quan hệ: pre-condition / overlapping / related…}
+- BDD: [`./bdd/`](./bdd/)
+- Design spec: [`./design-spec/`](./design-spec/) — không áp dụng với feature thuần backend (không có màn hình)
+- Từ điển nghiệp vụ: [`specs/domain-knowledge/business-dictionary.md`](../../domain-knowledge/business-dictionary.md)
+- Domain knowledge: [`specs/domain-knowledge/{domain}.md`](../../domain-knowledge/{domain}.md)
+
+## Existing API Contract *(CHỈ brownfield — điền khi API Source = existing; greenfield BỎ QUA cả section này)*
+
+<!--
+  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.
+-->
+
+| 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
+
+> {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.}
+
+- **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.")_
+
+---
+
+# Change Log
+
+> Hiện tại: **v1.0** ({date}) · Lịch sử đầy đủ → [changelog](./changelog/{TICKET}-{N}-{slug}.changelog.md) *(file kho chỉ tạo khi changelog vượt 5 version)*
+
+<!-- Bảng phẳng, MỘT dòng/version, MỚI NHẤT TRÊN CÙNG. Chỉ giữ tối đa 5 version gần nhất ở đây;
+     cũ hơn → /refine-prd & /review-context tự dồn (rollover) sang file changelog/ ở link trên. -->
+
+| Version | Date | Changes (UC/AC/BR bị ảnh hưởng) |
+|---------|------|---------------------------------|
+| 1.0 | {date} | Bản đầu — sinh từ product-definition. |
+
+---
+
+<!--
+  NEXT STEPS:
+  Khi PRD được approve (status: approved), chạy:
+  /generate-bdd "specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md"
+  để sinh BDD feature specs từ PRD này.
+-->

package/templates/product-definition.template.md

@@ -0,0 +1,188 @@
+# {TICKET-ID} Product Definition — {Feature Name}
+
+<!--
+  Template này được dùng bởi workflow /define-product.
+  AI Agent điền từng section qua Q&A theo từng phase với PO.
+  Output là input có cấu trúc cho /generate-prd.
+
+  QUY TẮC:
+  - Mỗi section tương ứng với 1 phase trong workflow
+  - Section chưa đủ → giữ placeholder, KHÔNG được sang phase tiếp theo
+  - Trạng thái xác nhận của PO được ghi trong mỗi section
+-->
+
+---
+
+## Metadata
+
+| Field              | Value                          |
+|--------------------|--------------------------------|
+| **Ticket**         | {TICKET-ID}                    |
+| **Feature**        | {tên tính năng}                |
+| **Domain**         | {domain}                       |
+| **PO**             | {tên PO}                       |
+| **Created**        | {YYYY-MM-DD}                   |
+| **Status**         | in-progress / completed        |
+| **Completed Phase**| {số phase hoàn thành gần nhất} |
+
+---
+
+## Phase 0: Đồng bộ tri thức (Knowledge Sync)
+
+> ⚙️ AI tự thu thập — đây là **bối cảnh hệ thống**, KHÔNG phải yêu cầu nghiệp vụ do PO viết. Mục đích: chuẩn hoá thuật ngữ và nhận biết phần đã có để tái sử dụng. Không cần input từ PO.
+
+### Khái niệm / dữ liệu nghiệp vụ liên quan
+- {Khái niệm 1} — {mô tả ngắn}
+- {Khái niệm 2} — {mô tả ngắn}
+
+### Phần hệ thống / feature liên quan
+- {Phần 1}
+- {Phần 2}
+
+### Rule / Logic có sẵn
+- {Rule/logic từ các PRD có sẵn hoặc domain knowledge}
+
+### Chuẩn hoá thuật ngữ
+| Thuật ngữ trong input PO | Thuật ngữ chuẩn (business-dictionary) |
+|--------------------------|---------------------------------------|
+| {thuật ngữ gốc}          | {thuật ngữ chuẩn}                     |
+
+---
+
+## Phase 1: Định nghĩa tính năng (Feature Definition)
+
+> ✅ PO xác nhận: {Có/Không}
+
+### Bối cảnh (Context)
+{Bối cảnh nghiệp vụ dẫn đến tính năng này}
+
+### Tuyên bố vấn đề (Problem Statement)
+{Vấn đề cần giải quyết}
+
+### Mục tiêu (Goal)
+{Mục tiêu của tính năng}
+
+### Actor
+| Actor    | Vai trò            | Chính/Phụ |
+|----------|--------------------|-----------|
+| {Actor}  | {mô tả vai trò}    | Primary   |
+
+### Phạm vi (In Scope)
+- {Chức năng 1}
+- {Chức năng 2}
+
+### Ngoài phạm vi (Out of Scope)
+- {Hạng mục KHÔNG làm trong ticket này — kèm lý do / để dành pha sau}
+
+### User Story
+- **Là một (As a)** {vai trò}
+- **Tôi muốn (I want to)** {mục tiêu}
+- **Để (So that)** {giá trị nghiệp vụ}
+
+### Phụ thuộc liên service *(mức nghiệp vụ)*
+
+> Feature này cần **dữ liệu/năng lực** gì từ feature/team khác — KHÔNG mô tả API/event/callback (đó là kỹ thuật, thuộc Tech-docs).
+
+- {Cần {dữ liệu/năng lực} từ {feature/team} — vì {lý do nghiệp vụ}} — hoặc "Không có"
+
+---
+
+## Phase 2: Định nghĩa User Flow
+
+> ✅ PO xác nhận: {Có/Không}
+
+### Điểm vào (Entry Point)
+{Người dùng bắt đầu tương tác với tính năng như thế nào}
+
+### Các bước của Flow
+| Bước | Hành động       | Trạng thái/Kết quả nghiệp vụ | Ghi chú    |
+|------|-----------------|------------------------------|------------|
+| 1    | {hành động}     | {trạng thái/kết quả nghiệp vụ} | {ghi chú}  |
+| 2    | {hành động}     | {trạng thái/kết quả nghiệp vụ} | {ghi chú}  |
+
+### Màn hình & thành phần chính
+> Mức nghiệp vụ — nguồn cho Wireframe PRD (§4b) và độ phủ BDD (C.1). KHÔNG pixel/layout/màu.
+
+| Màn hình | Thành phần chính | Hành động → kết quả nghiệp vụ |
+|----------|------------------|-------------------------------|
+| {màn 1}  | {thành phần}     | {hành động → kết quả}         |
+
+### Điểm ra (Exit Point)
+{Kết quả cuối khi flow hoàn thành}
+
+### Edge Cases / Luồng lỗi & ngoại lệ
+> Các kịch bản thất bại nghiệp vụ ngoài happy path — input thiếu, điều kiện không thoả, thao tác đồng thời, phụ thuộc không sẵn sàng.
+- {Kịch bản: khi {điều kiện bất thường} → {kết quả nghiệp vụ kỳ vọng}}
+
+---
+
+## Phase 3: Nhật ký làm rõ (Clarification Log)
+
+> Ghi lại mọi câu hỏi và câu trả lời qua các vòng.
+
+### Vòng {N}
+| # | Nhóm     | Câu hỏi    | PO trả lời |
+|---|----------|------------|------------|
+| 1 | Context  | {câu hỏi}  | {trả lời}  |
+| 2 | Flow     | {câu hỏi}  | {trả lời}  |
+| 3 | Logic    | {câu hỏi}  | {trả lời}  |
+
+### Mục chưa giải quyết
+- {Mục chưa giải quyết — nếu còn tồn đọng, KHÔNG được sang Phase 4}
+
+---
+
+## Phase 4: Business Rules
+
+> ✅ PO xác nhận: {Có/Không}
+
+| Rule ID | Hành động/Trigger   | Quy tắc             | Điều kiện              |
+|---------|---------------------|---------------------|------------------------|
+| BR-1    | {hành động từ flow} | {business rule}     | {điều kiện áp dụng}    |
+| BR-2    | {hành động từ flow} | {business rule}     | {điều kiện áp dụng}    |
+
+---
+
+## Phase 5: Business Logic
+
+> ✅ PO xác nhận: {Có/Không}
+
+| Rule ID | Logic nghiệp vụ (rẽ nhánh / công thức / điều kiện) | Thông báo/kết quả nghiệp vụ khi lỗi |
+|---------|---------------------------------------------------|-------------------------------------|
+| BR-1    | {logic nghiệp vụ khi rule kích hoạt}              | {vd: báo "Số dư không đủ"}           |
+| BR-2    | {logic nghiệp vụ khi rule kích hoạt}              | {…}                                 |
+
+---
+
+## Phase 6: Acceptance Criteria
+
+> ✅ PO xác nhận: {Có/Không}
+
+| AC ID | Mô tả                  | Hành vi kỳ vọng           | Bắt nguồn từ |
+|-------|------------------------|---------------------------|--------------|
+| AC-1  | {mô tả tiêu chí}       | {hành vi kỳ vọng}         | BR-{N}       |
+| AC-2  | {mô tả tiêu chí}       | {hành vi kỳ vọng}         | BR-{N}       |
+
+---
+
+## Phase 7: Báo cáo kiểm chứng (Validation Report)
+
+### Ma trận độ phủ (Coverage Matrix)
+| Hành động Flow | Có Rule? | Có Logic? | Có AC? | Status |
+|----------------|----------|-----------|--------|--------|
+| {Hành động 1}  | ✅/❌    | ✅/❌     | ✅/❌  | OK/GAP |
+
+### Xung đột phát hiện
+- {Mô tả xung đột — hoặc "None"}
+
+### Mục còn thiếu
+- {Rule/AC/logic còn thiếu — hoặc "None"}
+
+---
+
+<!--
+  NEXT STEPS:
+  Khi Product Definition hoàn tất (Status: completed), chạy:
+  /generate-prd {path-to-this-file}
+  để sinh PRD từ Product Definition này.
+-->