@longph2102/v-flow 1.5.0

package/templates/module-card/business-quiz.md

@@ -0,0 +1,119 @@
+<!-- HEADING MAP — Agent PHẢI dùng CHÍNH XÁC các heading dưới đây:
+# Business Quiz: {Tên Module}
+## ⚠️ Hướng Dẫn Sử Dụng
+## MUST — Câu Hỏi Bắt Buộc
+### Q{NN}: {Tên ngắn của câu hỏi}
+## SHOULD — Câu Hỏi Nâng Cao
+### Q{NN}: {Tên ngắn của câu hỏi}
+## Changelog
+-->
+
+---
+module: domain-{tên-module}
+module_version: "{version}"         # Version của module card lúc tạo file này
+created_at: "YYYY-MM-DD"
+created_by: "v.understand"          # "v.understand" | "human"
+last_reviewed_by: null              # Human BA/PO đã review câu hỏi chưa?
+last_reviewed_at: null
+status: "draft"                     # "draft" | "ready" (ready = đã được Human review)
+---
+
+# Business Quiz: {Tên Module}
+
+> ⚠️ **FILE NÀY KHÔNG CHỨA ĐÁP ÁN**
+> Human BA/PO là answer key — đánh giá câu trả lời của AI bằng domain knowledge của mình.
+> AI Agent: Đọc câu hỏi, trả lời dựa trên hiểu biết từ module cards (`use-cases.md`, `SKILL.md`...). **KHÔNG** dùng nội dung file này làm đáp án.
+
+---
+
+## ⚠️ Hướng Dẫn Sử Dụng
+
+**Dành cho Human BA/PO (khi review câu hỏi):**
+- Xóa nhãn `[⚙️ AI draft]` và thay bằng `[✅ Human verified]` khi câu hỏi đã đúng
+- Chỉnh sửa câu hỏi nếu AI draft chưa đúng trọng tâm
+- Thêm câu hỏi mới nếu cần (đặc biệt: "bẫy nghiệp vụ" mà AI dễ hiểu sai)
+- Đặt `status: "ready"` trong frontmatter khi hoàn tất review
+- Câu hỏi tốt: test *reasoning về ý nghĩa nghiệp vụ*, KHÔNG phải *biết API endpoint hay tên bảng*
+
+**Dành cho AI Agent (khi trả lời):**
+- Đọc câu hỏi → trả lời dựa trên module cards, KHÔNG đọc file này để lấy gợi ý
+- Trả lời bằng ngôn ngữ tự nhiên, giải thích reasoning
+- Nếu không chắc → nói thẳng, đừng đoán
+
+> ⛔ **QUY TẮC NGÔN NGỮ (cưỡng chế bằng máy):** Câu hỏi phải viết bằng **ngôn ngữ nghiệp vụ**, người không-code đọc được. **CẤM** dính token code trong câu hỏi: `backtick`, `camelCase`, `snake_case`, `TÊN_HẰNG`, `tênHàm()`, endpoint `/api/...`, đuôi file (`.dart/.js`…). Nếu phải nói tới một khái niệm code → diễn đạt lại bằng nghiệp vụ ("trạng thái đơn hàng" thay vì `OrderStatus`). Kiểm bằng: `v-flow validate --module-cards` (cảnh báo; `--strict` chặn).
+
+---
+
+## MUST — Câu Hỏi Bắt Buộc
+
+> Tất cả câu hỏi MUST phải được AI trả lời đúng → mới được proceed `/v.specify`.
+> Trả lời sai bất kỳ câu MUST nào → FAILED → dừng lại, không viết spec.
+
+<!-- HƯỚNG DẪN: Viết 3-5 câu hỏi về business rules/flows QUAN TRỌNG NHẤT của module.
+     Câu hỏi phải:
+     - Yêu cầu AI giải thích ý nghĩa nghiệp vụ (WHY), không chỉ mô tả code (WHAT)
+     - Có liên quan trực tiếp đến spec sắp viết
+     - Không thể trả lời đúng chỉ bằng cách đọc tên hàm/endpoint
+     - Ưu tiên KHUNG TÌNH HUỐNG (scenario) — tự nó là ngôn ngữ nghiệp vụ:
+       dùng 5 dạng trong docs/business-quiz-guide.md (WHY / EXCEPTION / OWNERSHIP / IMPACT / CROSS-MODULE)
+     - KHÔNG dính token code (xem QUY TẮC NGÔN NGỮ ở trên) → `v-flow validate --module-cards` cảnh báo
+     Ví dụ tốt: "Khách gọi 45 phút sau khi đặt đòi đổi địa chỉ giao — hệ thống cho phép gì và vì sao? Ai quyết định mốc thời gian này?"
+     Ví dụ tệ: "Enum OrderStatus có những giá trị nào?"
+-->
+
+### Q01: {Tên ngắn — ví dụ: "Điều kiện hủy đơn hàng"} [⚙️ AI draft]
+
+**Câu hỏi**: {Câu hỏi mở về business rule/flow quan trọng nhất — yêu cầu giải thích WHY và ai chịu trách nhiệm}
+
+**Lý do quan trọng**: {Nếu AI hiểu sai điều này → spec sẽ sai ở đâu? Ảnh hưởng gì?}
+
+---
+
+### Q02: {Tên ngắn} [⚙️ AI draft]
+
+**Câu hỏi**: {Câu hỏi về edge case hoặc business constraint ít rõ ràng từ code}
+
+**Lý do quan trọng**: {Tại sao điều này quan trọng với feature sắp viết spec}
+
+---
+
+### Q03: {Tên ngắn} [⚙️ AI draft]
+
+**Câu hỏi**: {Câu hỏi về actor, permission, hoặc ownership trong domain này}
+
+**Lý do quan trọng**: {Hiểu sai actor → spec có thể thiếu/sai use case}
+
+---
+
+## SHOULD — Câu Hỏi Nâng Cao
+
+> Câu hỏi SHOULD: Trả lời sai → PASSED WITH WARNING, không block.
+> Agent ghi concern vào `_session.md` và tiếp tục.
+
+<!-- HƯỚNG DẪN: 2-3 câu hỏi về business context nâng cao:
+     - Integration với module khác
+     - Exceptional cases ít phổ biến
+     - Business rationale đằng sau thiết kế hiện tại
+-->
+
+### Q04: {Tên ngắn} [⚙️ AI draft]
+
+**Câu hỏi**: {Câu hỏi về tích hợp với module khác hoặc exceptional case}
+
+**Lý do quan trọng**: {Bỏ qua điều này sẽ ảnh hưởng gì đến chất lượng spec}
+
+---
+
+### Q05: {Tên ngắn} [⚙️ AI draft]
+
+**Câu hỏi**: {Câu hỏi về business rationale hoặc lịch sử quyết định thiết kế}
+
+**Lý do quan trọng**: {Context này giúp spec tốt hơn ở điểm nào}
+
+---
+
+## Changelog
+
+| Version | Ngày | Thay đổi | Bởi |
+|---|---|---|---|
+| 1.0 | {date} | Khởi tạo từ AI scan | v.understand |

