@educa-corp/sdd-framework 0.6.0 → 0.7.0

package/templates/design-spec.template.md

@@ -1,217 +0,0 @@
-# {TICKET-ID} {Feature Name} — Design Spec [{Platform}]
-
-<!--
-  Template này được sử dụng bởi /generate-design-spec.
-  Platform = web | app | app-ios | app-android
-
-  PLATFORM SECTIONS:
-  - Section 3A + 4A: chỉ dành cho web (react/nextjs/vue/angular). Xóa C khi dùng cho web.
-  - Section 3C + 4B: chỉ dành cho app (flutter/react-native/ios/android). Xóa A+B khi dùng cho app.
-
-  COMPONENT MAPPING (bắt buộc):
-  - Mọi component trong Component Inventory PHẢI được map với figma-components/{module}.md
-  - ✅ Matched     → dùng Code Component và Import Path từ catalog
-  - ⚠️ TODO        → đánh dấu [TODO — chưa implement]
-  - ❌ Chưa có     → đánh dấu [NEW — cần confirm với designer]
-
-  FIGMA LINKS (bắt buộc mỗi màn):
-  - Mỗi screen PHẢI có link Figma node-level (URL chứa ?node-id=...) — lấy bằng
-    right-click frame → "Copy link to selection". Đây là link AI đọc được qua Figma MCP.
-  - Link file trần (không có node-id) KHÔNG hợp lệ — AI không định vị được frame.
-  - Screen chưa có design → đánh dấu ❌ Missing; spec giữ Status "draft", chặn sign-off
-    và /generate-bdd cho tới khi đủ link.
-
-  SCREEN STATES (bắt buộc mỗi màn):
-  - Tối thiểu: default, loading, error
-  - Thêm "empty" nếu màn có thể hiển thị trạng thái không có dữ liệu
-  - Thêm "success" nếu action tạo ra trạng thái xác nhận riêng biệt
--->
-
----
-
-## Metadata
-
-| Field              | Value                                                         |
-|--------------------|---------------------------------------------------------------|
-| **Spec ID**        | {TICKET-ID}-DS-{platform}                                     |
-| **Version**        | 1.0                                                           |
-| **Status**         | draft / approved                                              |
-| **Platform**       | {web \| app \| app-ios \| app-android}                        |
-| **Module**         | {active_module}                                               |
-| **Service**        | {active_service}                                              |
-| **Domain**         | {domain}                                                      |
-| **Business PRD**   | [{TICKET-ID}](./{TICKET-ID}-slug.md)                          |
-| **Figma**          | {link file feature} ({linked}/{N} frame đã link)             |
-| **Author**         | {tên PO hoặc "AI-assisted"}                                   |
-| **Created**        | {YYYY-MM-DD}                                                  |
-| **Updated**        | {YYYY-MM-DD}                                                  |
-
----
-
-# 1. Danh mục màn hình (Screen Inventory)
-
-| # | Tên màn hình | Điểm vào | Figma Frame (link node-level) | Ghi chú |
-|---|-------------|-------------|-------------------------------|-------|
-| 1 | {Màn hình 1}  | {người dùng đến từ đâu} | [Frame]({node-level url}) | |
-| 2 | {Màn hình 2}  | {điểm vào} | ❌ Missing — thêm link node-id | |
-
----
-
-# 2. Đặc tả màn hình (Screen Specs)
-
-## Màn hình 1: {Tên màn hình}
-
-**Figma**: [{Tên frame}]({figma_frame_url})
-
-### Layout
-
-{Grid / max-width / padding / spacing — tham chiếu design token nếu áp dụng được}
-
-### Component Inventory
-
-| Component (Figma)      | Code Component | Import Path            | States                          | Ghi chú |
-|------------------------|----------------|------------------------|---------------------------------|---------|
-| {Figma/Button/Primary} | Button         | @/components/ui/Button | default, loading, disabled      |         |
-| {Figma/Input/Text}     | TextInput      | @/components/ui/Input  | default, focus, error, disabled |         |
-
-### Screen States
-
-| State     | Trigger                          | Hành vi UI                                              |
-|-----------|----------------------------------|----------------------------------------------------------|
-| default   | Màn đã load, có dữ liệu           | {Mô tả toàn bộ giao diện đã render}                      |
-| loading   | API đang gọi                      | {Vị trí và kiểu skeleton / spinner}                      |
-| error     | API thất bại / lỗi validation     | {Toast / lỗi inline / màn lỗi + CTA khôi phục}           |
-| empty     | Không có dữ liệu trả về            | {Illustration + CTA — vd: "Chưa có mục nào. Thêm mới →"} |
-| success   | Action hoàn tất (nếu có)          | {Toast xác nhận / điều hướng / thay đổi giao diện}       |
-
-### Actions & Navigation
-
-| Action          | Trigger                   | Kết quả                                           |
-|-----------------|---------------------------|---------------------------------------------------|
-| {Tên action}    | Tap/click {phần tử}       | Điều hướng tới {Màn hình N} / Mở {Tên modal}      |
-| {Back/Cancel}   | Cử chỉ back / nút          | Quay lại {màn trước} mà không lưu                  |
-
----
-
-<!--  Lặp lại ## Màn hình N cho mỗi màn bổ sung  -->
-
----
-
-# 3. Pattern tương tác (Interaction Patterns)
-
-<!-- === CHỈ WEB — xóa section này cho app === -->
-
-## A. Hành vi Responsive  *(web)*
-
-| Breakpoint | Width      | Thay đổi layout                             |
-|------------|------------|---------------------------------------------|
-| Mobile     | < 768px    | {1 cột, bottom nav, CTA full-width}         |
-| Tablet     | 768–1279px | {grid 2 cột, sidebar thu gọn}               |
-| Desktop    | ≥ 1280px   | {layout đầy đủ, max-width 1440px}           |
-
-## B. Hover / Focus / Keyboard  *(web)*
-
-| Phần tử        | Hover                         | Focus                           | Keyboard      |
-|----------------|-------------------------------|---------------------------------|---------------|
-| Primary button | Background → {color.hover}    | Outline 2px {color.focus}       | Enter / Space |
-| Text input     | Border → {color.border.hover} | Border → {color.primary}        | Tab to focus  |
-
-<!-- === CHỈ APP — xóa section A+B cho app === -->
-
-## C. Cử chỉ & Điều hướng  *(app)*
-
-| Cử chỉ               | Màn / Phần tử       | Hành vi                                     |
-|----------------------|---------------------|---------------------------------------------|
-| Cử chỉ back          | Mọi màn             | {Quay lại / hiện dialog "Discard changes?"} |
-| Pull-to-refresh      | {Tên màn}           | Refresh dữ liệu, spinner ở trên cùng        |
-| Swipe trái trên row  | {List item}         | Hiện action {Delete / Archive}              |
-
-### Navigation Stack  *(app)*
-
-```
-{vd: BottomTab(Home) → ListPage → DetailPage → EditPage}
-```
-
-### Platform Conventions  *(app)*
-
-| Khía cạnh        | iOS                                       | Android                             |
-|------------------|-------------------------------------------|-------------------------------------|
-| Navigation bar   | Nút back trên-trái, title canh giữa        | Mũi tên Up, title canh trái         |
-| Bottom sheet     | UISheetPresentation, hiện grabber          | BottomSheet, drag handle            |
-| Dialog           | Action canh phải                          | Action canh trái                    |
-
----
-
-# 4. Cân nhắc theo Platform (Platform Considerations)
-
-<!-- === CHỈ WEB === -->
-
-## A. Accessibility  *(web)*
-
-- [ ] Mọi phần tử tương tác đều tới được bằng phím Tab — không có keyboard trap
-- [ ] Focus trap bên trong modal
-- [ ] Nút chỉ có icon phải có `aria-label`
-- [ ] Nội dung động thông báo qua `aria-live`
-- [ ] Tương phản WCAG AA: text ≥ 4.5:1, text lớn ≥ 3:1
-- [ ] Input form có label hiển thị (không chỉ dùng placeholder)
-
-<!-- === CHỈ APP === -->
-
-## B. Thiết bị & OS  *(app)*
-
-- [ ] Áp dụng safe area insets (trên + dưới) ở mọi màn
-- [ ] Touch target tối thiểu: 44×44pt (iOS) / 48×48dp (Android)
-- [ ] Đã test trên 375pt (iPhone SE) và 360dp (Android nhỏ)
-- [ ] Deep link: `{scheme}://{host}/{path}` → {tên màn}
-- [ ] Permission: {Camera / Location / Notification} — nội dung lý do TBD
-- [ ] Offline: {tên màn} hiện dữ liệu cache + banner; {action} bị disable kèm tooltip
-- [ ] Đã test dark mode — không có màu hardcode
-
----
-
-# 5. AC-UI — Tiêu chí chấp nhận về Design
-
-> Được **PO + Designer** review và sign off trước khi sinh BDD.
-> Bổ sung cho AC mức nghiệp vụ trong [Business PRD](./{TICKET-ID}-slug.md).
-
-| ID     | Tiêu chí chấp nhận                                                       | Verified by     |
-|--------|--------------------------------------------------------------------------|-----------------|
-| AC-UI1 | Mọi màn khớp với frame Figma đã duyệt trong dung sai design-system        | Designer        |
-| AC-UI2 | Trạng thái loading xuất hiện trong vòng 200ms kể từ khi gọi API           | QA              |
-| AC-UI3 | Mọi thông báo lỗi đều hiển thị, rõ ràng, và kèm CTA khôi phục             | PO              |
-| AC-UI4 | Empty state có illustration và call-to-action                            | PO + Designer   |
-| AC-UI5 | {Tiêu chí riêng theo platform}                                           | QA              |
-
----
-
-# Appendix
-
-## Tóm tắt Figma
-
-| Màn hình   | Figma Frame (node-level) | Trạng thái Link / Fetch         |
-|------------|--------------------------|--------------------------------|
-| {Màn hình 1} | [Link]({node-level url}) | ✅ Đã link & fetch             |
-| {Màn hình 2} | —                        | ❌ Missing — không có link node-id |
-
-## Design Token đã tham chiếu
-
-| Token             | Value    | Dùng ở                     |
-|-------------------|----------|----------------------------|
-| `color.primary`   | {#hex}   | Button, link               |
-| `spacing.md`      | {16px}   | Khoảng cách dọc tiêu chuẩn |
-
-## Tài liệu tham khảo
-
-- [{TICKET-ID}](./{TICKET-ID}-slug.md) — Business PRD
-
-## Giả định AI
-
-- {Giả định — [AI DRAFT]}
-
----
-
-## Changelog
-
-| Version | Date         | Changes         |
-|---------|--------------|-----------------|
-| 1.0     | {YYYY-MM-DD} | Initial version |

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/hooks/pre-push

@@ -1,61 +0,0 @@
-#!/usr/bin/env sh
-# ─────────────────────────────────────────────────────────────────────────────
-# SDD Framework — git pre-push hook
-#
-# CÀI (từ gốc project):
-#   cp .agent/templates/hooks/pre-push .git/hooks/pre-push
-#   chmod +x .git/hooks/pre-push
-#
-# Trên Windows: Git for Windows chạy hook bằng sh nên file này dùng được như vậy.
-#
-# VÌ SAO CÓ HOOK NÀY khi đã có CI (GAPS-v3 G39/G40): nó chặn ở chỗ RẺ NHẤT.
-# Cụ thể là T7 — marker conflict git (`<<<<<<< HEAD`) lọt vào sổ trace. Một khi
-# thứ đó vào nhánh chung thì mọi người kéo về đều có sổ hỏng, và sổ trace là dữ
-# liệu KHÔNG dựng lại được. Bắt trước lúc push tốn 2 giây; bắt ở CI thì đã muộn
-# một vòng, bắt bằng mắt thì thường là ba tuần sau.
-#
-# CỐ Ý CHỈ LINT, KHÔNG GATE:
-#   --lint-trace  = cấu trúc sổ. Nhanh, offline được sau lần đầu, và một lỗi ở đây
-#                   LUÔN là lỗi thật (tab lệch, marker conflict, enum sai).
-#   --gate-trace  = cờ 🔴. Cần trace-report.json còn tươi, mà giữa lúc làm việc thì
-#                   nó thường chưa tươi — đỏ liên tục ⇒ người ta gõ --no-verify ⇒
-#                   mất luôn cả phần lint. Cờ 🔴 để CI chặn.
-#
-# Bỏ qua một lần (dùng có ý thức, đừng thành phản xạ):  git push --no-verify
-# ─────────────────────────────────────────────────────────────────────────────
-
-# Không có node thì im lặng cho qua — hook không được làm người ta không push được
-# vì lý do không liên quan tới việc họ đang làm.
-command -v node >/dev/null 2>&1 || exit 0
-
-# Không có sổ trace thì không có gì để kiểm (project chưa chạy /generate-bdd lần nào).
-# Sửa đường dẫn nếu trace_dir của project khác (vd ../.trace, hay {spec_source}/.trace).
-TRACE_DIR=".trace"
-[ -d "$TRACE_DIR" ] || exit 0
-
-echo "→ Lint sổ trace trước khi push ..."
-
-if npx -y @educa-corp/sdd-framework@latest --lint-trace --trace "$TRACE_DIR"; then
-  exit 0
-fi
-
-cat <<'MSG'
-
-──────────────────────────────────────────────────────────────────────
-🔴 PUSH BỊ CHẶN — sổ trace hỏng cấu trúc.
-
-Sổ trace là dữ liệu KHÔNG regenerate được. Đẩy một sổ hỏng lên nhánh
-chung thì mọi người kéo về đều nhận bản hỏng.
-
-Thường gặp nhất — marker conflict git chưa giải (T7):
-  1. Mở file lint vừa nêu, xoá 3 dòng <<<<<<<  =======  >>>>>>>
-  2. GIỮ CẢ HAI BÊN, đừng chọn một bên (mất row là mất vĩnh viễn)
-  3. npx @educa-corp/sdd-framework --lint-trace     # xác nhận sạch
-  4. /validate-traces trong Claude Code             # reconcile row trùng
-
-Playbook đầy đủ: docs/02-concepts/traceability.md
-Bỏ qua một lần: git push --no-verify
-──────────────────────────────────────────────────────────────────────
-
-MSG
-exit 1

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\")"