@educa-corp/sdd-framework 0.5.0 → 0.7.0

package/templates/architecture.template.md

@@ -1,394 +0,0 @@
----
-last_verified: {{YYYY-MM-DD}}
-verified_by: {{AUTHOR}}
----
-
-# {{SYSTEM_NAME}} — Bối cảnh Kiến trúc (Architecture Context)
-
-> Nguồn chân lý duy nhất (single source of truth) về kiến trúc hệ thống — phục vụ cả bối cảnh sinh code (AI agents) lẫn các vấn đề vận hành (triển khai, CI/CD, NFR).
->
-> HƯỚNG DẪN DÙNG TEMPLATE:
-> - Điền các `{{PLACEHOLDER}}`, xoá comment hướng dẫn (`<!-- ... -->`) sau khi điền.
-> - Không cần điền tay: nên chạy `/generate-architecture` để tự hút từ config/tài liệu/code + phỏng vấn, rồi con người verify.
->
-> PHÂN TẦNG (tier) — mỗi mục có marker `<!-- tier: core|conditional|ops -->`:
-> - **core** — luôn điền. Kiến trúc nền mà mọi feature cần.
-> - **conditional** — chỉ giữ nếu hệ thống thực sự có (multi-tenant, message bus, sharding…). Không dùng → để dạng STUB hoặc xoá hẳn.
-> - **ops** — vận hành, chỉ để người đọc. AI **KHÔNG** nạp khi sinh code/tech-design.
->
-> ĐIỀN DẦN: không phải điền hết một lần. Mục chưa làm để dạng STUB rồi lấp sau bằng `/generate-architecture --section=<slug>`:
-> ```
-> ## Multi-tenant  <!-- tier: conditional --> <!-- status: stub -->
-> > ⏳ Chưa tài liệu hoá. Chạy `/generate-architecture --section=multi-tenant` khi cần, hoặc điền tay.
-> ```
-
-<!-- ════════════════════ CORE (luôn điền) ════════════════════ -->
-
-## Công nghệ sử dụng (Tech Stack)  <!-- tier: core -->
-
-| Tầng | Công nghệ | Phiên bản / Ghi chú |
-|---|---|---|
-| Backend | {{BACKEND_TECH}} | {{VERSION}} |
-| Frontend | {{FRONTEND_TECH}} | {{VERSION}} |
-| ORM / Truy cập dữ liệu | {{ORM}} | {{VERSION}} |
-| Database | {{DATABASE}} | {{PRIMARY_STORE_NOTE}} |
-| Caching | {{CACHE}} | {{CACHE_NOTE}} |
-| Event Bus / Messaging | {{MESSAGING}} | {{MESSAGING_NOTE}} |
-| API Gateway | {{GATEWAY}} | {{GATEWAY_NOTE}} |
-| Kiểm thử | {{TEST_STACK}} | {{TEST_NOTE}} |
-<!-- Thêm/bớt dòng theo thực tế. Cột Ghi chú nên ghi ràng buộc cụ thể AI cần biết (vd: "dùng cho mọi màn hình list", "thư viện private wrapper"). -->
-
-## Các tầng kiến trúc (Architecture Layers)  <!-- tier: core -->
-
-Kiểu kiến trúc: `{{ARCH_STYLE}}`  <!-- vd: Layered / Clean / Hexagonal / Component-based -->
-
-```
-{{LAYER_DIAGRAM}}
-```
-<!-- Ví dụ Clean Architecture:
-┌──────────────────────────────────────┐
-│  Presentation   │  Controllers, Middleware
-├──────────────────────────────────────┤
-│  Application    │  Use Cases, DTOs, Interfaces
-├──────────────────────────────────────┤
-│  Domain         │  Entities, Value Objects, Events
-├──────────────────────────────────────┤
-│  Infrastructure │  ORM, Cache, Messaging
-└──────────────────────────────────────┘
--->
-
-### Chiều phụ thuộc
-- {{OUTER}} → {{MIDDLE}} → {{INNER}} ← {{INFRASTRUCTURE}}
-- {{INNER_LAYER}} có **zero** phụ thuộc ngoài.
-- Infrastructure hiện thực các interface do Application/Domain định nghĩa.
-- Tầng trong KHÔNG được phụ thuộc tầng ngoài.
-
-## Quy ước đặt tên  <!-- tier: core -->
-
-| Thành phần | Quy ước | Ví dụ |
-|---|---|---|
-| Entity | {{ENTITY_CONV}} | {{EXAMPLE}} |
-| Value Object | {{VO_CONV}} | {{EXAMPLE}} |
-| Interface | {{INTERFACE_CONV}} | {{EXAMPLE}} |
-| Use Case Command | {{COMMAND_CONV}} | {{EXAMPLE}} |
-| Use Case Query | {{QUERY_CONV}} | {{EXAMPLE}} |
-| Handler | {{HANDLER_CONV}} | {{EXAMPLE}} |
-| DTO | {{DTO_CONV}} | {{EXAMPLE}} |
-| Controller | {{CONTROLLER_CONV}} | {{EXAMPLE}} |
-| DI Extension | {{DI_EXT_CONV}} | {{EXAMPLE}} |
-| Class test | {{TEST_CLASS_CONV}} | {{EXAMPLE}} |
-| Method test | {{TEST_METHOD_CONV}} | {{EXAMPLE}} |
-
-> Quy ước đặt tên của frontend / từng repo → xem `.ai-project-guide.md` tương ứng.
-
-## Định dạng response API chuẩn  <!-- tier: core -->
-
-```{{LANG}}
-// Thành công
-{{SUCCESS_WRAPPER}}
-→ {{SUCCESS_JSON_SHAPE}}
-
-// Thất bại
-{{FAILURE_WRAPPER}}
-→ {{FAILURE_JSON_SHAPE}}
-```
-
-## Quy ước API  <!-- tier: core -->
-
-| Khía cạnh | Quy ước |
-|---|---|
-| Base URL | {{BASE_URL}} |
-| Versioning | {{VERSIONING}}  <!-- vd: URL path /v1/, theo header, query param --> |
-| Đặt tên URL | {{URL_NAMING}}  <!-- vd: kebab-case --> |
-| Phân trang | {{PAGINATION}}  <!-- vd: ?page=1&pageSize=20 → meta{...} --> |
-| Lọc | {{FILTERING}} |
-| Sắp xếp | {{SORTING}} |
-| Định dạng ngày | {{DATE_FORMAT}}  <!-- vd: ISO 8601 --> |
-| Ngừng hỗ trợ (Deprecation) | {{DEPRECATION_POLICY}} |
-
-### Các endpoint chính theo service  <!-- [TUỲ CHỌN] -->
-
-| Service | Endpoints |
-|---|---|
-| {{SERVICE}} | {{ENDPOINTS}} |
-
-> Tài liệu API đầy đủ: {{API_DOCS_LOCATION}}  <!-- vd: /swagger cho mỗi service -->
-
-## Quy ước Database  <!-- tier: core -->
-
-- **Migration**: {{MIGRATION_STRATEGY}}  <!-- vd: code-first mỗi service -->
-- **Đặt tên**: {{DB_NAMING}}  <!-- vd: PascalCase cho entity, snake_case cho cột -->
-- **Soft Delete**: {{SOFT_DELETE_RULE}}
-- **Cột audit**: {{AUDIT_COLUMNS}}  <!-- vd: CreatedAt NOT NULL, ModifiedAt nullable -->
-- **Xử lý đồng thời**: {{CONCURRENCY_MECHANISM}}  <!-- vd: ROWVERSION / optimistic lock -->
-- **Quy ước ID**: {{PK_TYPE}}  <!-- vd: bigint (không dùng Guid) -->
-
-### Quy ước Migration  <!-- [TUỲ CHỌN] khi dùng SQL migration thủ công -->
-- **Vị trí**: {{MIGRATION_LOCATION}}
-- **Đặt tên**: {{MIGRATION_NAMING}}  <!-- vd: V{YYYYMMDD}_{NN}_{description}.sql -->
-- **Tính idempotent**: {{IDEMPOTENCY_RULE}}  <!-- vd: dùng guard IF NOT EXISTS -->
-
-<!-- ════════════════════ CONDITIONAL (chỉ giữ nếu hệ thống có) ════════════════════ -->
-
-## Luồng dữ liệu tổng quan  <!-- tier: conditional -->
-
-<!-- Mô tả 1-2 câu bản chất luồng dữ liệu của hệ thống (vd: "hệ tổng hợp dữ liệu: master data ở hệ ngoài, config/transaction ở DB local, gộp tại runtime"). -->
-{{DATA_FLOW_SUMMARY}}
-
-```
-{{DATA_FLOW_DIAGRAM}}
-```
-<!-- Vẽ ASCII: Clients → Gateway → Services → điểm composition ở Application → Infrastructure (API ngoài / DB / cache / bus).
-     Ghi rõ phương thức auth của từng client và các điểm composition quan trọng. -->
-
-### Phân loại nguồn dữ liệu  <!-- [TUỲ CHỌN] khi dữ liệu đến từ nhiều nguồn (API ngoài + DB local) -->
-
-| Dữ liệu | Nguồn | Cách truy cập | Caching |
-|---|---|---|---|
-| {{DATA}} | {{SOURCE}} | {{PATH}} | {{TTL_OR_DASH}} |
-
-### Giao tiếp giữa các service  <!-- [TUỲ CHỌN] khi multi-service -->
-
-```
-{{SERVICE_A}}  ──{{PROTOCOL}}──▶ {{SERVICE_B}}   ({{VIA_CLIENT}})
-```
-
-> **Endpoint nội bộ** ({{INTERNAL_ROUTE_PREFIX}}): {{INTERNAL_AUTH_MECHANISM}} — vd: header shared-secret + IP whitelist. Xem §Luồng Xác thực.
-
-## Repositories & Hướng dẫn nền tảng  <!-- tier: conditional -->  <!-- chỉ giữ nếu là hệ multi-repo -->
-
-| Repository | Stack | Platform Guide |
-|---|---|---|
-| `{{repo-name}}/` | {{STACK_SUMMARY}} | `{{repo-name}}/.ai-project-guide.md` |
-
-> **Cấu trúc thư mục, scan path, quy ước namespace, code pattern** → xem `.ai-project-guide.md` của từng repo.
-> File này tập trung vào **kiến trúc cắt ngang** dùng chung cho mọi repo.
-
-## Phân loại Entity  <!-- tier: conditional -->  <!-- khi hệ thống tích hợp dữ liệu từ hệ ngoài -->
-
-Entity được chia thành các nhóm sau. Mọi code, tài liệu, và BDD spec PHẢI dùng các thuật ngữ này nhất quán.
-
-| Nhóm | Thuật ngữ | Lưu ở DB? | ORM quản lý? | Truy cập qua | Ví dụ |
-|---|---|---|---|---|---|
-| **DB Entity** | `[entity] entity` | CÓ | CÓ | {{DB_REPO_INTERFACE}} | {{EXAMPLES}} |
-| **Model nguồn-API** | `[entity] model` | KHÔNG | KHÔNG — POCO/DTO | {{API_SERVICE_INTERFACE}} | {{EXAMPLES}} |
-| **Projection Entity** | `[entity] projection` | CÓ | CÓ | {{PROJECTION_REPO}} | {{EXAMPLES}} |
-
-**Quy tắc:**
-- Model nguồn-API KHÔNG có bảng DB, KHÔNG migration — là POCO/DTO được populate từ API ngoài.
-- {{ID_RULE}}  <!-- vd: Model nguồn-API Id = external ID; DB entity Id = tự sinh -->
-- {{PROJECT_SPECIFIC_RULE}}
-
-## Phân loại truy cập dữ liệu — Ranh giới các tầng  <!-- tier: conditional -->  <!-- khi gộp dữ liệu nhiều nguồn (API ngoài + DB) -->
-
-Cách các tầng truy cập dữ liệu và ranh giới giữa chúng:
-
-```
-{{ACCESS_TREE}}
-```
-<!-- Ví dụ:
-Handler / Controller
-  ├── IProductCatalogService (Application — điểm gộp DUY NHẤT)
-  │     ├── IProductService (Infrastructure — API ngoài)
-  │     └── IDisplayConfigRepository (Infrastructure — DB)
-  └── IOrderRepository (Infrastructure — DB, inject trực tiếp)
--->
-
-| Tầng | Mục đích | Sở hữu | Ví dụ |
-|---|---|---|---|
-| **{{API_SERVICE_LAYER}}** (Infrastructure) | Gọi API ngoài; tự quản cache/retry/circuit-breaker/mapping | Model nguồn-API | {{EXAMPLES}} |
-| **{{DB_REPO_LAYER}}** (Infrastructure) | Thao tác DB local; repository pattern chuẩn | DB entity | {{EXAMPLES}} |
-| **{{APP_SERVICE_LAYER}}** (Application) | Gộp dữ liệu nhiều nguồn; điểm composition duy nhất | Domain object đã enrich | {{EXAMPLES}} |
-| **{{HANDLER_LAYER}}** (Presentation/Application) | Điều phối use-case; mapping request→response | — | {{EXAMPLES}} |
-
-**Quy tắc Injection (BẮT BUỘC tuân theo):**
-1. {{RULE_1}}  <!-- vd: Service gọi API ngoài chỉ inject vào Application Service, KHÔNG inject thẳng vào Handler -->
-2. {{RULE_2}}
-3. {{RULE_3}}
-
-## Trách nhiệm của từng service  <!-- tier: conditional -->  <!-- khi multi-service -->
-
-| Service | Domain | Trách nhiệm chính |
-|---|---|---|
-| {{SERVICE}} | {{DOMAIN}} | {{RESPONSIBILITIES}} |
-
-## Mô hình đăng ký DI  <!-- tier: conditional -->
-
-Mỗi feature đăng ký dependency qua extension method / module:
-```{{LANG}}
-{{DI_REGISTRATION_EXAMPLE}}
-```
-
-## Mô hình Multi-tenant  <!-- tier: conditional -->  <!-- khi một hệ thống phục vụ nhiều khách hàng/chi nhánh, dữ liệu tách riêng -->
-
-Mọi entity (trừ {{GLOBAL_ENTITIES}}) PHẢI có `{{TENANT_KEY}}`. {{ISOLATION_MECHANISM}} đảm bảo cách ly:
-```{{LANG}}
-{{QUERY_FILTER_EXAMPLE}}
-```
-
-Truy cập tenant context qua: `{{TENANT_CONTEXT_ACCESSOR}}`  <!-- các field: TenantId, AppId, UserId... -->
-
-## Phân giải định danh — External ID vs Internal ID  <!-- tier: conditional -->  <!-- khi tích hợp hệ ngoài có ID riêng -->
-
-Hệ thống tích hợp với {{EXTERNAL_SYSTEM}}. Mỗi entity ngoài có ID riêng, **KHÔNG trùng** với internal ID. Hai hệ ID này phải luôn được phân biệt rõ.
-
-| | DB Entity (local) | Model nguồn-API (ngoài) |
-|---|---|---|
-| **`Id`** | {{INTERNAL_ID_RULE}} (tự sinh) | Gán từ response hệ ngoài — KHÔNG tự sinh |
-| **`ExternalId`** | Lưu ID hệ ngoài để tham chiếu chéo | Không áp dụng — `Id` chính là external ID |
-
-### Quy tắc bắt buộc
-1. {{RULE_1}}  <!-- vd: DB Entity Id luôn tự sinh, TUYỆT ĐỐI KHÔNG gán external ID vào Id -->
-2. {{RULE_2}}
-3. {{RULE_3}}
-
-### Anti-pattern (CẤM)
-```{{LANG}}
-// ❌ SAI — {{ANTIPATTERN_DESC}}
-{{BAD_EXAMPLE}}
-
-// ✅ ĐÚNG
-{{GOOD_EXAMPLE}}
-```
-
-## API Gateway  <!-- tier: conditional -->
-
-| Trách nhiệm | Chi tiết |
-|---|---|
-| Xác minh chữ ký / auth | {{DETAIL}} |
-| Rate limiting | {{DETAIL}} |
-| Xử lý CORS | {{DETAIL}} |
-| Định tuyến request | {{DETAIL}} |
-| Cân bằng tải | {{DETAIL}} |
-| IP whitelist | {{DETAIL}} |
-
-**Nguyên tắc thiết kế:** Stateless, không chứa business logic, scale ngang được.
-
-## Chiến lược Caching  <!-- tier: conditional -->
-
-**Mô hình**: {{CACHE_PATTERN}}  <!-- vd: Cache-Aside (read-through) -->
-**Định dạng key**: {{KEY_FORMAT}}  <!-- vd: {entity}:{tenantId}:{id} -->
-
-| Loại dữ liệu | TTL | Cách invalidate |
-|---|---|---|
-| {{DATA}} | {{TTL}} | {{INVALIDATION}} |
-
-## Event Bus  <!-- tier: conditional -->
-
-> **Trạng thái:** {{STATUS}}  <!-- vd: đã cấp hạ tầng nhưng chưa implement / đã chạy production -->
-
-**Nguyên tắc thiết kế:**
-- {{PARTITIONING}}  <!-- vd: partition theo TenantId để đảm bảo thứ tự trong mỗi tenant -->
-- {{DELIVERY_GUARANTEE}}  <!-- vd: at-least-once + theo dõi idempotency -->
-- {{DLQ_RETRY}}  <!-- vd: DLQ {topic}.dlq, retry 3 lần với exponential backoff -->
-
-## Sharding  <!-- tier: conditional -->
-
-- {{SHARD_STRATEGY}}  <!-- vd: mô hình Shard Registry + cache -->
-- {{SHARD_RESOLVER}}  <!-- vd: IShardResolver: cache → Registry DB → tự gán -->
-
-## Feature Toggle  <!-- tier: conditional -->
-
-Hệ thống dùng {{FEATURE_TOGGLE_TOOL}} cho feature flag lúc runtime.
-
-| Điều kiện | Hành vi |
-|---|---|
-| Toggle bị tắt | {{BEHAVIOR}}  <!-- thường: fail-open / cho phép -->|
-| Lỗi khi đánh giá | {{BEHAVIOR}}  <!-- thường: fail-open để sự cố không khoá user -->|
-| Flag trả về false | {{BEHAVIOR}} |
-
-## Luồng Xác thực  <!-- tier: conditional -->
-
-### {{AUTH_METHOD}}  <!-- vd: JWT Bearer / API Key (HMAC) / OAuth2 / Token Exchange -->
-
-```
-{{AUTH_FLOW_STEPS}}
-```
-<!-- Liệt kê tuần tự các bước middleware xử lý: extract → verify → resolve → build context.
-     Nếu có nhiều luồng auth (S2S, browser, internal), mô tả từng luồng. -->
-
-**Quy tắc chính:**
-- {{AUTH_RULE_1}}
-- {{AUTH_RULE_2}}
-
-**Middleware pipeline:**
-```
-{{ROUTE_PATTERN}}  → {{MIDDLEWARE_OR_BYPASS}}
-{{HEALTH_ROUTE}}   → bypass (health probe)
-```
-
-<!-- ════════════════════ OPS (chỉ người đọc — AI không nạp khi sinh code) ════════════════════ -->
-
-## Observability (Khả năng quan sát)  <!-- tier: ops -->
-
-### Ghi log (Logging)
-- Thư viện: {{LOGGING_LIB}}
-- Định dạng: {{LOG_FORMAT}}  <!-- vd: Compact JSON -->
-- Sink: {{LOG_SINKS}}  <!-- vd: file xoay vòng theo ngày, giữ 30 ngày; console chỉ khi dev -->
-- **Correlation ID**: {{CORRELATION_MECHANISM}}  <!-- vd: X-Correlation-Id đẩy vào log context -->
-- Mức log: {{LOG_LEVELS}}
-
-### Metrics  <!-- [TUỲ CHỌN] -->
-
-| Metric | Loại | Mô tả |
-|---|---|---|
-| {{METRIC}} | {{TYPE}} | {{DESC}} |
-
-### Distributed Tracing  <!-- [TUỲ CHỌN] -->
-- {{TRACING_TOOL}} — {{PROPAGATION_SCOPE}}  <!-- vd: OpenTelemetry, propagate qua HTTP + messaging -->
-
-### Health Check
-```{{LANG}}
-{{HEALTH_CHECK_REGISTRATION}}
-```
-- `{{LIVENESS_ROUTE}}` — liveness (chỉ tự kiểm tra)
-- `{{READINESS_ROUTE}}` — readiness (phụ thuộc: DB + cache + bus)
-
-## Triển khai & DevOps  <!-- tier: ops -->
-
-### Chiến lược môi trường
-
-| Môi trường | Mục đích | Hạ tầng |
-|---|---|---|
-| Development | {{PURPOSE}} | {{INFRA}} |
-| Staging | {{PURPOSE}} | {{INFRA}} |
-| Production | {{PURPOSE}} | {{INFRA}} |
-
-### CI/CD Pipeline
-```
-{{PIPELINE_STAGES}}
-```
-<!-- vd: Code Push → Build → Unit Test → Integration Test → Docker Build → Push Registry → Deploy Staging → Smoke → Duyệt tay → Production -->
-
-### Quản lý cấu hình
-
-| Loại cấu hình | Lưu ở | Ví dụ |
-|---|---|---|
-| App Settings | {{STORAGE}} | {{EXAMPLE}} |
-| Secrets | {{SECRET_STORE}} | {{EXAMPLE}}  <!-- secret production TUYỆT ĐỐI KHÔNG commit vào repo -->|
-| Biến môi trường | {{ENV_STORE}} | {{EXAMPLE}} |
-
-## Chiến lược kiểm thử  <!-- tier: ops -->
-
-| Cấp độ | Phạm vi | Công cụ |
-|---|---|---|
-| Unit Test | {{SCOPE}} | {{TOOLS}} |
-| Integration Test | {{SCOPE}} | {{TOOLS}} |
-| Functional Test | {{SCOPE}} | {{TOOLS}} |
-| Load Test | {{SCOPE}} | {{TOOLS}} |
-
-- Đặt tên: {{TEST_NAMING}}  <!-- vd: MethodName_Scenario_ExpectedResult -->
-- {{CI_TEST_RULE}}  <!-- vd: CI chạy unit + integration mỗi PR -->
-
-## Yêu cầu phi chức năng (NFR)  <!-- tier: ops -->
-
-| Yêu cầu | Mục tiêu |
-|---|---|
-| Khả năng mở rộng | {{TARGET}} |
-| Tính sẵn sàng | {{TARGET}}  <!-- vd: SLA uptime 99.9% -->|
-| Triển khai | {{TARGET}}  <!-- vd: zero-downtime, rolling update -->|
-| Tính nhất quán | {{TARGET}} |
-| Độ trễ | {{TARGET}}  <!-- vd: API p95 < 200ms -->|
-| Thông lượng | {{TARGET}} |
-| Lưu trữ dữ liệu | {{TARGET}} |
-| Sao lưu | {{TARGET}} |

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 |