Design baseline · 28 SEP 2026 · 08 / 23

TDD · Process / Workflow Runtime

Process Definition chạy qua Workflow Instances; mỗi Workflow có một Role owner và task graph bền vững.

DESIGN DIAGRAMS · TARGET ARCHITECTURE 2.0

−Vừa khung+Mở toàn màn hình ↗Tải SVGNguồn

−Vừa khung+Mở toàn màn hình ↗Tải SVGNguồn

Hierarchy và aggregate state

Process Definition (versioned end-to-end template)
  └── Workflow Definitions (each has one owner Role)
      └── Task Definitions (DAG: branch / parallel / join / wait)

Business Case
  └── Process Instance (pins Process Definition version)
      └── Workflow Instances (each pins Workflow + Role version)
          └── Task Instances (executor, attempts, evidence, result)

Process Definition là cha nghiệp vụ, không phải một task graph khổng lồ. Nó định nghĩa các Workflow con, điều kiện start/handoff và policy end-to-end. Mỗi Workflow định nghĩa graph các Task và có đúng một Role owner. Process Instance tương quan với booking/lô hàng; một Message Event thường cập nhật case/instance và có thể start/resume một hay nhiều Workflow phù hợp.

Process Definition contract

Versioned document gồm: business type/key strategy; start/correlation rules; ordered/conditional child Workflow references; transition conditions; completion/exception policies; compatible versions. Nó không chứa prompt/model trực tiếp, tool code hoặc provider credentials.

{
  "processCode": "SHIPMENT_FULFILMENT",
  "version": 1,
  "correlation": {"businessType": "BOOKING", "keyFields": ["bookingNo"]},
  "workflows": [
    {"code": "CONT_SEAL_INSPECTION", "ownerRole": "FIELD_OPERATIONS"},
    {"code": "BOOKING_DOCUMENTS", "ownerRole": "DOCUMENTATION"},
    {"code": "FLEET_DISPATCH", "ownerRole": "FLEET_DISPATCH"},
    {"code": "PAYMENT_COLLECTION", "ownerRole": "FINANCE"}
  ]
}

Workflow / Task graph contract

Workflow Definition chứa một Role owner, start condition, task nodes, edges/outcomes, branch/join policy, timeout/retry, wait/review actions, output schema và completion criteria. Task Definition khai báo executor kind, input/output schema, capability grants, evidence needs và idempotency behavior. Hỗ trợ node start, task, condition, parallel fork/join, wait_input, human_review, handoff/complete. Không cho workflow node gọi arbitrary Java/SQL/script.

Execution algorithm

1. Claim eligible Workflow/Task Instance bằng DB row lock hoặc durable queue; gắn lease token, attempt và pinned versions.
2. Build task context theo tenant + Business Case + workflow + Role policy, evidence provenance và budget.
3. Chạy executor ngoài DB transaction (code/AI/human/connector); gọi tool qua broker.
4. Validate typed result, evidence, expected aggregate version và current lease token.
5. Trong một transaction, ghi task result, facts/audit, workflow state, branch/join progress và child tasks/outbox kế tiếp.
6. Worker mất lease không được commit. Side effect có idempotency/reconciliation; UNKNOWN không tự resend.

Role ownership và handoff

Một Workflow Instance chỉ có một Role owner. Các Task Instances trong workflow chạy dưới policy của Role đó. Khi cần chuyên môn khác, workflow kết thúc hoặc phát transition được Process Orchestrator duyệt để khởi chạy Workflow con tiếp theo trong cùng Process Instance; không cho Role gọi Role trực tiếp.

Parallel branches and joins

Task graph có thể fan-out nhiều nhánh trong cùng Workflow. Mỗi nhánh có key riêng và kết quả/idempotency riêng. Join node khai báo policy (all, any, quorum) và timeout path; không suy ra join chỉ từ thứ tự hoàn tất. Nếu một nhánh fail, workflow policy xác định retry, compensate, continue-with-review hoặc fail Process Instance.

Message attach, wait và review

Workflow có thể chờ message/input có correlation key + expiry. Incoming event chỉ resume đúng Workflow Instance nếu Business Case, tenant/thread và wait token match duy nhất. Human review pin evidence, candidate result và aggregate version; quyết định APPROVE/CORRECT vẫn chạy validator, stale version trả conflict.

Versioning and migration

• Process Definition, Workflow Definition, Role Definition và Task Definition có version độc lập.
• Process Instance pin Process Definition; mỗi Workflow Instance pin Workflow + Role; mỗi Task Instance pin Task/Executor version.
• Instance đang chạy tiếp tục theo snapshot cũ; explicit migration tạo audit, validate graph compatibility và CAS state.
• Role/Task binding hoặc tool permission đổi không hồi tố quyền cho task đang chạy.

Delivery and integration

Gửi Zalo/WeChat, Sheet, ERP hoặc payment là Task/connector side effect có command ID, destination/config snapshot, outbox state và receipt. ACCEPTED/SENT/UNKNOWN/FAILED là delivery state, tách khỏi business Process/Workflow completion. Payment/ERP writes cần idempotency hoặc reconciliation; compensation là workflow task có audit.

Current implementation boundary

Hiện DB có core_workflow_instances và core_tasks cho Cont/Seal; mỗi event đủ điều kiện tạo một OPS task xử lý album, sau đó một CUSTOMER_SERVICE child task gửi kết quả trong cùng legacy instance. Đây là ngoại lệ chuyển tiếp có hai Role trên một instance. Chưa có Process Definition aggregate chứa nhiều Workflow Instances, chưa có general Workflow DAG executor. Workflow Canvas hiện lưu/validate/simulate config. Master Orchestrator chưa được nối vào normal inbound. TDD này mô tả target runtime và không được đọc như feature đã triển khai.

TDD acceptance