@educa-corp/sdd-framework 0.6.0 → 0.7.0

package/commands/generate-architecture.tmpl

@@ -1,197 +0,0 @@
-# /generate-architecture — Sinh / làm mới Architecture Context (SSOT)
-
-> **Mô hình phạm vi:** MỘT `architecture.md` cho mỗi codebase — nguồn chân lý (SSOT)
-> cross-cutting cho kiến trúc, dùng cho cả AI code-gen lẫn ops. Lệnh **thu thập từ mọi
-> nguồn sẵn có (config + tài liệu + code) → phỏng vấn lấp chỗ trống → draft → bàn giao
-> cho người verify**. Tách khỏi `/setup-ai-first` để SA chạy lại nhiều lần (refresh /
-> điền dần). Nó KHÔNG tự ký duyệt — con người là trust-gate.
->
-> **Triết lý điền:** ưu tiên **hút cái đã biết**, chỉ **hỏi cái chưa biết**. SA không phải
-> điền tay 140 ô — chỉ trả lời vài câu dễ hiểu về phần chưa nguồn nào trả lời được.
->
-> **Khác `/generate-tech-docs`:** tech-docs là thiết kế **per-PRD/feature**; lệnh này mô tả
-> **kiến trúc toàn hệ thống dùng chung**. Chi tiết per-repo (thư mục, namespace) vẫn ở
-> `.ai-project-guide.md` / CLAUDE.md của từng repo — lệnh này chỉ lo phần cross-cutting.
-
-## Gate
-
-*Checkpoint: **chặn CỨNG** — ghi đè architecture.md đã verified_by một người thật. `--yes` KHÔNG bỏ qua được (gate Bước 3a).*
-
-{{include:steps/gate.md}}
-
-*Với lệnh này — **bỏ qua Gate Bước 1** (không có input feature-file). `$ARGUMENTS` là **tuỳ chọn**, có thể gồm:
-- **service path** (chế độ umbrella, vd `user-service`) → target là `architecture.md` của service đó, scan giới hạn trong `{service}/`.
-- `--from=<path/glob,...>` → danh sách **tài liệu có sẵn** để hút nội dung (README, wiki, ADR, doc thiết kế cũ). Vd `--from=docs/**/*.md,README.md`.
-- `--section=<slug>` → chỉ lấp/refresh **đúng một mục** (điền dần). Danh sách slug ở Bước 5.
-- `--interview` → ép chạy phỏng vấn kể cả brownfield.
-Vẫn chạy Bước 0-B (model check) và Context Loader.*
-
-## Context
-{{include:steps/context-loader.md}}
-
----
-
-## Bước 1 — Phân giải target, chế độ & tham số
-
-1. **Target file:**
-   - Mặc định → `{paths.specs_dir}/architecture.md` (thường `specs/architecture.md`). Umbrella: context-loader đã trỏ `specs_dir`/`service_root` về service active → target nằm cạnh code service.
-   - `$ARGUMENTS` có **service path** → `target = {service}/specs/architecture.md`, scan giới hạn trong `{service}/`.
-   - **Umbrella mà không truyền service path** → DỪNG, hỏi: *"Umbrella không có một stack đơn. Chạy `/generate-architecture {service-path}` cho từng service."*
-
-2. **Parse cờ:** `--from` (danh sách nguồn tài liệu), `--section=<slug>` (chế độ 1-mục → nhảy Bước 5), `--interview` (ép phỏng vấn).
-
-3. **Chế độ code:** brownfield (có build/manifest: `pom.xml`/`*.csproj`/`package.json`/`go.mod`/`pubspec.yaml`/`build.gradle`/`Cargo.toml`) vs greenfield (không có code để scan).
-
-4. **File đã tồn tại?**
-   - Chưa → tạo mới.
-   - `verified_by: AI-draft` (hoặc trống) → được regenerate (xác nhận: *"architecture.md đang là AI-draft chưa verify — regenerate đè lên? (Y/N)"*).
-   - `verified_by: {người thật}` → **KHÔNG đè** → nhảy **Bước 6** (refresh có kiểm soát).
-
----
-
-## Bước 2 — Thu thập từ mọi nguồn (điền cái đã biết)
-
-Gom dữ kiện cho từng section/field theo **thứ tự ưu tiên**. Với mỗi giá trị điền được, ghi lại **nguồn** + **độ chắc chắn** (chắc / cần xác nhận). KHÔNG bịa ngoài bằng chứng.
-
-**Thứ tự nguồn:**
-
-1. **Config dự án** (luôn có) — đọc `project-context.yaml` + `CLAUDE.md`:
-   | Field template | Nguồn |
-   |---|---|
-   | Tech Stack (language/framework/db/build/test) | `project-context.yaml → tech_stack`, `conventions` |
-   | Các tầng + rules kiến trúc | `CLAUDE.md §2` |
-   | Quy ước đặt tên, response wrapper, error handling | `CLAUDE.md §3, §5` |
-   | Quy ước Git/DB nếu có | `CLAUDE.md §6, §7` |
-
-2. **Tài liệu có sẵn** (nếu có `--from`, hoặc hỏi 1 lần: *"Có tài liệu kiến trúc/thiết kế sẵn không? Trỏ path — README, wiki, ADR, doc cũ. Enter để bỏ qua."*) — đọc từng tài liệu, rút fact và **map vào section/field** tương ứng của template. Ghi chú nguồn theo dạng `<!-- nguồn: {đường-dẫn} -->` ở section được điền.
-
-3. **Scan code** (chỉ brownfield) — quét có mục tiêu:
-   | Nguồn quét | Section suy ra |
-   |---|---|
-   | build/manifest (dependencies) | **Tech Stack** |
-   | cây thư mục + tên project/layer (`*.Domain`/`*.Application`… hoặc `controller/service/repository`) | **Các tầng** + chiều phụ thuộc |
-   | DI registration (`Program.cs`/`Startup`/`*ServiceExtensions`) | **Đăng ký DI**, danh mục service/repo, **Ranh giới truy cập dữ liệu** |
-   | middleware / filter / interceptor | **Luồng Xác thực**, correlation-id, gateway |
-   | `appsettings*`/`application.yml`/`.env.example` | **Caching** (TTL), **Event Bus/Sharding**, **Feature Toggle** (chỉ ghi *tên* cấu hình, KHÔNG copy secret) |
-   | response wrapper / base controller / global exception handler | **Response API chuẩn** |
-   | entity/model (DbSet/@Entity) vs POCO/DTO từ API client | **Phân loại Entity**, **Identity Resolution** (nếu có external-id) |
-   | CI (`.github/workflows`, `Jenkinsfile`…), Dockerfile, k8s | **Triển khai & DevOps** |
-
-**Xử lý xung đột:** nếu ≥2 nguồn nói khác nhau (vd doc cũ "Redis TTL 10m" nhưng config "5m") → **KHÔNG tự chọn**. Đưa vào danh sách cần hỏi (Bước 3) hoặc gắn ⚠️ vào draft. Quy tắc chung: fact máy móc (tech stack, TTL, DI) ưu tiên **code/config**; phần ý đồ/narrative (data flow, rules, NFR) ưu tiên **tài liệu**.
-
-**Sản phẩm Bước 2:** với mỗi section — trạng thái `đã-điền` (kèm nguồn) / `còn-trống` / `xung-đột`. Đây là đầu vào cho phỏng vấn (chỉ hỏi phần còn-trống/xung-đột).
-
----
-
-## Bước 3 — Phỏng vấn thích ứng (chỉ hỏi cái chưa biết)
-
-### 3.0 — Báo cáo coverage trước khi hỏi
-
-```
-Đã điền từ config/tài liệu/code : {X}/{tổng} mục
-Còn cần hỏi                     : §{A}, §{B}, §{C}
-Xung đột cần xác nhận           : §{D} (nguồn 1 nói …, nguồn 2 nói …)
-```
-
-### 3.1 — Cách đặt câu hỏi (BẮT BUỘC: dễ hiểu, không thuật ngữ trần)
-
-Mỗi câu là một **thẻ giải thích**: tên mục + 1–2 câu nghĩa + ví dụ cụ thể + Có/Không nghĩa là gì. Ví dụ mẫu:
-```
-【 Hệ thống có Multi-tenant không? 】
-Một hệ thống phục vụ NHIỀU khách hàng/chi nhánh, dữ liệu mỗi bên tách riêng,
-không bên nào thấy của bên kia (vd: app SaaS bán hàng — mỗi shop chỉ thấy đơn của mình).
-  • CÓ    → phục vụ nhiều bên, cần cách ly dữ liệu
-  • KHÔNG → chỉ phục vụ một tổ chức duy nhất
-```
-Áp dụng phong cách này cho MỌI câu. Tuyệt đối không hỏi kiểu "Multi-tenant? [Y/N]" trơ trọi.
-
-### 3.2 — Pha 1: Sàng lọc (quyết mục conditional nào bật)
-
-Hỏi các thẻ dưới đây, **BỎ câu nào đã có đáp án** từ Bước 2 (config/tài liệu/code). Mỗi thẻ quyết định (các) section:
-
-| Thẻ hỏi (diễn đạt dễ hiểu như 3.1) | Bật section |
-|---|---|
-| Kiểu kiến trúc? (Layered/Clean/Hexagonal/Component-based) | §Các tầng (chọn sơ đồ mẫu) |
-| Backend có expose REST API cho client gọi? | §Response API + §Quy ước API |
-| Multi-tenant (nhiều khách hàng, dữ liệu tách riêng)? | §Multi-tenant |
-| Có tích hợp hệ ngoài có ID riêng (partner/hệ cũ)? | §Phân loại Entity + §Identity Resolution + §Nguồn dữ liệu + §Ranh giới truy cập dữ liệu |
-| Có xử lý bất đồng bộ qua message bus (Kafka/RabbitMQ…)? | §Event Bus |
-| Dữ liệu chia nhiều DB / sharding? | §Sharding |
-| Có bật/tắt tính năng bằng feature flag lúc chạy? | §Feature Toggle |
-| Có API Gateway đứng trước các service? | §API Gateway |
-| Có cache riêng (Redis…) để tăng tốc? | §Caching |
-| Nhiều repo / nhiều service? | §Repos + §Trách nhiệm service + §Giao tiếp giữa service |
-
-Trả lời KHÔNG → section tương ứng để **STUB** (không hỏi thêm về nó nữa).
-
-### 3.3 — Pha 2: Đào sâu (drill loop, tới khi ĐỦ-ĐỂ-VIẾT)
-
-Với **mỗi mục được bật (CÓ)** mà nội dung còn thiếu để viết đúng, hỏi tiếp bằng thẻ dễ hiểu — **lặp tới khi đủ**. Ví dụ sau khi CÓ multi-tenant:
-```
-Bạn nói CÓ multi-tenant. Để viết đúng phần này, cho hỏi thêm:
-1. Mỗi bản ghi phân biệt khách hàng bằng cột nào? (vd TenantId, MerchantId, OrgId)
-2. Cách ly kiểu gì? [tự động lọc mọi truy vấn / mỗi khách một DB riêng / khác]
-(Chưa rõ thì gõ "để sau" — mục này để trống, bổ sung sau bằng --section=multi-tenant)
-```
-
-**Ràng buộc loop (BẮT BUỘC — tránh lan man/phiền):**
-- **Chỉ đào sâu trong phạm vi mục SA đã trả lời CÓ.** KHÔNG tự mở chủ đề mới. Mục SA nói KHÔNG → không bao giờ hỏi lại.
-- **Chỉ hỏi khi mơ hồ THỰC SỰ cản việc viết đúng** mục đó — không hỏi chi tiết "cho vui".
-- **Gộp 2–3 câu/lượt** theo cụm, không hỏi lắt nhắt từng cái.
-- **Luôn có lối thoát:** SA gõ "để sau / chưa rõ" → mục đó thành **STUB**, dừng đào sâu ngay. → Loop chắc chắn kết thúc.
-- Follow-up cũng **skip-if-answered**: nếu tài liệu/config/code đã trả lời thì không hỏi.
-
-**Kết thúc phỏng vấn khi:** mọi mục CÓ đều (a) đủ để viết, hoặc (b) SA chủ động hoãn (→ stub). Xung đột ở 3.0 cũng được hỏi xác nhận trong pha này.
-
----
-
-## Bước 4 — Lắp ráp theo tier
-
-Nguồn khung: `.agent/templates/architecture.template.md` (đọc marker `<!-- tier: core|conditional|ops -->` mỗi mục).
-
-1. **core** → **luôn viết**, pre-fill từ Bước 2 + đáp án. Field nào vẫn chưa rõ → giữ `{{PLACEHOLDER}}` + comment (không stub cả mục core).
-2. **conditional** → nếu mục được bật (Bước 2 có nguồn HOẶC phỏng vấn CÓ) → viết đầy đủ; ngược lại → **STUB**:
-   ```
-   ## {Tên mục}  <!-- tier: conditional --> <!-- status: stub -->
-   > ⏳ Chưa tài liệu hoá. Chạy `/generate-architecture --section={slug}` khi cần, hoặc điền tay.
-   ```
-3. **ops** → mặc định **STUB** (không ép điền upfront). Chỉ điền nếu Bước 2 đã có nguồn rõ ràng (vd CI config, logging setup) — khi đó điền luôn, bỏ stub.
-4. **Provenance:** mỗi section điền từ tài liệu ngoài → chèn `<!-- nguồn: {path} -->`. Section có xung đột chưa giải → chèn `<!-- ⚠️ xung đột: … -->`.
-5. **Frontmatter — trust-gate:** `last_verified: {hôm nay}`; `verified_by: AI-draft` (khi có bất kỳ nội dung do AI hút/suy) hoặc `{{AUTHOR}}` (greenfield thuần tay chưa có gì).
-6. Nhất quán thuật ngữ với `business-dictionary.md` + tên entity `core-entities.md`; KHÔNG dùng banned term.
-7. Ghi ra `target`.
-
----
-
-## Bước 5 — Chế độ `--section=<slug>` (điền dần một mục)
-
-Khi `$ARGUMENTS` có `--section=<slug>`: bỏ qua lắp ráp toàn bộ, **chỉ** lấp/refresh đúng mục đó.
-1. Định vị mục theo bảng slug bên dưới trong `target`.
-2. Chạy thu thập (Bước 2) + phỏng vấn đào sâu (Bước 3.3) **giới hạn cho mục này**.
-3. Thay khối stub bằng nội dung đã điền, gỡ `<!-- status: stub -->`. Nếu mục đã có nội dung → refresh theo chênh lệch, giữ chỉnh tay của người.
-4. Cập nhật `last_verified`; nếu file đang `verified_by: {người}` → chỉ đề xuất diff (không tự đè).
-
-**Bảng slug ↔ mục:** `tech-stack` · `layers` · `naming` · `api-response` · `api-conventions` · `database` (core) — `data-flow` · `repositories` · `entity-classification` · `data-access` · `service-responsibilities` · `di` · `multi-tenant` · `identity-resolution` · `api-gateway` · `caching` · `event-bus` · `sharding` · `feature-toggle` · `auth` (conditional) — `observability` · `deployment` · `testing` · `nfr` (ops).
-
----
-
-## Bước 6 — Refresh có kiểm soát (khi file đã verify bởi người)
-
-Nếu Bước 1.4 xác định `verified_by: {người thật}`:
-- KHÔNG ghi đè. Chạy lại thu thập (Bước 2) và **so sánh** với nội dung hiện tại.
-- Xuất **danh sách chênh lệch** (drift): mục nào trong code/config/tài liệu đã khác doc.
-- Với mỗi drift, đề xuất câu chữ cập nhật để SA tự áp; KHÔNG tự đổi `verified_by`.
-
----
-
-## Bước 7 — Bàn giao cho người verify
-
-> Nếu frontmatter ghi `verified_by: AI-draft`:
-> 1. Tech Lead/Architect **duyệt từng section**, sửa chỗ AI đoán sai (đối chiếu `<!-- nguồn: … -->` và `<!-- ⚠️ xung đột -->`).
-> 2. Điền nốt `{{PLACEHOLDER}}` còn lại; lấp các mục STUB cần thiết bằng `--section=<slug>`.
-> 3. Đổi `verified_by: AI-draft` → **tên bạn**, cập nhật `last_verified`. Commit.
->
-> Chỉ khi `verified_by` là người thật, `/generate-tech-docs` (Bước 0.5 [ARCH]) mới coi doc là **ràng buộc kiến trúc chính thức**. Còn `AI-draft` thì bị gắn ⚠️ và ưu tiên CLAUDE.md/BDD khi mâu thuẫn.
-
-## Output
-{{include:steps/report-footer.md}}