@educa-corp/sdd-framework 0.2.3 → 0.2.5

package/core/commands/generate-code.md

@@ -443,6 +443,8 @@ Lệnh này giới hạn nghiêm ngặt trong **một file feature** được tr
 3. CLAUDE.md §architecture + §coding_standards
 4. **(chỉ FE/App)** Design Spec — nạp qua **Guard** bên dưới (gate approved/độ-tươi + sanity), là nguồn của màn hình, component inventory, và link Figma frame từng-màn.
 
+> **Phạm vi vét nguồn (SRC-CHAIN):** khi một giá trị còn thiếu ở nguồn chính, được phép đọc thêm các artifact **cùng feature-package** `{paths.specs_dir}/{domain}/{prd-slug}/` — PRD `{TICKET-ID}-{prd-slug}.md`, các `.feature` khác (system/web/app), design-spec, tech-doc anh em — cùng `core-entities.md`/`business-dictionary.md`. Đọc **theo nhu cầu** để phân giải giá trị trước khi hỏi người (xem §Quy tắc nguồn giá trị).
+
 ---
 
 ## Guard — BDD & Design Spec đã sẵn sàng chưa *(cảnh báo MỀM — đồng bộ generate-bdd)*
@@ -775,7 +777,18 @@ DTOs → Entity/Model → Repository → Service interface → Service impl →
 
 > **Quy tắc entry-point:** `@trace.implements` phải xuất hiện ở **layer entry-point** như định nghĩa trong `CLAUDE.md §2`. Với REST API → Controller. Với module event-driven → event handler / consumer class. Với context-engineering → hàm orchestration prompt. Không bao giờ chỉ đặt ở layer trong.
 
-> **Quy tắc nguồn giá trị (chống hard-code):** MỌI giá trị cụ thể (endpoint path, error code, tên field/DTO, enum, limit/timeout, header) phải lấy từ **nguồn đã chốt** — tech-doc §4 (contract) · `core-entities.md` (enum/field) · config/env — **KHÔNG bịa inline**. Nếu một hằng số nghiệp vụ lặp lại hoặc mang ý nghĩa (retry count, ngưỡng, key) → **đặt tên hằng số** (constant/config), không rải magic number/string trong code. Không có nguồn cho một giá trị → đây là GAP: dừng và hỏi, đừng chế bừa (đồng bộ Cổng 2 của generate-tech-docs). *(DS3 đã đảm bảo có §4 contract trước khi tới đây với BE.)*
+> **Quy tắc nguồn giá trị (chống hard-code):** MỌI giá trị cụ thể (endpoint path, error code, tên field/DTO, enum, limit/timeout, header) phải lấy từ **nguồn đã chốt** — **KHÔNG bịa inline**. Nếu một hằng số nghiệp vụ lặp lại hoặc mang ý nghĩa (retry count, ngưỡng, key) → **đặt tên hằng số** (constant/config), không rải magic number/string trong code.
+>
+> **VÉT CẠN NGUỒN TRƯỚC KHI HỎI (SRC-CHAIN) — bắt buộc.** Khi một giá trị chưa thấy ở nguồn chính, PHẢI quét lần lượt các nguồn đã có trong context/spec-package theo thứ tự sau, **dừng ngay khi tìm thấy** (skip-if-answered), KHÔNG hỏi người ngay:
+> 1. Tech-doc gộp §4 (contract: §4.1 endpoint · §4.2 request/response · §4.3 error · §4.5.4 client integration)
+> 2. `core-entities.md` (tên field / type / enum) · `business-dictionary.md` (thuật ngữ chuẩn)
+> 3. PRD của UC (nhất là Appendix "Existing API Contract" khi `API Source: existing`, và metadata)
+> 4. Design-spec (FE/App: field/label/state màn hình)
+> 5. System/platform BDD — mệnh đề `Then` (behavior + giá trị fixture)
+> 6. Code/adapter đã sinh ở lần chạy trước (vd mock adapter `--phase=ui` đã chốt shape port/DTO) · config/env
+> 7. Tech-doc anh em cùng domain
+>
+> Chỉ giá trị **thật sự không nguồn nào có** mới là GAP. **Gom TẤT CẢ GAP còn lại vào MỘT checkpoint** (mỗi GAP ghi rõ "đã tìm ở: {các nguồn}"), hỏi một lượt — KHÔNG hỏi lắt nhắt từng câu, KHÔNG chế bừa (đồng bộ Cổng 2 của generate-tech-docs). *(DS3 đã đảm bảo có §4 contract trước khi tới đây với BE.)*
 
 ### Test Selectors — emit element ID ổn định *(chỉ UI FE/App)*
 
