Workflow Module (M-002) — Planning Hub

Module ID: M-002 Cập nhật: 2026-03-04 S103 — BỎ BPMN, chuyển Tailwind Steps Timeline + Checkpoint integration Lead: claude_ai | Critic: gemini

Tầm nhìn

M-002 là hệ điều hành quy trình cho AI Council — không phải workflow builder. Quy trình tạo nhanh hơn viết code. Bấm là chạy. Hàng ngàn flow mà không hỗn loạn.

Tầm nhìn S103 — Steps Timeline ↔ Checkpoint Integration: Mỗi quy trình có danh sách bước (workflow_steps). Mỗi bước có trạng thái tiến trình (checkpoint). Timeline dọc hiển thị TRỰC QUAN cho con người: đang ở đâu, đã làm gì, chưa làm gì, việc tiếp theo. Hệ thống tự cập nhật trạng thái từng bước khi checkpoint thay đổi — không cần thao tác thủ công.

Luồng dữ liệu:

workflow_steps (DSL/SSOT) → Tailwind Steps Timeline (hiển thị)
                          ↕
task_checkpoints (trạng thái) → cập nhật step status tự động

Khi checkpoint bước N = completed → Timeline tự hiển thị bước N xong, bước N+1 là current. Đây là nền tảng để quản lý tiến trình MỌI quy trình trong hệ thống.

Kiến trúc 4 Tầng

Tầng	Vai trò	Trạng thái
4 — Visualization	Tailwind Steps Timeline dọc + Checkpoint status	🔄 Phase: DROP-BPMN → rồi tích hợp checkpoint
3 — DSL + Blocks	workflow_steps, block_library = SSOT	✅ Phase 2A DONE
2 — Governance	WCR intake, Schema Scan, Admin approve	✅ Phase 2A DONE
1 — Execution	DSL → Prefect Adapter	📋 Phase 3

Lộ trình Phase 2B — Governance UX + Visualization

