Điều 34: Luật Workflow — Draft v1.0
ĐIỀU 34: LUẬT WORKFLOW — Draft v1.0
v1.0 | S145 | Huyên chỉ đạo. Chờ hội đồng AI review. Tầm nhìn: 10.000+ workflows. Lắp ráp 100%, không làm tay. Mỗi WF = hợp chất (Điều 0-B Lớp 3).
§1. MỤC ĐÍCH
Workflow (WF) là đơn vị quản lý quy trình của toàn bộ hệ thống Incomex. Mọi nghiệp vụ — từ duyệt công việc đến xử lý đơn hàng xuất khẩu 60 bước — đều được biểu diễn, quản lý, và thực thi dưới dạng WF.
Điều 34 quy định khung kiến trúc, quy trình vận hành, và công cụ cho hệ thống WF, với tầm nhìn 10.000+ workflows quản lý đồng thời mà KHÔNG loạn.
§2. NGUYÊN TẮC CỐT LÕI
§2.1 Lắp ráp 100% — KHÔNG làm tay
Mọi WF được LẮP RÁP từ các thành phần chuẩn (viên gạch). Thêm WF mới = gọi DOT commands. Sửa WF = tạo WCR (đề xuất thay đổi) → duyệt → DOT apply. KHÔNG edit SQL trực tiếp, KHÔNG sửa BPMN XML bằng tay.
§2.2 Nguyên tắc vàng
"Thiết kế hệ thống để CHẠY. Khi đã chạy, KHÔNG SỬA CODE. Thay đổi kinh doanh = thay đổi metadata/config. Đi sửa code = thiết kế tồi."
§2.3 WF = Hợp chất (Điều 0-B Lớp 3)
WF chứa phân tử (blocks) + nguyên tử (nodes) + CÓ quy trình/logic điều phối. WF kết nối xuống atoms (checkpoints, DOT tools) qua PG FK/M2M, và sẵn sàng đấu nối lên lớp cao hơn (Vật liệu = bộ WF chuẩn, Sản phẩm = WF đang chạy, Công trình = mảng kinh doanh).
§2.4 Tư duy 10.000
Thiết kế MỌI thứ cho quy mô 10.000 WF ngay từ đầu. Phân loại phân cấp, version, reusable blocks, governance. "Nhìn số nhỏ → tư duy nhỏ → đập đi làm lại."
§2.5 DOT 100%
Mọi thao tác WF (tạo, sửa, xóa, nối, mở rộng) qua DOT tool. Không curl, không directus_create_item trực tiếp.
§3. MÔ HÌNH — 4 TẦNG LẮP RÁP
Tầng 1: Viên gạch (Atom — Node Types)
Mỗi node trong WF thuộc 1 loại chuẩn. Danh mục node types tuân thủ BPMN 2.0:
| Nhóm | Loại node | step_type | Mô tả | Status |
|---|---|---|---|---|
| Events | Start Event | start_event |
Bắt đầu quy trình | 🔴 Cần |
| End Event | end_event |
Kết thúc quy trình | 🔴 Cần | |
| Timer Event | timer_event |
Chờ thời gian | 🟡 Sau | |
| Signal/Message | message_event |
Nhận tín hiệu từ bên ngoài | 🟡 Sau | |
| Wait Event | wait_for_event |
Chờ sự kiện | ✅ Có | |
| Tasks | User Task | human_checkpoint |
Người thực hiện | ✅ Có |
| Service Task | agent_call |
AI/hệ thống tự chạy | ✅ Có | |
| Script Task | script_task |
Script/code chạy | 🟡 Sau | |
| Manual Task | manual_task |
Việc làm ngoài hệ thống | 🟡 Sau | |
| Gateways | Exclusive (XOR) | condition |
Rẽ nhánh Yes/No | ✅ Có |
| Parallel (AND) | parallel_gateway |
Chạy song song | 🟡 Sau | |
| Inclusive (OR) | inclusive_gateway |
Rẽ nhiều nhánh | 🟡 Sau | |
| Actions | Action | action |
Hành động đơn | ✅ Có |
Hiện có: 5 loại (wait_for_event, human_checkpoint, agent_call, condition, action). Cần ngay cho WF đầu tiên: +start_event, +end_event = 7 loại. Mở rộng sau: timer, message, script, manual, parallel, inclusive = 12 loại.
Lưu trữ: Danh mục node types trong PG table workflow_node_types (hoặc dùng CHECK constraint + metadata). Thêm loại mới = INSERT 1 dòng, KHÔNG sửa code.
Tầng 2: Mảng tường (Molecule — Blocks)
Block = nhóm nodes + relations lắp sẵn, tái sử dụng. Lưu trong block_library.
Ví dụ blocks cần:
| Block | Mô tả | Nodes | Dùng trong |
|---|---|---|---|
| basic-approval | Duyệt đơn giản (submit → review → approve/reject) | 4-5 nodes | Hàng trăm WF |
| approval-3-level | Duyệt 3 cấp (nhân viên → quản lý → giám đốc) | 10-12 nodes | Quy trình lớn |
| ai-review | AI kiểm tra + human override | 3-4 nodes | WF có AI |
| basic-sequence | Chuỗi N bước tuần tự | N nodes | Mọi WF |
| loop-retry | Lặp lại khi thất bại (max N lần) | 3-4 nodes | Error handling |
Mục tiêu: ~50-100 blocks → lắp được 10.000 WF. Giống Lego: ít loại gạch, nhiều công trình.
Tầng 3: Ngôi nhà (Compound — Workflow)
1 WF = lắp từ blocks + nodes rời. Mỗi WF có:
process_code: WF-NNN (unique, auto-generated)version: tăng mỗi lần sửalevel: 1-3 (hierarchy)category_id: phân loại 3 cấpbpmn_xml: tự generate từ steps + relations (KHÔNG viết tay)status: draft → active → deprecated → retired
Tầng 4: Khu phố (Material — WF Template Sets) — TƯƠNG LAI
Nhóm WF chuẩn cho 1 nghiệp vụ. Ví dụ: "Bộ WF Xuất khẩu" = 8 WF liên kết. Chưa xây, nhưng kiến trúc sẵn sàng đấu nối.
§4. QUY TRÌNH KHÉP KÍN
§4.1 Tạo WF mới
User quyết định → DOT: dot-workflow-create
→ PG: INSERT workflows (auto WF-NNN + birth_registry)
→ Directus: sync
→ Nuxt: hiện trên UI
§4.2 Thêm bước (viên gạch)
DOT: dot-workflow-add-step --wf=WF-003 --type=user_task --title="..." --after=ND-0012
→ PG: INSERT workflow_steps (auto ND-NNNN + birth_registry)
→ PG: INSERT workflow_step_relations (nối với bước trước/sau)
→ DOT: dot-workflow-regenerate-bpmn --wf=WF-003
§4.3 Lắp block (mảng tường)
DOT: dot-workflow-expand-block --wf=WF-003 --block="approval-3-level" --after=ND-0012
→ PG: INSERT N workflow_steps (tất cả từ block template)
→ PG: INSERT M workflow_step_relations
→ PG: Nối block vào WF tại vị trí chỉ định
→ DOT: regenerate BPMN
§4.4 Sửa đổi (qua WCR)
DOT: dot-wcr-create --wf=WF-003 --change="thêm bước kiểm tra hàng sau bước 5"
→ PG: INSERT workflow_change_requests (auto WCR-NNN)
→ Review: User/AI duyệt
→ DOT: dot-wcr-apply --wcr=WCR-001
→ PG: Apply changes + version++
→ DOT: regenerate BPMN
§4.5 Xóa/Retire bước
DOT: dot-workflow-remove-step --wf=WF-003 --step=ND-0015
→ PG: UPDATE status='retired' (KHÔNG DELETE — Amidan)
→ PG: Cập nhật relations (bỏ edges liên quan)
→ DOT: regenerate BPMN
§5. CÔNG CỤ CẦN (DOT TOOLS)
Ưu tiên 1 — Cần cho WF đầu tiên lắp ráp:
| DOT Tool | Mô tả | Status |
|---|---|---|
dot-workflow-create |
Tạo WF mới (trống hoặc từ template) | 🔴 Cần |
dot-workflow-add-step |
Thêm 1 node vào WF | 🔴 Cần |
dot-workflow-connect |
Nối 2 nodes (relation) | 🔴 Cần |
dot-workflow-validate |
Kiểm tra WF hợp lệ (có start/end, không dead-end) | 🔴 Cần |
dot-workflow-regenerate-bpmn |
Tự sinh BPMN XML từ steps+relations | 🔴 Cần |
Ưu tiên 2 — Hoàn thiện:
| DOT Tool | Mô tả | Status |
|---|---|---|
dot-workflow-remove-step |
Retire 1 node | 🟡 |
dot-workflow-expand-block |
Lắp block từ thư viện | 🟡 |
dot-wcr-create |
Tạo đề xuất thay đổi | 🟡 |
dot-wcr-apply |
Áp dụng thay đổi đã duyệt | 🟡 |
dot-workflow-clone |
Clone WF để tạo phiên bản mới | 🟡 |
Ưu tiên 3 — Scale:
| DOT Tool | Mô tả | Status |
|---|---|---|
dot-block-create |
Tạo block mới trong thư viện | 🔵 |
dot-block-export |
Export block từ WF đang có | 🔵 |
dot-workflow-diff |
So sánh 2 versions | 🔵 |
dot-workflow-migrate |
Nâng cấp WF khi block thay đổi | 🔵 |
§6. MÔI TRƯỜNG THỰC THI
Collections đã có:
| Collection | Vai trò | Data |
|---|---|---|
workflows |
WF chính | 2 WFs (WF-001 active, WF-002 draft) |
workflow_steps |
Nodes/bước | 10 nodes WF-001 |
workflow_step_relations |
Edges/nối | 10 relations WF-001 |
workflow_change_requests |
Đề xuất sửa đổi | Schema có, 0 data |
workflow_categories |
Phân loại 3 cấp | Có |
block_library |
Thư viện blocks | Schema có, 0 blocks |
Collections cần thêm (hoặc mở rộng):
| Cần | Mô tả | Cách |
|---|---|---|
workflow_node_types |
Danh mục loại node chuẩn BPMN | PG table mới hoặc PG CHECK + seed data |
Mở rộng step_type |
Từ 5 → 7 (ngay) → 12 (sau) | ALTER CHECK constraint hoặc metadata table |
PG Features đã có:
- FK: workflow_steps.workflow_id → workflows.id
- FK: workflow_step_relations.from_step_id/to_step_id → workflow_steps.id
- Birth triggers: workflows (WF-NNN) + workflow_steps (ND-NNNN)
- birth_registry tracking
PG Features cần:
- Trigger regenerate bpmn_xml khi steps/relations thay đổi (hoặc DOT tool gọi)
- Validation function: check WF có start + end, không có dead-end nodes
§7. PHÂN LOẠI — KHÔNG LOẠN 10.000 WF
3 trụ chống loạn:
Trụ 1: Phân cấp 3 tầng (workflow_categories)
Cấp 1: Mảng kinh doanh (Xuất khẩu, Nội bộ, Tài chính, HR...)
Cấp 2: Nhóm nghiệp vụ (Đơn hàng, Kiểm hàng, Vận chuyển...)
Cấp 3: Loại WF (Đơn hàng mới, Đơn hàng sửa, Đơn hàng hủy...)
10.000 WF / 3 cấp = mỗi nhóm con ~50-100 WF. Quản lý được.
Trụ 2: Version + WCR governance
- Mỗi thay đổi = version mới. Rollback = quay version cũ.
- Mọi sửa đổi qua WCR → duyệt → apply. Không ai sửa tự do.
Trụ 3: Block library tái sử dụng
- ~50-100 blocks → lắp 10.000 WF. Sửa 1 block = cập nhật N WF dùng block đó.
- Block = đơn vị tái sử dụng quan trọng nhất. "Có ÍT vật liệu mà xây NHIỀU công trình."
§8. VÒNG ĐỜI WORKFLOW
draft → active → deprecated → retired
│ │ │ │
│ │ │ └─ Lưu trữ, không chạy, không hiện UI chính
│ │ └─ Đánh dấu sắp thay thế, vẫn chạy, cảnh báo
│ └─ Đang sử dụng, chạy production
└─ Đang thiết kế, chưa publish
Tuân thủ Điều 27 (Lifecycle Law) nếu có.
§9. KẾT NỐI VỚI CÁC ĐIỀU LUẬT KHÁC
| Điều | Liên quan | Vai trò |
|---|---|---|
| Điều 0 | Nhận diện | Mọi WF có WF-NNN, mọi node có ND-NNNN |
| Điều 0-B | Phân tầng | WF = Hợp chất (Lớp 3). Node = Nguyên tử (Lớp 1). Block = Phân tử (Lớp 2) |
| Điều 21 | 6 quan hệ | WF hiện đầy đủ: thuộc ai, chứa gì (nodes), dùng ai (checkpoints), ai dùng tôi, cùng nhóm, tương tự |
| Điều 23 | DOT Scanning | DOT tools cho WF phải register, scanner phải cover |
| Điều 26 | Registries | WF đếm qua pivot_count(), hiện trên Registries |
| Điều 31 | Integrity | Scanner verify WF có start+end, không dead-end |
| Điều 32 | Phê duyệt | WCR qua approval flow. Sửa WF = phê duyệt |
| Điều 33 | PG Law | WF tables tuân thủ naming, constraints, automation |
§10. LỘ TRÌNH TRIỂN KHAI
Phase 0 — LUẬT + HOẠCH ĐỊNH (hiện tại)
- ✅ Soạn Điều 34 draft v1.0
- ⬜ Hội đồng AI review
- ⬜ Huyên phê duyệt
Phase 1 — DÙNG TAY + HOÀN THIỆN PIVOT (ngắn hạn)
- User điều hành WF bằng tay (comment, prompt copy-paste)
- Quay lại hoàn thiện Pivot (M4 cross-table, TD-398~402)
- Hoàn thiện các nợ kỹ thuật đang dở
Phase 2 — CÔNG CỤ CƠ BẢN (trung hạn)
- 5 DOT tools ưu tiên 1 (create, add-step, connect, validate, regenerate-bpmn)
- Mở rộng step_type (5 → 7 → 12)
- Populate block_library (3-5 blocks đầu)
- workflow_node_types table
Phase 3 — LẮP RÁP TỰ ĐỘNG (dài hạn)
- 5 DOT tools ưu tiên 2 (remove, expand-block, wcr-create, wcr-apply, clone)
- WF đầu tiên lắp ráp hoàn toàn bằng DOT
- Block library mở rộng (~50 blocks)
Phase 4 — SCALE (tương lai)
- DOT tools ưu tiên 3 (block-create, export, diff, migrate)
- 100+ WFs production
- Kết nối lớp Vật liệu → Sản phẩm → Công trình
Điều 34 v1.0 | S145 | Tầm nhìn: 10.000 WF, lắp ráp 100%, BPMN 2.0, DOT 100% "Mặc dù mới làm 1 WF đầu tiên, nhưng thiết kế cho 10.000" — Huyên