@@ -829,7 +842,8 @@ Dựng mock từ `mock_source` đã phân giải ở Phase Detection — **shape
 *Bỏ qua hoàn toàn section này nếu `--phase` không phải `integration`.*
 
 1. **Đọc integration design.** Trong tech-doc gộp `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md`: ưu tiên §4.5.4 (mapping port→endpoint→DTO→error của platform), dùng §4.1/§4.2/§4.3 làm nguồn endpoint / request-response / error-code. Nếu doc chưa có §4.5.4 cho platform này, trích endpoint + shape + error code trực tiếp từ §4.1–§4.3.
-2. **Đọc mock adapter có sẵn** interface (`{UC-ID}ApiPort`) từ output `--phase=ui`.
+   - **Nếu §4/§4.5.4 thiếu bất kỳ chi tiết integration nào (endpoint, field/DTO, error-code, mapping):** ÁP DỤNG **SRC-CHAIN** (xem §Quy tắc nguồn giá trị) — vét cạn PRD (Appendix Existing API Contract), design-spec, mệnh đề `Then` của System/platform BDD, `core-entities.md`, **mock adapter đã sinh ở `--phase=ui`** (shape port/DTO đã chốt — nguồn shape mạnh nhất, đừng bỏ quên), tech-doc anh em cùng domain — TRƯỚC khi coi là GAP. Skip-if-answered. Chỉ hỏi cái không nguồn nào có, và **gộp mọi GAP còn lại vào MỘT checkpoint** (ghi rõ đã tìm ở đâu). *(Đây là fix cho tình trạng phase=integration hỏi nhiều dù đáp án đã nằm trong tài liệu khác.)*
+2. **Đọc mock adapter có sẵn** interface (`{UC-ID}ApiPort`) từ output `--phase=ui`. Real adapter implements **cùng** interface này → shape port/DTO đã cố định từ mock; **không hỏi lại shape** đã có ở đây.
 3. **Sinh real API adapter** tại `{paths.src_dir}/{domain}/{UC-ID}ApiAdapter.{ext}`:
    - Implements cùng interface `{UC-ID}ApiPort` như mock adapter
    - Gọi HTTP thật tới endpoint từ contract tech-doc

package/core/commands/generate-tech-docs.md

@@ -463,6 +463,25 @@ Lưu `input_features`, `platforms_present`, danh sách scenario theo từng UC,
 
 ---
 
+## Bước 0.5 — [ARCH] Nạp Architecture Context (nếu có)
+
+Tech-design chắt lọc kiến trúc hệ thống thành API contract + client design, nên đây là **nơi duy nhất** trong pipeline nạp `architecture.md` (SSOT cross-cutting sinh bởi `/generate-architecture`). Không nạp toàn cục ở context-loader — chỉ lệnh này cần nó ở mức sâu.
+
+1. **Phân giải path:** `{paths.specs_dir}/architecture.md` (mặc định `specs/architecture.md`). Chế độ umbrella: context-loader đã trỏ `specs_dir`/`service_root` về service đang active → dùng `architecture.md` của chính service đó (kiến trúc là code-level, per-service).
+2. **Nếu file KHÔNG tồn tại** → bỏ qua âm thầm, đặt `arch = none`. Vẫn dựa vào CLAUDE.md §2 (layers/rules) + core-entities như trước. (Gợi ý mềm một lần trong report cuối: "Chưa có architecture.md — cân nhắc chạy `/generate-architecture` để tech-design bám kiến trúc hệ thống.")
+3. **Nếu tồn tại** → đọc **có chọn lọc theo tier** (mỗi mục có marker `<!-- tier: core|conditional|ops -->`):
+   - **Nạp** thân các mục **`core` + `conditional`** — đây là phần ảnh hưởng code/API/data: layer boundaries + dependency direction, phân loại/nguồn dữ liệu, injection rules, luồng xác thực, response API chuẩn, caching/sharding/messaging, multi-tenant/identity-resolution.
+   - **BỎ QUA** các mục **`ops`** (Observability, Triển khai & DevOps, Chiến lược kiểm thử, NFR) — không đổi thiết kế API/data-model, chỉ làm nhiễu context.
+   - Các section §2–§4 (data model, API contract, integration) PHẢI nhất quán với phần đã nạp — KHÔNG tự suy khác.
+4. **Mục đang STUB (`<!-- status: stub -->`):** nếu một UC trong batch **chạm** tới một concern mà mục tương ứng còn stub (vd UC có tenant scoping nhưng §Multi-tenant là stub) → **cảnh báo mềm** trong report: *"§{Mục} chưa tài liệu hoá trong architecture.md — chạy `/generate-architecture --section={slug}` để tech-design chính xác hơn."* Vẫn tiếp tục dựa vào CLAUDE.md.
+5. **Trust-gate — đọc frontmatter `verified_by`:**
+   - `verified_by: AI-draft` (hoặc trống) → nội dung do AI dựng từ config/tài liệu/code, CHƯA ai verify. Vẫn dùng làm tham chiếu nhưng **cảnh báo** trong report: *"⚠️ architecture.md còn là AI-draft chưa verify — tech-design có thể kế thừa giả định sai. Nên để Tech Lead verify (đổi `verified_by`) trước khi chốt."* Khi mâu thuẫn với CLAUDE.md/BDD thì ưu tiên CLAUDE.md/BDD.
+   - `verified_by: {người thật}` → coi là ràng buộc kiến trúc chính thức.
+
+Lưu `arch` (`none` | `ai-draft` | `verified`) để dùng ở các bước sinh section và report.
+
+---
+
 ## Bước 1 — Chế độ Fresh vs Append
 
 Kiểm tra `output_path` đã tồn tại chưa.

