@educa-corp/sdd-framework 0.5.0 → 0.7.0

package/templates/feature.template

@@ -1,123 +0,0 @@
-# ============================================================
-# @trace.id: {TICKET-ID}-UC{N}
-# @trace.title: <Feature name>
-# @trace.revision: 1  ← field tĩnh; version theo dõi bằng @trace.bdd_version
-# @trace.domain: <domain>
-# @trace.platform: {active_platform — web | app | system}   ← BẮT BUỘC mọi mode; phải khớp segment bdd/{platform}/ của path
-# @trace.service: {active_service — BẮT BUỘC mọi mode. "—" ở single-service/spec repo mode; "multi" nếu chưa chốt; "unresolved" nếu routing sai. Nguồn của cột TSV `service` — trace gộp không tách theo service nên đây là chỗ DUY NHẤT mang thông tin sở hữu}
-# @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: {cấp FILE — 1.0 nếu gen mới; tăng 0.1 khi gen lại. Khác @trace.sc_version (cấp từng SC) bên dưới}
-# @trace.business_rules: {TICKET-ID}-UC{N}-BR{m}, {TICKET-ID}-UC{N}-BR{m+1}   ← {m} lấy NGUYÊN từ PRD §3: BR đánh số LIÊN TỤC toàn PRD, KHÔNG reset theo UC
-# @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   ← cấp SCENARIO. Sửa thân SC này (tên/step/table/side-effect) thì +0.1, nếu không code cũ mãi hiện OK
-  # @trace.business_rules: {TICKET-ID}-UC{N}-BR{m}
-  @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}-BR{m}
-  @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}-BR{m+2}
-  @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}-BR{m}   (...) → SC1, SC2
-#   {TICKET-ID}-UC{N}-BR{m+2} (...) → 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
-# - [ ] SỬA nội dung một SC (tên / step / data table / side-effect) → đã bump @trace.sc_version của
-#       CHÍNH SC đó (+0.1). Quên bump = code sinh từ SC cũ vẫn hiện OK, không ai biết phải regen.
-#       (Đổi @trace.business_rules / tag / comment → KHÔNG bump: không đổi hành vi cần implement.)
-# - [ ] 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

@@ -1,145 +0,0 @@
-# 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

