@longph2102/v-flow 1.5.0

package/templates/module-card/ui-flows.md

@@ -0,0 +1,91 @@
+<!-- HEADING MAP — Agent PHẢI dùng CHÍNH XÁC các heading dưới đây:
+# UI Flows: {Tên Module}
+## 1. Danh Sách Màn Hình
+## 2. Chi Tiết Từng Màn Hình
+### Màn hình: {Tên màn hình thực}
+-->
+# UI Flows: {Tên Module}
+
+> **Audience chính**: BA, Frontend Dev
+> **AI generate**: Scan components, routes, state management → draft. Human bổ sung UX context.
+
+**App(s)**: {web / mobile / cả hai}
+**Framework**: {framework thực — VD: Flutter, React, Vue...}
+**State Management**: {state management thực — VD: Riverpod, BLoC, Redux...}
+
+---
+
+## 1. Danh Sách Màn Hình
+
+<!-- HƯỚNG DẪN: Scan route definitions, navigation, GoRouter, Navigator.push...
+Liệt kê TẤT CẢ màn hình/screens/pages thuộc module.
+-->
+
+| # | Màn hình | Route/Path | Component/Widget chính | State Manager | Mô tả chức năng |
+|---|---|---|---|---|---|
+| 1 | {tên màn hình thực} | {route thực} | {widget/component thực} | {state manager thực} | {mô tả} |
+
+---
+
+## 2. Chi Tiết Từng Màn Hình
+
+### Màn hình: {Tên màn hình thực}
+
+**Route**: {route thực}
+**Component**: `{WidgetThực}` — File: `{file_thực}`
+**State**: `{StateManagerThực}` — File: `{state_file_thực}`
+
+**UI Elements chính:**
+
+| Element | Loại | Behavior | State liên quan |
+|---|---|---|---|
+| {element thực từ code} | {loại widget} | {behavior mô tả từ code} | `{state_field_thực}` |
+
+**Fields Mapping (UI → API → DB):**
+
+<!-- HƯỚNG DẪN: So sánh tên fields trong UI form/display với tên fields trong API DTO và DB columns.
+Tạo bảng mapping CHÍNH XÁC từ code thực tế.
+-->
+
+| UI Label | UI Component | API Field (Request) | API Field (Response) | DB Column | Validation |
+|---|---|---|---|---|---|
+| "{label thực}" | {component} | `{api_field}` | `{response_field}` | `{db_column}` | {validation} |
+
+**User Flow:**
+
+<!-- HƯỚNG DẪN: Mô tả step-by-step thao tác người dùng.
+Phải phản ánh đúng UX thực tế trong code (navigation, loading states, error handling).
+-->
+
+1. {bước 1 — action người dùng}
+2. {bước 2 — hệ thống phản hồi}
+3. {bước 3 — action tiếp theo}
+
+**API Calls:**
+
+| Action | Endpoint / Method Call | Trigger | Loading State | Error Handling |
+|---|---|---|---|---|
+| {action} | `{endpoint/method thực}` | {trigger} | `{loading_state_thực}` | {error handling} |
+
+---
+
+### Màn hình: {Tên màn hình thực 2}
+
+**Route**: {route thực}
+**Component**: `{WidgetThực}` — File: `{file_thực}`
+
+**UI Elements chính:**
+
+| Element | Loại | Behavior | Điều kiện hiển thị |
+|---|---|---|---|
+| {element thực} | {loại} | {behavior} | {điều kiện} |
+
+**Conditional UI (nếu có phân quyền):**
+
+<!-- HƯỚNG DẪN: Chỉ điền section này nếu UI thay đổi theo role/status.
+Nếu không có conditional UI → bỏ section này.
+-->
+
+| Điều kiện | UI thay đổi | File reference |
+|---|---|---|
+| {điều kiện từ code} | {UI element thay đổi} | `{file_thực}:{line}` |

package/templates/module-card/use-cases.md