package/core/skills/setup-ai-first/SKILL.md

@@ -1,11 +1,19 @@
 ---
-description: Cài đặt framework Spec-Driven Development trong bất kỳ backend project nào từ đầu. Trigger when: "/setup-ai-first", "setup spec-driven workflow", "initialize ai-first framework", "cài đặt framework", "khởi tạo spec-driven", "set up this workflow", "how do I start using this framework".
+description: Cài đặt framework Spec-Driven Development, và sinh/làm mới tài liệu kiến trúc (architecture.md SSOT). Trigger when: "/setup-ai-first", "/generate-architecture", "setup spec-driven workflow", "initialize ai-first framework", "cài đặt framework", "khởi tạo spec-driven", "set up this workflow", "how do I start using this framework", "sinh architecture", "tạo tài liệu kiến trúc", "generate architecture doc", "refresh architecture", "scan codebase architecture".
 ---
 
-# /setup-ai-first — Initialize SDD Framework in a Project
+# /setup-ai-first · /generate-architecture — Foundation Skills (SA / Tech Lead)
 
-Skill này xử lý `/setup-ai-first`. Để **không lệch** (umbrella/services routing, cấu trúc), skill KHÔNG nhân bản — thực thi **y hệt** command.
+Skill này xử lý `/setup-ai-first` và `/generate-architecture`. Để **không lệch** (umbrella/services routing, cấu trúc, trust-gate), skill KHÔNG nhân bản — mỗi lệnh thực thi **y hệt** command tương ứng.
+
+## /setup-ai-first — Initialize SDD Framework in a Project
 
 → **Đọc và tuân theo `commands/setup-ai-first.md`** với cùng `$ARGUMENTS`.
 
-Command lo: tạo cấu trúc thư mục + feature-package on demand · CLAUDE.md + `.agent/project-context.yaml` (gồm umbrella `services` routing) · nhắc PO đặt row `Domain` (bảng Metadata) khớp services config · verify môi trường.
+Command lo: tạo cấu trúc thư mục + feature-package on demand · CLAUDE.md + `.agent/project-context.yaml` (gồm umbrella `services` routing) · seed `architecture.md` (Step 3.5) · nhắc PO đặt row `Domain` (bảng Metadata) khớp services config · verify môi trường.
+
+## /generate-architecture — Sinh / làm mới Architecture Context (SSOT)
+
+→ **Đọc và tuân theo `commands/generate-architecture.md`** với cùng `$ARGUMENTS`.
+
+Command lo: phân giải target (single-service / per-service umbrella) · phát hiện greenfield vs brownfield · **scan codebase** (build-file/DI/middleware/config/CI) → draft từng section kèm bằng chứng · xoá section [OPTIONAL] không dùng · **trust-gate** `verified_by: AI-draft` · refresh có kiểm soát (không đè bản người đã verify) · bàn giao cho người verify.

package/core/templates/architecture.template.md

@@ -1,113 +1,394 @@
-# §1. Project Overview
+---
+last_verified: {{YYYY-MM-DD}}
+verified_by: {{AUTHOR}}
+---
 
-Project    : {{PROJECT_NAME}}
-Language   : {{LANGUAGE}}          # vd: Java 17 / TypeScript / C# / Go
-Framework  : {{FRAMEWORK}}         # vd: Spring Boot 3.2 / Angular 17 / .NET 8
-Build      : {{BUILD_COMMAND}}     # vd: mvn clean install -DskipTests / dotnet build / ng build
-Test       : {{TEST_COMMAND}}      # vd: mvn test / dotnet test / ng test
-Domains    : {{COMMA_SEPARATED_DOMAINS}}
-
-# §2. Architecture
+# {{SYSTEM_NAME}} — Bối cảnh Kiến trúc (Architecture Context)
 