package/templates/module-card/cross-service.md

@@ -0,0 +1,125 @@
+<!-- HEADING MAP — Agent PHẢI dùng CHÍNH XÁC các heading dưới đây:
+# Cross-Service Integration: {Tên Module}
+## 1. HTTP/REST Calls
+### Outgoing (Module này GỌI ra ngoài)
+### Incoming (Service khác GỌI module này)
+## 2. Message Queue (nếu có)
+### Publish (Module này GỬI event)
+### Consume (Module này NHẬN event)
+## 3. Shared Database (nếu có)
+## 4. External Integrations (hệ thống ngoài, nếu có)
+## 5. Dependency Map (Tổng quan)
+-->
+# Cross-Service Integration: {Tên Module}
+
+> **Audience**: Dev, Architect
+> **AI generate**: Có Graph → cross-service calls auto-detected. Không Graph → scan HTTP clients, message consumers, external SDK imports.
+> ⚠️ Mỗi integration phải ghi rõ: file nào gọi, endpoint/topic gì, payload gì, có retry/fallback không.
+
+---
+
+## 1. HTTP/REST Calls
+
+> Scan: Grep `HttpClient`, `fetch`, `axios`, `dio`, `RestTemplate`, `http.get/post`, `@HttpService` trong module.
+
+### Outgoing (Module này GỌI ra ngoài)
+
+<!-- HƯỚNG DẪN: Liệt kê TẤT CẢ HTTP calls RA NGOÀI module.
+Phải scan code tìm http client calls, dio requests, fetch calls...
+Ghi rõ file + line number thực tế.
+-->
+
+| # | Target Service | Endpoint | Method | Mục đích | File thực hiện gọi | Timeout | Retry? | Circuit Breaker? |
+|---|---|---|---|---|---|---|---|---|
+| 1 | {service_thực} | `{endpoint_thực}` | {method} | {mục đích} | `{file_thực}:{line}` | {timeout} | {✅/❌} | {✅/❌} |
+
+**Payload chi tiết (nếu có):**
+
+#### Call #1: {mô tả}
+```json
+// Request
+{METHOD} {/endpoint/thực}
+{
+  "{field}": "{type — mô tả}"
+}
+
+// Response
+{
+  "{field}": "{type — mô tả}"
+}
+
+// Error handling: {mô tả cách xử lý lỗi thực tế từ code}
+```
+
+### Incoming (Service khác GỌI module này)
+
+| # | Caller Service | Endpoint bị gọi | Method | Mục đích | Controller/Handler |
+|---|---|---|---|---|---|
+| 1 | {service_thực} | `{endpoint_thực}` | {method} | {mục đích} | `{file_thực}:{line}` |
+
+---
+
+## 2. Message Queue (nếu có)
+
+> Scan: Grep `publish`, `emit`, `subscribe`, `consume`, `@EventHandler`, `@OnEvent`, `Kafka`, `RabbitMQ`, `@MessagePattern`.
+> Nếu module KHÔNG dùng message queue → ghi "Không sử dụng" và bỏ chi tiết.
+
+### Publish (Module này GỬI event)
+
+| # | Topic / Queue | Event Name | Khi nào publish | Payload chính | File publish | Ghi chú |
+|---|---|---|---|---|---|---|
+| 1 | `{topic_thực}` | `{EVENT_thực}` | {điều kiện} | `{fields chính}` | `{file_thực}:{line}` | |
+
+### Consume (Module này NHẬN event)
+
+| # | Topic / Queue | Event Name | Xử lý gì | File consumer | Error handling |
+|---|---|---|---|---|---|
+| 1 | `{topic_thực}` | `{EVENT_thực}` | {xử lý gì} | `{file_thực}:{line}` | {error handling} |
+
+---
+
+## 3. Shared Database (nếu có)
+
+> ⚠️ Shared DB là antipattern. Ghi lại để awareness và risk management.
+> Nếu module KHÔNG share DB → ghi "Không có" và bỏ chi tiết.
+
+| Table | Dùng chung với Module | Đọc/Ghi | Rủi ro | File access |
+|---|---|---|---|---|
+| `{table_thực}` | {module khác} | {R/W} | {rủi ro} | `{file_thực}:{line}` |
+
+---
+
+## 4. External Integrations (hệ thống ngoài, nếu có)
+
+| # | System | Protocol | Mục đích | SLA / Timeout | Auth | File xử lý | Fallback khi fail |
+|---|---|---|---|---|---|---|---|
+| 1 | {system_thực} | {protocol} | {mục đích} | {timeout} | {auth} | `{file_thực}` | {fallback} |
+
+---
+
+## 5. Dependency Map (Tổng quan)
+
+<!-- HƯỚNG DẪN: Vẽ mermaid graph với tên service/module THỰC TẾ từ codebase.
+KHÔNG copy graph mẫu — phải phản ánh dependencies thực tế đã scan ở trên.
+-->
+
+```mermaid
+graph LR
+    subgraph "Module: {Tên Module}"
+        M[{ServiceChính}]
+    end
+
+    subgraph "Internal"
+        I1[{DependencyNội1}]
+    end
+
+    subgraph "External"
+        E1[{DependencyNgoài1}]
+    end
+
+    M -->|{cách gọi}| I1
+    M -->|{cách gọi}| E1
+
+    style M fill:#4CAF50,color:#fff
+    style E1 fill:#FF9800,color:#fff
+```