Bước	Mục tiêu	Trạng thái
1	Bỏ BPMN, lắp Tailwind Steps Timeline dọc	✅ DONE (PR #435)
2	UI Polish: scroll/auto-position/accordion/tỉ lệ vàng	✅ DONE (PR #436)
3	Narrative CTA + CommentModule lắp Hội đồng AI + ApprovalWidget	⚠️ Code merged (PR #437) nhưng UI chưa đúng thiết kế
4	Inline WCR (dấu + hàng/cột + proposal popup)	⚠️ Code merged (PR #439/#440) nhưng lỗi trên production
5	TABLE-ASSEMBLY: Chuyển TẤT CẢ tables sang Nuxt UI UTable	📋 ĐANG LÀM — giải quyết tận gốc bước 3+4
6	TIMELINE-ASSEMBLY: Chuyển StepsTimeline sang Nuxt UI UTimeline/UStepper	📋 Điều tra trong TABLE-ASSEMBLY
7	Nested Checkpoints: expand step → checkpoints con + sub-process	📋 SAU bước 5+6 — dùng UTable expanded rows
8	Checkpoint ↔ Timeline sync thực sự	📋 SAU bước 7
9	CommentModule liên thông — AI Council review từng bước	📋 SAU
10	Đa tầng view: lãnh đạo (rút gọn), thực thi (chi tiết), khách hàng (tổng quan)	📋 SAU

Thiết kế: Narrative → Trình tự (S103 — LỖ HỔNG CẦN FIX)

Vấn đề: Tab "Mô tả" có field narrative nhưng KHÔNG CÓ cơ chế chuyển narrative → workflow_steps. Trình tự hiện tại tạo độc lập, không liên kết với mô tả. Sửa mô tả không ảnh hưởng trình tự.

Thiết kế đúng:

Mô tả (narrative text) = NGUỒN GỐC
    ↓ (AI hoặc User rút ra)
Trình tự (workflow_steps) = DẪN XUẤT từ mô tả
    ↓
Timeline hiển thị = VIEW của trình tự

Luồng thay đổi:

User sửa Mô tả hoặc tạo WCR → hệ thống nhận biết narrative thay đổi
AI Council review narrative mới (CommentModule)
Approve → AI đề xuất cập nhật Trình tự tương ứng (hoặc User tự sửa)
Trình tự cập nhật → Timeline tự cập nhật

Giai đoạn 1 (hiện tại): Thêm CTA rõ ràng trong UI — "Tạo/Cập nhật trình tự từ mô tả" → liên kết 2 tab. Giai đoạn 2: AI tự phân tích narrative → đề xuất steps (cần API call). Giai đoạn 3: Auto-sync khi narrative thay đổi.

Kiến trúc Nested Process (S104 — NÂNG CẤP LỚN)

Vấn đề trước S104: Checkbox gộp vào step trên timeline (1 checkbox = 1 step). SAI — vì mỗi step có thể chứa hàng chục checkpoint con và nhiều quy trình con bên trong.

Kiến trúc đúng:

Quy trình chính
  └─ Step 1 (NODE LỚN trên timeline)
       ├─ Checkpoint 1.1 (đọc rules)
       ├─ Checkpoint 1.2 (lập kế hoạch)
       ├─ Sub-workflow 1.A (viết mã)
       │    ├─ CP 1.A.1 (trigger prompt)
       │    ├─ CP 1.A.2 (agent execute)
       │    └─ CP 1.A.3 (verify)
       └─ Checkpoint 1.3 (human approval)
  └─ Step 2
       └─ ...

Nguyên tắc:

Step = node LỚN. Checkpoint = node NHỎ bên trong step. Sub-process = workflow khác liên kết.
Timeline hiển thị STEPS (nodes lớn). Click step → expand checkpoints/sub-processes.
1 bộ dữ liệu duy nhất. Nhiều view: lãnh đạo (rút gọn), thực thi (chi tiết), khách hàng (tổng quan).
Actor-agnostic: AI và Human dùng cùng giao diện. Phân quyền = admin config.
Scale: Hoạt động cho 3 bước VÀ 300 bước. 0 checkpoint VÀ 50 checkpoint/step.

Schema bổ sung cần (Phase tiếp):

step_checkpoints: collection riêng cho checkpoints BÊN TRONG step (khác task_checkpoints cấp workflow)
step_sub_workflows: liên kết step → child workflow (quy trình con)
Hoặc mở rộng task_checkpoints thêm parent_step_id FK

Tầm nhìn 3 tầng:

Tầng 1 (hiện tại): Steps timeline + expand/collapse accordion
Tầng 2 (tiếp theo): Nested checkpoints bên trong mỗi step
Tầng 3 (sau): Sub-processes + đa tầng view cho từng đối tượng

Vấn đề: Checkpoint (L0/L1/L2) và Steps Timeline đang TÁCH RỜI. Bấm checkbox checkpoint không ảnh hưởng timeline.

Thiết kế:

Tích checkpoint → API update task_checkpoints → re-evaluate step status
Tất cả checkpoints của step PASS → step="completed". Đang xử lý → "current". Chưa có → "pending"
Timeline + Trình tự cập nhật real-time (reactivity)
Checkbox = HTML <input type="checkbox"> tiêu chuẩn, cả người và máy đều toggle
Actor-agnostic: giao diện giống nhau cho AI và Human. Phân quyền xử lý sau bằng admin config.

Cần schema: Kiểm tra task_checkpoints có workflow_step_id FK → workflow_steps không. Nếu chưa → thêm.

Thiết kế: Module tách nhỏ (S104)

CommentModule (đầy đủ) → lắp vào "Hội đồng AI" ApprovalWidget (nhỏ gọn, ~80px) → cuối trang, chỉ: trạng thái + nút phê duyệt + timestamp. Không comment stream.

Vấn đề: WCR hiện chỉ ở tab riêng, người dùng phải nhớ vị trí rồi mô tả.

Thiết kế mới: Dấu + giữa MỌI dòng trong bảng Trình tự + Timeline.

Bấm + → popup WCR tại vị trí đó (tự điền "Sau bước X")
Tạo xong → đề xuất hiển thị inline compact (1 hàng, không theo cột, dạng mô tả ngắn)
Áp dụng cho TẤT CẢ tabs: Trình tự, Tiến trình, Đề xuất thay đổi

Tài liệu

File	Nội dung	Trạng thái
`M-002-phase2-unified-plan.md`	KẾ HOẠCH CHÍNH THỨC Phase 2 — SSOT	✅ v1.5
`architecture.md`	Kiến trúc Phase 1 (bpmn-js — ĐÃ BỎ)	📦 Archive
`tech-evaluation.md`	So sánh bpmn-js vs alternatives — ĐÃ BỎ bpmn-js	📦 Archive
`discussions.md`	Lịch sử thảo luận	✅ (tham khảo)

Liên kết

Comment Module (M-001): search_knowledge("comment module planning")
Module Protocol: search_knowledge("module protocol standard")
Operating Rules: search_knowledge("operating rules SSOT")
Checkpoint System: search_knowledge("task checkpoints")
Table Module: search_knowledge("table module SSOT")