Design baseline · 28 SEP 2026 · 02 / 23
High-level architecture
Process Definition → Workflow → Task · mô hình quy trình nghiệp vụ end-to-end.
HIGH-LEVEL ARCHITECTURE · TARGET MODEL
01 · Process Definition → Workflow → Task
Process Definition mô tả nghiệp vụ end-to-end. Mỗi Workflow con có một Role owner và nhiều Task có thể rẽ nhánh, chạy song song, hội tụ hoặc chờ. Process Instance gắn quy trình với booking/lô hàng cụ thể.
02 · Runtime hiện tại (để đối chiếu)
Đây là luồng code đang chạy: intake cố định theo media; Cont/Seal match workflow config theo session/group. Master Orchestrator và Workflow Canvas chưa nằm trong execution path.
03 · Deployment và ownership
Gateway sở hữu transport; Core sở hữu Process/Workflow/Task state và business decisions; PostgreSQL lưu state và audit; adapters gọi model và dịch vụ ngoài.
Phân biệt target với hiện trạng. Process Definition → nhiều Workflow → nhiều Task là mô hình kiến trúc đề xuất. Runtime hiện tại chưa có Process Orchestrator chung và chưa thực thi Workflow DAG production.
01Inbound eventGateway nhận notify từ channel, gom album, lưu inbox rồi chuyển canonical event vào Core.
02Context + correlationCore xác thực tenant/session/thread, lấy sender/group/config, business references và công việc đang mở.
03Process OrchestratorPhân loại intent, tìm hoặc tạo Business Case/Process Instance, chọn Workflow con cần bắt đầu/tiếp tục.
04Role-owned WorkflowMỗi Workflow có một Role owner; Workflow quyết định Task graph, nhánh, wait, review và handoff.
05Task executionTask chạy bằng code thường, AI skill hoặc human; quyền và schema được kiểm tra phía Core.
06Commit + integrationValidator cập nhật facts/state/audit atomically; outbox gọi channel, Sheet, ERP hoặc payment adapter.
Ranh giới module trong kiến trúc đích
| Thành phần | Sở hữu | Không tự quyết |
|---|---|---|
| TS channel gateway | Phiên kênh, gom media, inbox giao nhận, gửi outbound và receipt | Nghiệp vụ, role, quyền sửa shipment |
| Dashboard / BFF | Login, tenant scope, UI và proxy có xác thực | Tenant lấy từ payload client; credentials public |
| Quarkus core | Dispatcher, role runtime, orchestrator, validators, DB transactions | Để output model tự commit business state |
| Model adapter | Text/vision completion và structured parsing; capability-based model profile | Sở hữu task/flow state hoặc tạo đích gửi tùy ý |
| Integration adapters / MCP | Sheet read/write, provider API, schema validation và audit | Tự quyết scope hoặc role permission |
| PostgreSQL + evidence storage | Nguồn sự thật; durable jobs/outbox, object metadata, audit | Dùng chat history hoặc model memory thay cho facts |
Domain model và naming
| Khái niệm | Vai trò trong kiến trúc |
|---|---|
| Process Definition | Định nghĩa quy trình end-to-end, ví dụ xử lý lô hàng từ lập kế hoạch đến thu tiền. Nó chứa nhiều Workflow Definition. |
| Workflow Definition | Một quy trình con có ranh giới nghiệp vụ và đúng một Role owner. Nó chứa nhiều Task Definition với điều kiện, nhánh và điểm chờ. |
| Task Definition / Task Instance | Định nghĩa việc và một lần thực hiện cụ thể. Task có input/output schema, executor kind, retry/timeout và kết quả kiểm định. |
| Role | Trách nhiệm logistics thực tế như Field Operations, Documentation, Fleet Dispatch, Customer Service, Finance, Supervisor. Role sở hữu Workflow; không phải model/provider. |
| Business Case | Danh tính nghiệp vụ ổn định như booking/lô hàng, dùng để tương quan message và nhiều quy trình. |
| Process Instance | Một lần chạy Process Definition cho Business Case cụ thể; chứa các Workflow Instance và state tổng. |
| Workflow Instance | Một lần chạy Workflow con trong Process Instance; chứa Task Instances, task graph state và Role/version snapshot. |
| Message Event | Đầu vào hoặc bằng chứng cập nhật case; không mặc định tương đương một Task hay một Process Instance mới. |
Luồng xử lý mục tiêu
- Channel gửi notification/event tới Gateway. Gateway chuẩn hóa envelope, gom album, lưu inbox bền vững và chuyển event sang Core.
- Core xác thực scope, dedupe và persist event. Context Resolver lấy channel/session, tên nhóm, sender, config, media/text, case references và active work.
- Process Orchestrator xác định loại nghiệp vụ. Rule đã cấu hình được ưu tiên; AI hỗ trợ semantic routing khi cần. Nó tìm Business Case và Process Instance hiện hữu trước khi tạo mới.
- Orchestrator chọn Process Definition phù hợp, rồi bắt đầu/tiếp tục một hay nhiều Workflow con theo intent và trạng thái. Message có thể cập nhật nhiều workflow nếu chứa nhiều ý độc lập; không tạo workflow chỉ vì có message mới.
- Workflow có một Role owner và điều phối nhiều Task theo graph: tuần tự, song song, condition, join, wait hoặc human review. Handoff giữa Role diễn ra qua Workflow boundary.
- Task executor có thể là deterministic code, AI skill/model, human action hoặc connector. Role/workflow policy giới hạn quyền; AI đề xuất kết quả nhưng Core validate và commit.
- Kết quả được ghi cùng state, evidence, audit và outbox. Message/receipt sau đó có thể resume đúng Process/Workflow Instance theo correlation.
AI architecture: dùng AI ở đâu?
- Process Orchestrator: dùng model để phân loại intent hoặc resolve ambiguity nếu rule/context chưa đủ; output chỉ là routing proposal có schema.
- Workflow Runtime: không phải AI. Nó giữ state, điều kiện, retries, wait/review, idempotency và thực thi graph xác định.
- Task Role: cung cấp trách nhiệm, policy, context profile và capability. Role không tự gọi Role khác và không tự ghi business state.
- Task executor: gọi AI khi công việc cần đọc ảnh/văn bản hoặc tổng hợp; dùng code cho ISO/check/rules; dùng human cho duyệt ngoại lệ.
- AI Connector: cung cấp model routing/usage/cost telemetry; không sở hữu process/task state hay business workflow.
Ranh giới module
| Module | Sở hữu |
|---|---|
| Channel Gateway | Channel sessions, album/message normalization, durable inbox, outbound command và receipt. |
| Core Intake | Canonical event, tenant scope, dedupe, event persistence và inbox ACK. |
| Process Orchestrator | Intent routing, case correlation, Process Definition/Instance lifecycle, chọn workflow start/resume. |
| Workflow Runtime | Workflow graph state, Role owner, task scheduling, branch/join, wait/retry/review, version pinning. |
| Role & Task Catalog | Role responsibility/policy, Task schema/executor contract, workflow ownership và capability binding. |
| Task Executors | Vision/OCR, code rules, Sheet lookup, human approval, send result; không tự thay state machine. |
| State + evidence store | Business Case, process/workflow/task instances, facts có provenance, idempotency, audit và outbox. |
| AI Connector & Stats | Model providers, model routing theo policy, usage/quota/cost logs và thống kê. Không sở hữu Workflow/Task state hoặc business routing. |
| Business Connectors | Sheet/MCP/ERP/channel/payment adapters; quyền gọi do Task capability + Tool Broker kiểm tra, không nằm trong AI Connector. |
Hiện trạng runtime so với target
- Đang chạy: Gateway nhận/lưu inbox và POST event vào Core; Core lưu event rồi route ảnh Cont/Seal theo workflow config khớp session/nhóm nguồn, hoặc route text vào processor riêng.
- Cont/Seal hiện tại: một task OPS chạy image job chuyên biệt cho album, sau đó một CUSTOMER_SERVICE child task gửi kết quả trong cùng legacy workflow instance. Đây là hai Role trên một instance, không theo ranh giới target mỗi Workflow một Role. Chưa có Process Definition/Business Case aggregate chung.
- Chưa nối vào inbound: Master Orchestrator API chỉ phân loại/lưu event, chưa dispatch workflow/task; normal Zalo inbound không gọi nó.
- Canvas: lưu/validate cấu hình và dry-run; không thực thi graph node trong production. Runtime chọn group/source/result config chứ chưa chạy workflow tổng quát.
- UI hiện tại: chưa có Role catalog/admin; đang cấu hình Cont/Seal theo phiên Zalo và các phần Booking Sheet/Data.
Nguyên tắc triển khai
- Định danh Business Case/correlation trước khi tạo Process Instance; tránh mỗi message tạo một case mới.
- Process Definition và Workflow Definition version hóa độc lập; running instances pin snapshot.
- Mỗi Workflow có một Role owner. Cross-role handoff được mô hình thành workflow khác trong cùng Process Definition, không giao Role gọi chéo.
- Task graph hỗ trợ fan-out/fan-in; khai báo join policy, timeout và failure path rõ ràng.
- Outbox/integration side effect chạy idempotent/reconcilable; unknown receipt không tự gửi lại.
- Triển khai modular monolith trước; chỉ tách worker/service khi tải hoặc ownership yêu cầu.
Liên quan: Intake & Process Routing · Role & Task · Process / Workflow Runtime · Vertical slice Cont/Seal.