M-002 Phase 2 — Workflow Governance Engine (Unified Plan)
M-002 Phase 2 — Workflow Governance Engine
Version: v1.5 | Date: 2026-03-04 (S102) Quyết định bởi: Claude AI (Điều hành kỹ thuật) + GPT (Phản biện kiến trúc) + User (Mục tiêu chiến lược) Status: APPROVED — Thay thế tất cả bản draft trước đó v1.2: Process Registry + Supervisor UI v1.3: Trang Workflows top-level v1.4: Đổi level Cụ/Bà/Me → Cấp 1/2/3. TD-062 (400 error). v1.5 — S102: Cập nhật Phase 2A hoàn thành. Bổ sung §XI Text-First Governance (4 điểm mù kiến trúc). BPMN layout fix + tab color fix → TD-064. Đổi "Bảng bước" → "Trình tự".
I. TUYÊN BỐ — M-002 LÀ GÌ
M-002 không phải workflow builder hay công cụ vẽ sơ đồ.
M-002 là hệ điều hành quy trình cho AI Council — nơi:
- Quy trình được tạo nhanh hơn viết code
- AI điều phối AI như điều phối robot vật lý
- Hàng ngàn flow chạy song song mà không hỗn loạn
- Bấm là chạy. Không debug thủ công.
Phase 1 đã xong: BPMN Viewer + Modeler + Annotations → COMMERCIAL CONFIRMED. Phase 2 bắt đầu: Xây engine thực sự phía dưới — DSL, Governance, Block Library.
II. KIẾN TRÚC 4 TẦNG
┌─────────────────────────────────────────────────────────┐
│ TẦNG 4 — VISUALIZATION (✅ XONG — Phase 1) │
│ bpmn-js Viewer + Modeler │
│ BPMN XML sinh deterministic từ DSL │
│ VIEW ONLY — không phải SSOT │
├─────────────────────────────────────────────────────────┤
│ TẦNG 3 — DSL + BLOCK LIBRARY (✅ Phase 2A XONG) │
│ workflow_steps + workflow_step_relations = SSOT │
│ block_library = template blocks tái sử dụng │
│ DSL → deterministic mapping → BPMN XML │
├─────────────────────────────────────────────────────────┤
│ TẦNG 2 — GOVERNANCE (Phase 2B — đang xây) │
│ workflow_change_requests (intake) │
│ M-001 CommentModule = phòng thảo luận │
│ WCR → task → AI Council → approve → apply DSL │
├─────────────────────────────────────────────────────────┤
│ TẦNG 1 — EXECUTION (Phase 3 — sau) │
│ DSL → Adapter → Prefect/Kestra │
└─────────────────────────────────────────────────────────┘
III. SCHEMA — Collections
3.1 workflows (đã có + mở rộng)
| Field | Type | Mô tả |
|---|---|---|
| id | PK | Auto |
| title | string | Tên quy trình |
| description | text | Mô tả ngắn |
| narrative | text/rich-text | MÔ TẢ BẰNG NGÔN NGỮ TỰ NHIÊN — SSOT đầu tiên, con người viết/đọc (§XI) |
| process_code | string unique | Mã quy trình: WF-001, WF-002... |
| sort | integer | STT hiển thị |
| parent_workflow_id | FK → workflows | Phân cấp cha (self-referencing) |
| level | integer | Cấp: 1=Cấp 1 (root/cao nhất), 2=Cấp 2, 3=Cấp 3 (leaf/thấp nhất). Max=3 |
| status | enum | draft, active, deprecated |
| bpmn_xml | text | BPMN XML cache (sinh từ DSL, không phải SSOT) |
Phân cấp 3 cấp:
WF-001 Quy trình tổng (level=1, parent=null) ← CẤP 1
├─ WF-001-A Nhóm con A (level=2, parent=WF-001) ← CẤP 2
│ ├─ WF-001-A1 Chi tiết A1 (level=3) ← CẤP 3
│ └─ WF-001-A2 Chi tiết A2 (level=3) ← CẤP 3
└─ WF-001-B Nhóm con B (level=2, parent=WF-001) ← CẤP 2
Mỗi quy trình được gán Cấp 3 → system tự xác định Cấp 2/1 qua parent_workflow_id.
Enforce max 3 cấp: Directus Flow reject nếu parent đã level=3.
3.2 workflow_steps (đã có + mở rộng)
| Field | Type | Mô tả |
|---|---|---|
| id | PK | Auto |
| workflow_id | FK → workflows | Thuộc workflow nào |
| step_key | string | Unique key trong workflow |
| step_type | enum | action, agent_call, condition, wait_for_event, human_checkpoint, loop, parallel |
| title | string | Tên hiển thị |
| description | text | Mô tả chi tiết |
| actor_type | enum | user, claude_ai, claude_code, gemini, gpt, system, orchestrator, codex |
| config | json | Cấu hình theo step_type |
| position_x / position_y | float | Vị trí diagram |
| trigger_in_text | text | Trigger vào — text cho người đọc |
| trigger_out_text | text | Trigger ra — text cho người đọc |
| sort_order | integer | Thứ tự |
| block_id | FK → block_library | Nếu tạo từ block template |
3.3 workflow_step_relations (đã có)
| Field | Type | Mô tả |
|---|---|---|
| from_step_id / to_step_id | FK → workflow_steps | Bước nguồn → đích |
| relation_type | enum | sequence, conditional, parallel_fork, parallel_join, loop_back |
| condition_expression | string | Điều kiện rẽ nhánh |
| label | string | Nhãn mũi tên |
3.4 block_library (đã có)
Template blocks tái sử dụng: ai_review_block, code_review_loop, approval_with_retry, agent_dispatch_block, planning_council.
3.5 workflow_change_requests — WCR (đã có)
| Field | Type | Mô tả |
|---|---|---|
| workflow_id | FK → workflows | Workflow thay đổi |
| change_type | enum | add_step, modify_step, remove_step, reorder, add_block, restructure |
| description | text | Mô tả tự nhiên từ User |
| status | enum | draft → ai_reviewing → approved → applied |
| task_id | FK → tasks | Liên kết M-001 CommentModule |
| schema_warnings | json | Kết quả Integrity Scan |
| dsl_diff | json | Preview thay đổi DSL |
3.6 DSL → BPMN Mapping (Deterministic)
step_type → BPMN element
────────────────────────────────────────
action → bpmn:Task
agent_call → bpmn:ServiceTask
condition → bpmn:ExclusiveGateway
wait_for_event → bpmn:IntermediateCatchEvent
human_checkpoint → bpmn:UserTask
loop → bpmn:ExclusiveGateway + loop arrow
parallel → bpmn:ParallelGateway
workflow_step_relations → bpmn:SequenceFlow
IV. LỘ TRÌNH TRIỂN KHAI
Phase 2A — Foundation (✅ HOÀN THÀNH — S100/S101)
| # | Việc | Trạng thái |
|---|---|---|
| 1-8 | DSL engine: 4 collections, blocks, generator, WCR, integrity scan, migrate WF-1 | ✅ DONE (Codex) |
| 9-10 | Schema mở rộng: process_code, sort, level, parent, trigger texts | ✅ DONE |
| 11-17 | Supervisor UI: Workflows nav + list + detail + 3 tabs + WCR permissions | ✅ DONE (PR #426/430/431) |
Còn lại (Polish — TD-064):
| # | Việc | Trạng thái |
|---|---|---|
| P1 | BPMN layout: dọc (top→bottom) + spacing đủ rộng | 🔴 TD-064 |
| P2 | Tab active state: màu đổi rõ khi chuyển tab | 🔴 TD-064 |
| P3 | Đổi "Bảng bước" → "Trình tự" trong UI + docs | 🟡 TO-DO |
| P4 | Tester module: verify dot-spider + tích hợp Mũ 2 | 🟡 TD-065 |
Phase 2B — Text-First Governance (Phase 2B — CẦN CODE)
Xây dựng luồng §XI: Narrative → AI Council → Approve → Tạo Trình tự.
| # | Việc | Agent | Output |
|---|---|---|---|
| 1 | Thêm field narrative vào workflows (DOT) |
Codex | 1 field mới |
| 2 | Tab "Mô tả" hiển thị narrative + CommentModule | Codex | Tab mới |
| 3 | WCR auto-create task → link CommentModule | Codex | Directus Flow |
| 4 | AI extract narrative → đề xuất steps (AI draft) | Claude Code | Composable mới |
Phase 2C — BPMN Nâng cao
Overlays realtime, highlight path, color theo actor, auto-zoom, export SVG/PNG.
Phase 3 — Execution (SAU Phase 2)
DSL → Prefect Adapter → Agent dispatch runtime.
V. SUPERVISOR UI — GIAO DIỆN NGƯỜI GIÁM SÁT
5.1 Layout tab trang detail
┌────────────────────────────────────────────────────────┐
│ [Mô tả] [Trình tự] [Sơ đồ BPMN] [Đề xuất thay đổi] │
├────────────────────────────────────────────────────────┤
│ Tab "Mô tả": Narrative text + AI Council comments│
│ Tab "Trình tự": WorkflowMatrixView (step table) │
│ Tab "Sơ đồ": WorkflowViewer (BPMN, từ DSL) │
│ Tab "Đề xuất": WcrIntakePanel (form WCR) │
└────────────────────────────────────────────────────────┘
5.2 Bảng danh sách (Process Registry)
| STT | Mã QT | Tên quy trình | Cấp | Số bước | Trạng thái |
|---|---|---|---|---|---|
| 1 | WF-001 | Quy trình tổng A | Cấp 1 | 10 | Active |
| 2 | WF-001-A | Nhóm con A | Cấp 2 | 5 | Active |
- Pagination 25 items/page, search, filter theo status/level
- Hiển thị cây phân cấp (indent theo level)
5.3 Trình tự (Step Matrix — đổi từ "Bảng bước")
| STT | Mã bước | Tên bước | Trigger vào | Trigger ra | Mô tả | Trạng thái |
|---|---|---|---|---|---|---|
| 1 | WF-001-S01 | Tiếp nhận | Khách ký HĐ | → Bước 2,3 | Nhận hồ sơ... | Pending |
VI. NGUYÊN TẮC BẤT DI BẤT DỊCH
- Directus = DOT 100% — Mọi schema qua DOT tools
- DSL = SSOT — BPMN chỉ là view. AI đọc DSL.
- Narrative = SSOT đầu tiên — Text-First, con người đọc được (§XI)
- Assembly First — Directus native → Module có sẵn → Code mới
- Governance bắt buộc — Mọi thay đổi qua WCR → task → AI Council → approve
- Deterministic mapping — DSL → BPMN không có suy diễn
VII. QUAN HỆ HỆ THỐNG
| Hệ thống | Vai trò trong M-002 |
|---|---|
| M-001 CommentModule | Phòng họp governance cho WCR + Narrative review |
| task_checkpoints | L0/L1/L2 verify cho workflow changes |
| Agent Data KB | SSOT docs, báo cáo, kế hoạch |
| Prefect (Phase 3) | Executor DSL |
VIII. CÂU HỎI ĐÃ TRẢ LỜI
| # | Câu hỏi | Quyết định |
|---|---|---|
| 1 | BPMN hay DSL là SSOT? | DSL = SSOT. BPMN sinh từ DSL. |
| 2 | Block Library trước DSL? | CÓ — seed 5 blocks trước |
| 3 | Event-driven ngay v1? | Schema CÓ, triển khai Phase 3 |
| 4 | Narrative → Steps: AI hay DOT? | Option C: AI phân tích → AI review → DOT apply (Phase 2B) |
| 5 | WCR là gì về mặt tổ chức? | Mỗi WCR = 1 task mới → AI Council bàn thảo → approve |
XI. TEXT-FIRST GOVERNANCE — 4 ĐIỂM MÙ KIẾN TRÚC (MỚI v1.5 — S102)
Nguồn: Phân tích S102 sau khi xem UI thực tế. 4 điểm này phải giải quyết trước Phase 2B.
11.1 NARRATIVE — Tầng SSOT Đầu Tiên (chưa có)
Vấn đề: Hiện tại quy trình bắt đầu từ "Trình tự" (workflow_steps). Thiếu tầng mô tả bằng ngôn ngữ tự nhiên — thứ con người đọc và AI phân tích.
Giải pháp: Thêm field narrative vào collection workflows:
- Người dùng/AI soạn mô tả tự nhiên (dạng paragraph)
- AI Council comment bên dưới (M-001 CommentModule lắp vào)
- Đây là điểm khởi thuỷ logic — mọi sửa đổi bắt đầu từ Narrative, không phải từ Trình tự
- UI: Tab "Mô tả" là tab ĐẦU TIÊN, trước tab "Trình tự"
11.2 WCR LOOP — Mỗi Thay Đổi = 1 Task Mới (chưa đúng)
Vấn đề: WCR hiện tại chỉ là form, chưa liên kết chặt với M-001 task system.
Giải pháp — Luồng đúng:
User/AI đề xuất thay đổi Narrative
↓ Tạo WCR → Directus Flow auto-tạo task mới
↓ CommentModule trong task đó = AI Council bàn thảo
↓ Admin duyệt task → WCR approved → cập nhật Narrative
↓ Từ Narrative mới → tự động/manual cập nhật Trình tự
↓ Regenerate BPMN
Nguyên tắc: 1 quy trình sửa 100 lần = 100 tasks. Mỗi task = 1 vòng thảo luận độc lập. Không sửa trực tiếp vào Trình tự — MỌI thay đổi đều qua WCR → task → approve.
11.3 NARRATIVE → TRÌNH TỰ — Cơ Chế Chuyển Đổi (chưa có)
Vấn đề: Khi Narrative được duyệt → ai/cái gì tạo ra Trình tự? Cơ chế chưa được code.
Quyết định — Option C (đã chốt):
Bước 1: AI-A (Claude Code / GPT) phân tích Narrative text
→ đề xuất danh sách workflow_steps dạng JSON draft
Bước 2: AI-B (agent review độc lập) đọc draft + Narrative
→ xác nhận / phản biện / bổ sung
Bước 3: Admin xem draft steps trong tab "Trình tự"
→ approve (click) → DOT apply steps vào Directus
Trách nhiệm rõ ràng:
| Vai trò | Trách nhiệm | Tool |
|---|---|---|
| User/Admin | Viết Narrative text tự nhiên | UI tab "Mô tả" |
| AI-A (Analyst) | Phân tích Narrative → draft JSON steps | Claude API / composable |
| AI-B (Reviewer) | Review draft → feedback | CommentModule task |
| Admin | Approve draft → confirm | UI button "Áp dụng trình tự" |
| System | DOT apply steps + auto-number sort_order | dot-schema-* + Flow |
Tại sao không DOT script thuần? Narrative là text tự nhiên, không tiêu chuẩn → AI phải trích xuất. Script chỉ tin cậy khi data đã có cấu trúc cố định.
Cần code trong Phase 2B:
- Field
narrativetrong collectionworkflows(DOT) - Composable
useNarrativeToSteps: gọi Claude API → parse JSON steps draft - UI review draft + approve button
- DOT apply khi approved + auto-assign sort_order theo thứ tự
11.4 AUTO-TEST — Phát Hiện Lỗi UI Lặt Vặt (chưa đủ)
Vấn đề: Tab không đổi màu khi active — loại bug nhỏ nhưng lặp lại nhiều lần. Auto-test hiện tại chỉ check routes 200, không check UI state.
Giải pháp — Thêm vào Tester Module checklist:
- Tab active state: kiểm tra class CSS thay đổi khi click tab
- Button click response: click → verify visual feedback (loading state, color change)
- Form submit feedback: submit → verify thành công/thất bại indicator
- Empty state display: collection rỗng → verify không blank/crash
→ Xem TD-065 (Tester Module) + TD-064 (BPMN + tab fix).
Bản này thay thế: architecture.md (v1-draft), governance-update-proposal, GPT v3 owner-draft.