@@ -1,283 +0,0 @@
-# {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 BR: MẶC ĐỊNH bảng 3 cột — ID | Business Rule | Business Logic
-    (KHÔNG tách Business Logic ra khối riêng).
-    NGOẠI LỆ — MỞ CỘT: nếu MỌI BR trong một UC chia sẻ cùng một bộ thuộc tính lặp lại
-    (vd trigger / data / tần suất), promote các thuộc tính đó thành CỘT RIÊNG —
-    một bản ghi = một DÒNG. Dấu hiệu tự phát hiện: đang phải dùng <br/> để nhồi
-    NHIỀU HƠN MỘT bản ghi cùng cấu trúc vào một ô. Chi tiết + cảnh báo BR ID churn:
-    xem §3 "Business Rule" của template và mục "Hình dạng bảng Business Rule" của lệnh.
-
-  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ó"
-
-## d. Quy ước *(TUỲ CHỌN — chỉ thêm khi tài liệu có quy ước áp dụng xuyên suốt; nếu không có → XOÁ HẲN section này)*
-
-> Khai báo **MỘT LẦN** các quy ước áp dụng cho **mọi BR** ở §3. BR **KHÔNG** lặp lại nội dung đã khai ở đây,
-> AC §2 **trỏ tới** quy ước thay vì chép lại. Đây là nơi chứa định nghĩa dùng chung, giá trị mặc định,
-> và cách đọc các cột của bảng BR — những thứ trước đây bị xé nhỏ và lặp trong từng dòng.
->
-> Phân biệt với **§1b Phạm vi** (ranh giới làm/không làm) và **business-dictionary** (định nghĩa thuật ngữ
-> cấp domain, dùng chung nhiều PRD): §1d chỉ chứa quy ước **cục bộ của tài liệu này**.
-
-- **{Tên quy ước}**: {nội dung áp dụng cho mọi BR bên dưới}
-- **{Giá trị mặc định dùng chung}**: {…}
-
----
-
-# 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**
-
-> **Hình dạng bảng — mặc định 3 cột.** Dùng dạng này khi Business Logic là **văn xuôi** (mô tả luật bằng câu).
-
-| 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 | {…} | - {…} |
-
-<!--
-  NGOẠI LỆ — MỞ CỘT (dùng THAY cho bảng 3 cột ở trên, KHÔNG dùng cả hai):
-
-  Điều kiện kích hoạt: MỌI BR trong UC này chia sẻ CÙNG một bộ thuộc tính lặp lại.
-  Dấu hiệu tự phát hiện: đang phải dùng <br/> để nhồi NHIỀU HƠN MỘT bản ghi cùng
-  cấu trúc vào một ô Business Logic.
-
-  Khi kích hoạt: promote thuộc tính thành CỘT, một bản ghi = một DÒNG:
-
-    | ID  | Business Rule | {Thuộc tính 1} | {Thuộc tính 2} | {Thuộc tính 3} |
-    |-----|---------------|----------------|----------------|----------------|
-    | BR1 | {luật ngắn}   | {giá trị}      | {giá trị}      | {giá trị}      |
-    | BR2 | {luật ngắn}   | {giá trị}      | {giá trị}      | {giá trị}      |
-
-  Hai cột ID + Business Rule LUÔN giữ (traceability phụ thuộc chúng). Chỉ cột
-  Business Logic được tách thành N cột. Giá trị dùng chung cho mọi dòng → đưa lên
-  §1d Quy ước, ĐỪNG lặp trong từng ô.
-
-  ⚠️ CẢNH BÁO BR ID CHURN — đọc trước khi mở cột trên PRD ĐÃ TỒN TẠI:
-  Mở cột đúng nghĩa = một bản ghi một dòng ⇒ số BR TĂNG. Vì BR ID tăng liên tục
-  trên toàn PRD, chèn dòng ở giữa sẽ ĐÁNH SỐ LẠI mọi BR phía sau. Nếu PRD này đã có
-  BDD downstream, mọi tag `@trace.business_rules` trong .feature sẽ trỏ SAI trong im lặng.
-  → Trước khi mở cột trên PRD đã có: kiểm tra `{specs_dir}/{domain}/{prd-slug}/bdd/`.
-    - Chưa có BDD → mở cột tự do.
-    - ĐÃ có BDD → DỪNG, báo người dùng: cần re-gen BDD sau khi đổi, hoặc giữ nguyên hình dạng cũ.
-  PRD sinh MỚI không bị ảnh hưởng (chưa có downstream).
--->
-
-> **Note {BR ref}:** *(TUỲ CHỌN)* {giải thích **quyết định đã chốt** — vì sao luật này như vậy, ràng buộc
-> nào dẫn tới nó, biên nào đã cân nhắc}. Đặt ngay sau bảng, cạnh nơi phát sinh.
->
-> **Ranh giới với "Giả định AI" (Appendix):** Note = quyết định **đã chốt**, giải thích cho người đọc sau.
-> Giả định AI = **độ vênh CẦN PO chốt**. Note **KHÔNG** được nuốt Giả định AI — nghi ngờ thì để ở Giả định AI.
-
----
-
-#### {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
-
-> **KHÔNG nhân bản §3.** Wireframe liệt kê **màn + thành phần + hành động** — nó là nguồn coverage màn hình
-> cho `/generate-bdd` (C.1), KHÔNG phải bản sao thứ hai của bảng Business Rule.
-> Nếu một dòng Wireframe không thêm thông tin nào ngoài BR đã có → **tham chiếu BR ID, đừng chép nội dung**.
-> Nếu cả §4b không thêm gì mới so với §3 → **xoá hẳn §4b** (hai nguồn sự thật cho cùng một dữ liệu sẽ lệch nhau
-> ngay lần sửa đầu tiên).
-
-### 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.
--->