@@ -0,0 +1,142 @@
+<!-- HEADING MAP — Agent PHẢI dùng CHÍNH XÁC các heading dưới đây:
+# Use Cases: {Tên Module}
+## 1. Luồng Nghiệp Vụ E2E (End-to-End Flows)
+### Flow 1: {Tên luồng chính}
+### Flow 2: {Tên luồng phụ}
+## 2. Business Rules Chi Tiết
+### BR-01: {Tên rule cụ thể}
+### BR-02: {Tên rule}
+## 3. State Machine
+## 4. Actors & Permissions (Tóm tắt)
+-->
+# Use Cases: {Tên Module}
+
+> **Audience chính**: BA, PO, Domain Expert
+> **AI generate**: Draft từ deep code scan → Human bổ sung business context, SLA
+
+---
+
+## 1. Luồng Nghiệp Vụ E2E (End-to-End Flows)
+
+> ⚠️ Mỗi flow phải mô tả CHÍNH XÁC luồng chạy trong code: từ entry point → xử lý → lưu DB → response.
+> KHÔNG viết chung chung. Phải ghi rõ file/hàm nào xử lý bước nào.
+
+### Flow 1: {Tên luồng chính}
+
+**Trigger**: {Ai trigger, khi nào}
+**Entry point**: `{file_thực}` → hàm `{function_thực}`
+
+**Chi tiết luồng:**
+
+<!-- HƯỚNG DẪN: Mô tả từng bước chạy trong code, dạng:
+1. [Layer] Mô tả — File: file_thực:line
+2. [Layer] Mô tả — File: file_thực:line
+Các layer phổ biến: UI, Controller, Service, Repository, DB, Side-effect, Response
+-->
+
+```
+1. [{Layer}] {mô tả bước 1} — File: {file_thực}:{line}
+2. [{Layer}] {mô tả bước 2} — File: {file_thực}:{line}
+3. [{Layer}] {mô tả bước 3} — File: {file_thực}:{line}
+```
+
+<!-- HƯỚNG DẪN: Vẽ sequence diagram cho flow phức tạp.
+Thay tên participant bằng tên THỰC TẾ từ codebase (class names, file names).
+-->
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant A as {ComponentThực1}
+    participant B as {ComponentThực2}
+    participant C as {ComponentThực3}
+
+    User->>A: {action thực}
+    A->>B: {method call thực}
+    B->>C: {operation thực}
+    C-->>B: {response}
+    B-->>A: {result}
+    A-->>User: {UI feedback}
+```
+
+### Flow 2: {Tên luồng phụ}
+
+**Trigger**: {Ai trigger, khi nào}
+**Entry point**: `{file_thực}` → hàm `{function_thực}`
+
+**Chi tiết luồng:**
+```
+1. [{Layer}] {mô tả} — File: {file_thực}:{line}
+   ...
+```
+
+---
+
+## 2. Business Rules Chi Tiết
+
+> ⚠️ Trích xuất TỪ CODE. Mỗi rule PHẢI có file reference. Không viết chung chung.
+
+### BR-01: {Tên rule cụ thể}
+
+<!-- HƯỚNG DẪN: Mỗi rule phải có:
+- Điều kiện: Khi nào rule apply
+- Hành động: Hệ thống làm gì
+- Code reference: file:line + đoạn code ngắn THỰC TẾ
+- Ngoại lệ: Trường hợp ngoại lệ nếu có
+-->
+
+- **Điều kiện**: {Khi nào rule apply}
+- **Hành động**: {Hệ thống làm gì}
+- **Code reference**: `{file_thực}:{line}` — `{đoạn code ngắn thực tế}`
+- **Ngoại lệ**: {Trường hợp ngoại lệ nếu có}
+- **SLA**: {Thời gian / ràng buộc nếu có} [❓ CẦN HUMAN BỔ SUNG]
+- [⚠️ AI-inferred]
+
+### BR-02: {Tên rule}
+
+- **Điều kiện**: ...
+- **Hành động**: ...
+- **Code reference**: `{file_thực}:{line}`
+- [⚠️ AI-inferred]
+
+---
+
+## 3. State Machine
+
+> ⚠️ States và transitions phải lấy TỪ CODE (enum definitions, transition logic). Không bịa.
+> Source: `{enum_file_thực}` — enum `{EnumName_thực}`
+
+<!-- HƯỚNG DẪN: Vẽ stateDiagram với states THỰC TẾ từ code.
+Lấy từ enum definitions, const values trong codebase.
+TUYỆT ĐỐI KHÔNG copy states mẫu (DRAFT, PENDING_APPROVAL, APPROVED...) nếu module không có.
+Nếu module không có state machine → ghi rõ "Module không có state machine" và bỏ section này.
+-->
+
+```mermaid
+stateDiagram-v2
+    [*] --> {STATE_1} : {event tạo}
+    {STATE_1} --> {STATE_2} : {event chuyển}
+    {STATE_2} --> {STATE_3} : {event chuyển}
+    {STATE_3} --> [*]
+```
+
+| Từ trạng thái | Sang trạng thái | Trigger (Event) | Điều kiện (Guards) | Ai được phép | File reference |
+|---|---|---|---|---|---|
+| `{STATE_1}` | `{STATE_2}` | {event} | {điều kiện} | {actor} | `{file_thực}:{line}` |
+
+**Side-Effects khi chuyển state:**
+
+| Transition | Side-Effect | File reference |
+|---|---|---|
+| → `{STATE}` | {mô tả side-effect} | `{file_thực}:{line}` |
+
+---
+
+## 4. Actors & Permissions (Tóm tắt)
+
+> Chi tiết đầy đủ xem [permissions.md](permissions.md)
+
+| Actor (Role) | Quyền trong module | Phạm vi dữ liệu | Ghi chú |
+|---|---|---|---|
+| `{ROLE_1}` | {quyền} | {phạm vi} | |
+| `{ROLE_2}` | {quyền} | {phạm vi} | |

package/templates/module-template.yaml

@@ -0,0 +1,161 @@
+# Module Template — Subgraph Composition
+# Mỗi module = 1 reusable subgraph trong V Flow pipeline.
+# Lấy cảm hứng từ LangGraph Subgraphs — encapsulated workflows có input/output rõ ràng.
+#
+# Module che giấu internal complexity — parent pipeline chỉ cần biết input/output.
+
+# ─ Cách dùng ─────────────────────────────────────────────────────
+# 1. Tạo file module definition: .v-flow/modules/[name].yaml
+# 2. Dùng module trong pipeline: /v.plan --module security
+# 3. Compose nhiều modules: /v.plan --modules "security,ux,api"
+# ─────────────────────────────────────────────────────────────────
+
+# ═══════════════════════════════════════════════════════════════
+# Module: Build (B.0)
+# ═══════════════════════════════════════════════════════════════
+module_build:
+  name: "build"
+  description: "Plan + Test + Optional Agents chạy song song"
+  phase: "B.0"
+
+  input_required:
+    - "spec.md (approved)"
+    - "constitution.md"
+    - "context.md (nếu legacy)"
+
+  output_produces:
+    - "plan.md"
+    - "tasks.md"
+    - "test-cases.md"
+    - "security-review.md (optional)"
+    - "ux-checklist.md (optional)"
+
+  composed_of:
+    - command: "/v.plan"
+      parallel: true
+      required: true
+    - command: "/v.test"
+      parallel: true
+      required: true
+    - command: "/v-flow.security"
+      parallel: true
+      required: false
+      trigger_keywords: ["auth", "login", "payment", "JWT", "API key"]
+
+  exit_condition:
+    all_required_complete: true
+    output_synced_to_spec: true
+
+  next_module: "review"
+
+# ═══════════════════════════════════════════════════════════════
+# Module: Review (R.0 + R.1)
+# ═══════════════════════════════════════════════════════════════
+module_review:
+  name: "review"
+  description: "Master Check → Gate → Code Review"
+  phase: "R.0 → R.1"
+
+  input_required:
+    - "plan.md"
+    - "tasks.md"
+    - "test-cases.md"
+    - "spec.md"
+
+  output_produces:
+    - "validation-report.md"
+
+  composed_of:
+    - command: "/v.check"
+      required: true
+    - command: "human_gate"   # pause for human approval
+      required: true
+
+  routing:
+    PASS: "implement_module"
+    PASS_WITH_CONCERNS: "implement_module"
+    FAIL: 
+      spec_gap: "specify_module"
+      plan_gap: "build_module"
+      test_gap: "build_module"
+
+  next_module: "implement"
+
+# ═══════════════════════════════════════════════════════════════
+# Module: Implement (B.1)
+# ═══════════════════════════════════════════════════════════════
+module_implement:
+  name: "implement"
+  description: "TDD implementation + Code Review"
+  phase: "B.1 → R.1"
+
+  input_required:
+    - "plan.md"
+    - "tasks.md"
+    - "test-cases.md"
+    - "validation-report.md (PASS or PASS_WITH_CONCERNS)"
+
+  output_produces:
+    - "source code"
+    - "test files"
+    - "updated tasks.md [x]"
+
+  composed_of:
+    - command: "/v.implement"
+      required: true
+    - command: "/v.review"
+      required: true
+
+  routing:
+    APPROVED: "metrics_module"
+    CHANGES_REQUIRED: "self"   # loop back — fix and re-review
+
+  next_module: "metrics"
+
+# ═══════════════════════════════════════════════════════════════
+# Module: Quick Fix (Prebuilt Composed Subgraph)
+# ═══════════════════════════════════════════════════════════════
+module_quickfix:
+  name: "quickfix"
+  description: "Mini Spec → Implement → Quick Review (skip full pipeline)"
+  phase: "S.1 → B.1 → R.1"
+
+  input_required:
+    - "bug description / change request"
+    - "constitution.md"
+
+  output_produces:
+    - "mini spec.md"
+    - "code fix"
+    - "review report"
+
+  composed_of:
+    - command: "/v.quickfix"   # uses internal phases
+      required: true
+
+  exit_condition:
+    review_verdict: ["APPROVED", "APPROVED_WITH_NOTES"]
+
+# ═══════════════════════════════════════════════════════════════
+# Full Pipeline Composition
+# ═══════════════════════════════════════════════════════════════
+pipeline_full:
+  name: "full_pipeline"
+  modules:
+    - "specify"     # S.1 → spec.md
+    - "build"       # B.0 → plan + tests + optional agents
+    - "review"      # R.0 → master check + gate
+    - "implement"   # B.1 + R.1 → code + review
+    - "metrics"     # M.0 → retrospective + metrics
+
+  # Prebuilt alternatives:
+  # quickfix_pipeline: ["quickfix"]
+  # hotfix_pipeline: ["hotfix"]
+
+pipeline_quickfix:
+  name: "quickfix_pipeline"
+  modules: ["quickfix"]
+
+pipeline_hotfix:
+  name: "hotfix_pipeline"
+  modules: ["hotfix"]

package/templates/operations-report-template.md

@@ -0,0 +1,108 @@
+# Template: Operations Report — Báo cáo Vận hành
+
+> Tạo bởi Operations Agent (**O.0**) hoặc thủ công khi có incident.
+> Lưu tại: `.v-flow/features/NNN-ten-feature/operations-report.md` hoặc `.v-flow/incidents/INC-NNN.md`
+
+## Thông tin Incident
+
+| Mục | Giá trị |
+|-----|--------|
+| **Incident ID** | INC-[NNN] |
+| **Severity** | 🔴 P1 / 🟡 P2 / 🔵 P3 / ⚪ P4 |
+| **Phát hiện lúc** | [YYYY-MM-DD HH:MM UTC] |
+| **Phát hiện bởi** | Operations Agent / Manual / Monitoring alert |
+| **Resolved lúc** | [YYYY-MM-DD HH:MM UTC] |
+| **Duration** | [X phút / giờ] |
+
+---
+
+## 1. Mô tả sự cố
+
+### Triệu chứng
+<!-- Mô tả ngắn gọn: cái gì bị lỗi, users thấy gì -->
+
+### Timeline
+| Thời gian | Sự kiện |
+|-----------|---------|
+| [HH:MM] | [Anomaly đầu tiên được phát hiện] |
+| [HH:MM] | [Hành động đầu tiên] |
+| [HH:MM] | [Fix được deploy] |
+| [HH:MM] | [Confirmed resolved] |
+
+---
+
+## 2. Impact — Ảnh hưởng
+
+| Metric | Giá trị |
+|--------|--------|
+| Users bị ảnh hưởng | |
+| Error rate (peak) | |
+| Services bị ảnh hưởng | |
+| Revenue impact (nếu có) | |
+
+---
+
+## 3. Root Cause Analysis
+
+### Nguyên nhân gốc
+<!-- Mô tả chi tiết nguyên nhân -->
+
+### Feature / Component liên quan
+| Mục | Giá trị |
+|-----|--------|
+| Feature | #[NNN] — [Tên feature] |
+| Spec | `.v-flow/features/NNN/spec.md` |
+| Commit gây lỗi | [commit hash] — [message] |
+| File | [path:line] |
+
+### Phân loại nguyên nhân
+- [ ] Code bug (logic error, unhandled exception)
+- [ ] Data issue (schema mismatch, bad data)
+- [ ] Infrastructure (resource exhaustion, config error)
+- [ ] External dependency (3rd party API down)
+- [ ] Deployment issue (failed migration, config)
+- [ ] Khác: ___
+
+---
+
+## 4. Resolution — Giải pháp
+
+### Hành động đã thực hiện
+1. [Mô tả fix]
+
+### Fix verification
+- [ ] Fix đã deploy
+- [ ] Error rate trở về baseline
+- [ ] Không có side effects
+
+---
+
+## 5. Lessons Learned & Prevention
+
+### Test gaps phát hiện
+<!-- Test cases nào bị thiếu mà nên có? -->
+- [ ] [Test case cần thêm]
+
+### Process gaps
+<!-- Quy trình nào cần cải thiện? -->
+- [ ] [Process improvement]
+
+### Follow-up actions
+| Action | Owner | Deadline | Status |
+|--------|-------|----------|--------|
+| [Thêm test case] | [Tên] | [Date] | [ ] |
+| [Cập nhật spec/plan] | [Tên] | [Date] | [ ] |
+| [Cập nhật monitoring] | [Tên] | [Date] | [ ] |
+
+---
+
+## 6. Traceability
+
+| Artifact | Link |
+|----------|------|
+| Spec gốc | `.v-flow/features/NNN/spec.md` |
+| Plan gốc | `.v-flow/features/NNN/plan.md` |
+| Test cases | `.v-flow/features/NNN/test-cases.md` |
+| Metrics report | `.v-flow/features/NNN/metrics-report.md` |
+| Fix PR/MR | [link to merge request] |
+| Monitoring dashboard | [link to dashboard] |