@educa-corp/sdd-framework 0.1.0

package/core/templates/design-spec.template.md

@@ -0,0 +1,217 @@
+# {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/core/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/core/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\")"