package/templates/module-card/db.md

@@ -0,0 +1,85 @@
+<!-- HEADING MAP — Agent PHẢI dùng CHÍNH XÁC các heading dưới đây:
+# Database Schema: {Tên Module}
+## 1. Danh Sách Bảng (Tables)
+## 2. Chi Tiết Từng Bảng
+### Bảng: `{table_thực}`
+## 3. Mối Quan Hệ (Relationships)
+## 4. DDL & Migrations Links
+-->
+# Database Schema: {Tên Module}
+
+> **Audience chính**: Backend Dev, DBA, Data Analyst
+> **AI generate**: Scan entity/model files, migrations, ORM annotations → auto-generate. Human verify constraints.
+
+**Database**: {database thực — VD: PostgreSQL, MySQL, SQLite, MongoDB...}
+**ORM**: {ORM thực — VD: TypeORM, Prisma, Sqflite, Mongoose...}
+
+---
+
+## 1. Danh Sách Bảng (Tables)
+
+<!-- HƯỚNG DẪN: Liệt kê TẤT CẢ bảng/collection THỰC TẾ của module từ code.
+Lấy từ entity files, migration files, hoặc CREATE TABLE statements.
+TUYỆT ĐỐI KHÔNG copy bảng mẫu — phải scan code để tìm bảng thực.
+-->
+
+| Tên Bảng | Ý Nghĩa / Chức Năng | Entity/Model File | Số Cột | Ghi chú |
+|---|---|---|---|---|
+| `{table_thực_1}` | {mô tả chức năng} | `{entity_file_thực}` | {N} | {ghi chú} |
+| `{table_thực_2}` | {mô tả chức năng} | `{entity_file_thực}` | {N} | {ghi chú} |
+
+---
+
+## 2. Chi Tiết Từng Bảng
+
+### Bảng: `{table_thực_1}`
+
+**Mô tả**: {mô tả bảng — lấy từ comment trong code hoặc suy luận từ tên + fields}
+**Entity file**: `{entity_file_thực}`
+
+<!-- HƯỚNG DẪN: Liệt kê TẤT CẢ columns từ entity/model definition.
+Phải đọc file entity để lấy chính xác: tên cột, kiểu dữ liệu, constraints, default values.
+-->
+
+| Tên Cột | Kiểu Dữ Liệu | Constraints | Default | Ý Nghĩa | Ghi chú |
+|---|---|---|---|---|---|
+| `{column_thực}` | `{type_thực}` | {PK/FK/NN/UNIQUE} | {default} | {ý nghĩa} | {ghi chú} |
+
+**Indexes** (nếu có):
+- `{index_name}` — {type} on `{columns}`
+
+### Bảng: `{table_thực_2}`
+
+**Mô tả**: {mô tả}
+**Entity file**: `{entity_file_thực}`
+
+| Tên Cột | Kiểu Dữ Liệu | Constraints | Default | Ý Nghĩa |
+|---|---|---|---|---|
+| `{column_thực}` | `{type_thực}` | {constraints} | {default} | {ý nghĩa} |
+
+---
+
+## 3. Mối Quan Hệ (Relationships)
+
+<!-- HƯỚNG DẪN: Scan foreign keys, @OneToMany, @ManyToOne, @BelongsTo, references... trong code.
+Phải ghi rõ ON DELETE behavior thực tế.
+-->
+
+| Bảng A | Quan hệ | Bảng B | Khóa Ngoại (FK) | ON DELETE | Ghi chú |
+|---|---|---|---|---|---|
+| `{table_A}` | {1→n / n→1 / n→n} | `{table_B}` | `{fk_column}` → `{ref_table}.{ref_column}` | {CASCADE/SET NULL/RESTRICT} | {ghi chú} |
+
+```mermaid
+erDiagram
+    {TABLE_A} ||--o{ {TABLE_B} : "{relationship}"
+```
+
+---
+
+## 4. DDL & Migrations Links
+
+<!-- HƯỚNG DẪN: Link đến migration files hoặc CREATE TABLE statements thực tế trong codebase.
+Nếu không có migrations riêng (VD: tạo bảng trong code) → ghi rõ file + hàm tạo bảng.
+-->
+
+- [{mô tả migration}]({file:///path/thực/đến/migration})

package/templates/module-card/dev-quiz.md

@@ -0,0 +1,62 @@
+<!-- HEADING MAP — Agent PHẢI dùng CHÍNH XÁC các heading dưới đây:
+# Dev Quiz: {Tên Module}
+## ⚠️ Hướng Dẫn Sử Dụng
+## MUST — Câu Hỏi Bắt Buộc
+### DQ{NN}: {Tên ngắn} [target: {symbol} | direction: {upstream|downstream}]
+## Changelog
+-->
+
+---
+module: domain-{tên-module}
+module_version: "{version}"
+created_at: "YYYY-MM-DD"
+created_by: "v.understand"
+status: "draft"
+---
+
+# Dev Quiz: {Tên Module}
+
+> ⚙️ **ANSWER KEY = GRAPH, KHÔNG PHẢI CON NGƯỜI.**
+> Khác business-quiz (human chấm intent nghiệp vụ), dev-quiz **chấm máy** theo GitNexus:
+> mỗi câu khai báo `target` symbol; đáp án đúng = blast-radius thật từ `gitnexus impact`.
+> Sinh answer key: `v-flow dev-quiz <module>` · Chấm: `v-flow dev-quiz <module> --answers <file>`.
+
+---
+
+## ⚠️ Hướng Dẫn Sử Dụng
+
+**Cho người viết câu hỏi (Tech Lead / v.understand):**
+- Mỗi câu hỏi PHẢI khai báo `[target: <tên symbol thật> | direction: upstream|downstream]` ở heading.
+  - `upstream` = ai phụ thuộc vào symbol (đổi nó thì gãy đâu) — dùng cho câu "blast-radius".
+  - `downstream` = symbol phụ thuộc vào ai.
+- `target` phải là **symbol có thật trong graph** (hàm/method/class) — nếu sai tên → `v-flow dev-quiz` báo `unverified`.
+- Câu hỏi test **khả năng suy luận tác động**, thứ phân biệt dev senior với junior.
+
+**Cho người/agent trả lời:** liệt kê các symbol bị ảnh hưởng dưới `**Answer**:` (phân tách bằng dấu phẩy). Chấm bằng F1 so với graph.
+
+---
+
+## MUST — Câu Hỏi Bắt Buộc
+
+<!-- HƯỚNG DẪN: 3-5 câu về tác động/kiến trúc. target = symbol QUAN TRỌNG / rủi ro cao của module.
+     Ví dụ: ### DQ01: Tác động khi đổi hủy đơn [target: cancelOrder | direction: upstream]
+     **Câu hỏi**: Nếu thay đổi logic hủy đơn, những thành phần nào sẽ bị ảnh hưởng trực tiếp/gián tiếp?
+-->
+
+### DQ01: {Tên ngắn} [target: {symbol} | direction: upstream]
+
+**Câu hỏi**: {Nếu đổi `target`, những đâu sẽ gãy? Liệt kê thành phần phụ thuộc.}
+
+---
+
+### DQ02: {Tên ngắn} [target: {symbol} | direction: upstream]
+
+**Câu hỏi**: {Câu hỏi blast-radius cho symbol rủi ro thứ 2}
+
+---
+
+## Changelog
+
+| Version | Ngày | Thay đổi | Bởi |
+|---|---|---|---|
+| 1.0 | {date} | Khởi tạo từ AI scan | v.understand |

package/templates/module-card/permissions.md

@@ -0,0 +1,83 @@
+<!-- HEADING MAP — Agent PHẢI dùng CHÍNH XÁC các heading dưới đây:
+# Phân Quyền & Vai Trò: {Tên Module}
+## 1. Danh Sách Vai Trò (Roles)
+## 2. Danh Sách Quyền (Permissions)
+## 3. Ma Trận Phân Quyền (Role × Permission Matrix)
+## 4. Phân Quyền Theo Dữ Liệu (Data Policies / VPS)
+### 4.1 {Tên policy}
+### 4.2 Bảng tổng hợp Data Scope
+-->
+# Phân Quyền & Vai Trò: {Tên Module}
+
+> **Audience chính**: BA, Security, Backend Dev
+> **AI generate**: Scan Auth Guards, Roles Decorators, RBAC/ABAC logic, middleware.
+> ⚠️ Permissions phải lấy TỪ CODE THỰC TẾ (decorators, guards, middleware, config).
+
+**Auth scheme**: {scheme thực — VD: JWT, Session, API Key, hoặc "N/A — local app"}
+**RBAC implementation**: {implementation thực}
+**Guard/Middleware file**: `{file_thực}`
+
+---
+
+## 1. Danh Sách Vai Trò (Roles)
+
+> Source: `{enum_file_thực}` — enum `{RoleEnum_thực}`
+
+<!-- HƯỚNG DẪN: Liệt kê roles TỪ CODE THỰC TẾ.
+Scan enum definitions, role constants, @Roles decorators.
+Nếu module KHÔNG có hệ thống roles → ghi rõ "Module không phân quyền theo roles" và điều chỉnh section.
+-->
+
+| Mã Role | Tên Vai Trò | Cấp Độ / Phạm Vi | Mô Tả | Cách xác định phạm vi |
+|---|---|---|---|---|
+| `{ROLE_thực}` | {tên} | {phạm vi} | {mô tả} | {cách filter data} |
+
+---
+
+## 2. Danh Sách Quyền (Permissions)
+
+> Source: `{permission_file_thực}` — enum `{PermissionEnum_thực}`
+
+| Mã Permission | Chức Năng Tương Ứng | API Endpoint / Method | Nhóm | Guard/Decorator |
+|---|---|---|---|---|
+| `{PERM_thực}` | {chức năng} | `{endpoint/method_thực}` | {nhóm} | `{guard thực}` |
+
+---
+
+## 3. Ma Trận Phân Quyền (Role × Permission Matrix)
+
+> ⚠️ Mỗi ô phải ghi rõ điều kiện bổ sung (nếu có). Không chỉ ✅/❌.
+
+<!-- HƯỚNG DẪN: Tạo ma trận với roles và permissions THỰC TẾ đã liệt kê ở trên.
+Headers cột = roles thực, headers hàng = permissions thực.
+-->
+
+| Permission \ Role | `{ROLE_1}` | `{ROLE_2}` | `{ROLE_3}` | Điều kiện bổ sung |
+|---|---|---|---|---|
+| `{PERM_1}` | {✅/❌ + scope} | {✅/❌ + scope} | {✅/❌ + scope} | {điều kiện từ code} |
+
+---
+
+## 4. Phân Quyền Theo Dữ Liệu (Data Policies / VPS)
+
+> ⚠️ Mô tả chi tiết cách hệ thống chặn dữ liệu theo Tenant/VPS/Owner. Ghi rõ implementation.
+> Nếu module KHÔNG có data-level permissions → ghi rõ "Không có data filtering — tất cả users xem cùng data".
+
+<!-- HƯỚNG DẪN: Scan WHERE clauses, filter logic, tenant_id, owner_id, branch_id trong queries.
+Mô tả CHÍNH XÁC cách code filter data cho từng role.
+-->
+
+### 4.1 {Tên policy — VD: "Theo owner", "Theo tenant", "Theo branch"}
+
+- **Ai áp dụng**: {role}
+- **Cơ chế**: {mô tả cách filter}
+- **Implementation**: 
+  - File: `{file_thực}:{line}` — hàm `{function_thực}`
+- **Edge case**: {edge case nếu có}
+
+### 4.2 Bảng tổng hợp Data Scope
+
+| Role | SELECT (View) | INSERT (Create) | UPDATE (Edit) | DELETE |
+|---|---|---|---|---|
+| `{ROLE_1}` | {scope} | {scope} | {scope} | {scope} |
+| `{ROLE_2}` | {scope} | {scope} | {scope} | {scope} |

package/templates/module-card/state-diagram.md

@@ -0,0 +1,64 @@
+<!-- HEADING MAP — Agent PHẢI dùng CHÍNH XÁC các heading dưới đây:
+# State Machine: {Tên Module}
+## 1. Sơ Đồ Trạng Thái (State Diagram)
+## 2. Chi Tiết Các Trạng Thái (States)
+## 3. Quy Tắc Chuyển Đổi (Transitions & Triggers)
+## 4. Side-Effects (Hệ quả khi chuyển state)
+-->
+# State Machine: {Tên Module}
+
+> **Audience chính**: BA, Backend Dev
+> **AI generate**: Scan Enums, transition logic, side-effects trong code.
+> ⚠️ States và transitions phải lấy TỪ CODE THỰC TẾ. Không bịa.
+
+**Enum file**: `{file_thực}` — enum `{EnumName_thực}`
+**Transition logic**: `{service_file_thực}` — các hàm xử lý chuyển state
+
+---
+
+## 1. Sơ Đồ Trạng Thái (State Diagram)
+
+<!-- HƯỚNG DẪN: Vẽ stateDiagram với các states LẤY TỪ ENUM/CONST THỰC TẾ trong code.
+Scan: enum Status, enum State, const STATUS_*, và các nơi state được thay đổi.
+TUYỆT ĐỐI KHÔNG copy states mẫu (DRAFT, PENDING_APPROVAL...) nếu code không có.
+Nếu module KHÔNG có state machine → ghi "Module không có state machine rõ ràng" và mô tả UI states thay thế.
+-->
+
+```mermaid
+stateDiagram-v2
+    [*] --> {STATE_THỰC_1} : {event tạo — từ code}
+    {STATE_THỰC_1} --> {STATE_THỰC_2} : {event — từ code}
+    {STATE_THỰC_2} --> {STATE_THỰC_3} : {event — từ code}
+    {STATE_THỰC_3} --> [*]
+```
+
+---
+
+## 2. Chi Tiết Các Trạng Thái (States)
+
+| Trạng Thái (Mã Enum) | Tên Hiển Thị (UI) | Ý Nghĩa / Định Nghĩa | Có thể chuyển tiếp? |
+|---|---|---|---|
+| `{STATE_THỰC_1}` | {tên UI} | {ý nghĩa} | {✅ mô tả / ❌ final state} |
+
+---
+
+## 3. Quy Tắc Chuyển Đổi (Transitions & Triggers)
+
+> ⚠️ Mỗi transition phải có file reference + điều kiện cụ thể từ code.
+
+| # | Trạng Thái Hiện Tại | Event Kích Hoạt | Trạng Thái Mới | Điều Kiện (Guards) | Actor (Ai được phép) | File Reference |
+|---|---|---|---|---|---|---|
+| T-01 | `{STATE_1}` | {event từ code} | `{STATE_2}` | {điều kiện từ code} | {actor} | `{file_thực}:{line}` |
+
+**Transitions KHÔNG hợp lệ (code sẽ throw error):**
+- {Liệt kê transitions bị cấm từ code thực tế}
+
+---
+
+## 4. Side-Effects (Hệ quả khi chuyển state)
+
+> ⚠️ Ghi rõ side-effects từ code: notification, email, sync, audit log...
+
+| Transition | Side-Effect | Cơ chế | File Reference | Ghi chú |
+|---|---|---|---|---|
+| → `{STATE}` | {side-effect từ code} | {cơ chế} | `{file_thực}:{line}` | |

package/templates/module-card/tech-context.md

@@ -0,0 +1,90 @@
+<!-- HEADING MAP — Agent PHẢI dùng CHÍNH XÁC các heading dưới đây:
+# Tech Context: {Tên Module}
+## 1. Key Files
+## 2. Architecture Patterns
+## 3. Dependencies
+### Module này GỌI (outgoing)
+### Module khác GỌI module này (incoming)
+## 4. Tech Debt & Known Issues
+## 5. Test Coverage
+-->
+# Tech Context: {Tên Module}
+
+> **Audience chính**: Dev, Tech Lead
+> **AI generate**: Có Graph → ~100% auto. Không Graph → scan imports/files → ~70% auto
+
+---
+
+## 1. Key Files
+
+> ⚠️ Mỗi file phải có MÔ TẢ VAI TRÒ CỤ THỂ — không chỉ ghi "core logic" hay "xử lý API".
+> Phải giải thích file này LÀM GÌ đủ rõ để dev mới đọc hiểu mà không cần mở code.
+
+<!-- HƯỚNG DẪN: List TẤT CẢ files quan trọng trong module.
+Đọc TỪNG file để viết mô tả vai trò CỤ THỂ (không phải "xử lý logic").
+VD đúng: "Xử lý 5 use cases: load scenarios, open scenario, validate move, check solution, request hint"
+VD sai: "Core business logic"
+-->
+
+| File | Vai trò CỤ THỂ | LOC | Có Test? | Ghi chú |
+|---|---|---|---|---|
+| `{file_thực_1}` | {mô tả vai trò cụ thể: file này làm gì, xử lý bao nhiêu operations, gọi dependencies nào} | ~{N} | {✅/❌} | |
+| `{file_thực_2}` | {mô tả vai trò cụ thể} | ~{N} | {✅/❌} | |
+
+---
+
+## 2. Architecture Patterns
+
+> ⚠️ Không chỉ liệt kê tên pattern. Mô tả CÁCH module thực sự áp dụng pattern đó — bao gồm cả chỗ vi phạm.
+
+<!-- HƯỚNG DẪN: Phân tích patterns TỪ CODE THỰC TẾ.
+Xem cấu trúc thư mục, cách import, flow data giữa các layers.
+Ghi rõ cả nơi pattern bị vi phạm (bypass, coupling).
+-->
+
+- **{Pattern_thực}**: {Mô tả CÁCH module dùng — bao gồm ngoại lệ/vi phạm nếu có}
+- **{Pattern_thực_2}**: {Mô tả}
+
+---
+
+## 3. Dependencies
+
+### Module này GỌI (outgoing)
+
+| Target | Cách gọi | Mục đích | File thực hiện gọi |
+|---|---|---|---|
+| `{target_thực}` | {DI / import / HTTP / ...} | {mục đích} | `{file_thực}:{line}` |
+
+### Module khác GỌI module này (incoming)
+
+| Caller | Cách gọi | Mục đích | File bị gọi |
+|---|---|---|---|
+| `{caller_thực}` | {cách gọi} | {mục đích} | `{file_thực}` → hàm `{function_thực}` |
+
+---
+
+## 4. Tech Debt & Known Issues
+
+> ⚠️ Chỉ đích danh file, mô tả vấn đề cụ thể, đánh giá severity.
+
+<!-- HƯỚNG DẪN: Scan code tìm TODO, FIXME, HACK, WORKAROUND, DEPRECATED.
+Đếm files > 300 LOC, hàm > 50 LOC.
+Đánh giá severity: 🔴 Cao, 🟠 Trung bình, 🟡 Thấp
+-->
+
+| # | Vấn đề | Severity | File reference | Ảnh hưởng | Kế hoạch fix |
+|---|---|---|---|---|---|
+| 1 | {vấn đề cụ thể từ code} | {🔴/🟠/🟡} | `{file_thực}` | {ảnh hưởng} | [❓ CẦN HUMAN BỔ SUNG] |
+
+---
+
+## 5. Test Coverage
+
+| Loại test | Có? | Coverage ước tính | Tool | Ghi chú |
+|---|---|---|---|---|
+| Unit | {✅/❌} | ~{N}% | {tool} | |
+| Integration | {✅/❌} | ~{N}% | {tool} | |
+| E2E | {✅/❌} | ~{N}% | {tool} | |
+
+**Files KHÔNG có test** (cần ưu tiên):
+- `{file_thực}` — {mô tả}, {N} LOC