-style: "{{ARCH_STYLE}}"  # vd: Layered / Clean / Hexagonal / Component-based
-
-layers: "{{LAYER_STACK}}"
-# Ví dụ:
-#   Java/Spring:  Controller → Facade → Service → Repository
-#   .NET Clean:   Presentation → Application → Domain → Infrastructure
-#   Angular:      Component → Service → HTTP Client → Backend API
-#   Go:           Handler → UseCase → Repository → Domain
-
-rules:
-  - "{{ARCH_RULE_1}}"  # vd: Controller không được chứa business logic
-  - "{{ARCH_RULE_2}}"  # vd: Service sở hữu ranh giới transaction
-  - "{{ARCH_RULE_3}}"  # vd: Repository không được gọi service
-
-# Chiều phụ thuộc giữa các layer (layer trong không được phụ thuộc layer ngoài):
-# {{OUTER_LAYER}} → {{MIDDLE_LAYER}} → {{INNER_LAYER}}
-
-# §3. Coding Standards
-
-naming:
-  classes: "{{CLASS_NAMING}}"        # vd: PascalCase / PascalCase+Suffix
-  methods: "{{METHOD_NAMING}}"       # vd: camelCase / PascalCase
-  packages: "{{PACKAGE_NAMING}}"     # vd: lowercase / lowercase.snake_case
-  files: "{{FILE_NAMING}}"           # vd: PascalCase.java / kebab-case.ts
-
-patterns:
-  response_wrapper: "{{RESPONSE_WRAPPER}}"  # vd: ApiResponse<T> / Result<T> / IActionResult
-  mapping: "{{MAPPING_LIBRARY}}"            # vd: MapStruct / AutoMapper / manual
-  exception_base: "{{BASE_EXCEPTION}}"      # vd: ResourceNotFoundException / DomainException
-
-forbidden:
-  - "Magic number — dùng hằng số có tên"
-  - "Lệnh debug print trong code production"
-  - "{{PROJECT_SPECIFIC_FORBIDDEN_PATTERN}}"
-
-# §4. API Conventions
-
-versioning: "{{API_VERSIONING}}"     # vd: tiền tố /v1/ / theo header / query param
-auth: "{{AUTH_MECHANISM}}"           # vd: JWT Bearer / OAuth2 / API Key
-
-http_status:
-  get_list:    200   # danh sách phân trang hoặc đầy đủ
-  get_single:  200
-  create:      201
-  update:      200
-  delete:      204
-  bad_request: 400
-  unauthorized: 401
-  forbidden:   403
-  not_found:   404
-  server_error: 500
-
-error_response_format: |
-  {
-    "code": "ERROR_CODE",
-    "message": "Human readable message",
-    "details": {}   // optional field-level errors
-  }
-
-# §5. Error Handling
-
-not_found_exception: "{{NOT_FOUND_EXCEPTION_CLASS}}"  # vd: ResourceNotFoundException
-validation_exception: "{{VALIDATION_EXCEPTION_CLASS}}" # vd: ValidationException
-domain_exception: "{{DOMAIN_EXCEPTION_CLASS}}"         # vd: DomainException / BusinessRuleViolationException
-
-global_handler: "{{GLOBAL_EXCEPTION_HANDLER}}"  # vd: @ControllerAdvice / ExceptionHandlerMiddleware
-
-rules:
-  - "Không bao giờ nuốt exception âm thầm"
-  - "Log ở mức error kèm full stack trace cho lỗi 5xx"
-  - "{{PROJECT_SPECIFIC_ERROR_RULE}}"
-
-# §6. Testing Standards
-
-unit_test_framework: "{{UNIT_TEST_FW}}"        # vd: JUnit 5 + Mockito / xUnit + Moq / Jest
-integration_test_framework: "{{IT_TEST_FW}}"   # vd: Spring Boot Test / WebApplicationFactory
-
-coverage_targets:
-  unit: "{{UNIT_COVERAGE_PCT}}%"          # vd: 80%
-  integration: "{{IT_COVERAGE_PCT}}%"     # vd: phủ các flow chính
-
-naming_pattern: "{{TEST_METHOD_NAMING}}"  # vd: methodName_whenCondition_shouldExpectation
-
-rules:
-  - "Unit test chỉ mock các dependency trực tiếp"
-  - "Integration test phủ happy path + các luồng lỗi chính"
-  - "Mọi scenario trong .feature phải có test tương ứng"
-
-# §7. Git Conventions
-
-branch_feature: "feature/{{TICKET_PREFIX}}-{N}-{slug}"
-branch_fix:     "fix/{{TICKET_PREFIX}}-{N}-{slug}"
-branch_chore:   "chore/{slug}"
-
-commit_feature: "feat({{TICKET_PREFIX}}-{N}): {description}"
-commit_fix:     "fix({{TICKET_PREFIX}}-{N}): {description}"
-commit_chore:   "chore: {description}"
-commit_docs:    "docs: {description}"
-
-pr_title: "{{TICKET_PREFIX}}-{N}: {feature name}"
-pr_requires_review: true
-pr_branch_protection: "{{BASE_BRANCH}}"  # vd: main / develop
+> 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}} |