Design baseline · 28 SEP 2026 · 07 / 23

TDD · Role & Task Runtime

Role đại diện cho trách nhiệm logistics. Mỗi Workflow có một Role owner; Role chịu trách nhiệm cho các task bên trong workflow.

DESIGN DIAGRAMS · TARGET ARCHITECTURE 2.0

Mô hình · Workflow owner, role boundary và task graph. Một Workflow thuộc đúng một Role và chứa task graph; đổi Role là workflow handoff do Process Orchestrator điều phối. — Mô hình · Workflow owner, role boundary và task graph
Một Workflow thuộc đúng một Role và chứa task graph; đổi Role là workflow handoff do Process Orchestrator điều phối.

Domain contract

Role Definition: trách nhiệm nghiệp vụ, phạm vi dữ liệu, policy, tools/capabilities được phép, SOP/context profile và fallback/human owner.
Workflow Definition: có đúng một ownerRoleCode; Role nhận quyền sở hữu kết quả/state transition của workflow.
Task Definition: đơn vị việc trong workflow; khai báo input/output schema, executor kind (CODE/AI/HUMAN/CONNECTOR), timeout, retry, evidence requirement.
Task Instance: trạng thái thực thi cụ thể, input reference, attempt/lease, output, provenance, validation và error.
Role không phải model: role không chứa vendor/model ID cố định. Task executor hoặc AI profile chọn capability/model qua AI Connector policy.

Ownership và phân công

Process Definition gom nhiều Workflow end-to-end. Mỗi child Workflow được sở hữu bởi một Role; trong workflow, nhiều task có thể chạy tuần tự/song song và đều nằm dưới trách nhiệm Role đó. Khi nghiệp vụ cần Role khác, Workflow kết thúc/handoff để Process Orchestrator start Workflow con tiếp theo của Role mới. Task catalog dùng chung; Workflow tham chiếu Task Definition thay vì nhúng logic executor tùy ý.

Process Definition: Fulfil shipment
  Workflow: Inspect container · ownerRole=FIELD_OPERATIONS
    Task: read_container_evidence ─┬─ Task: validate_iso
                                   └─ Task: validate_seal ─→ Task: join_findings
  Workflow: Confirm booking · ownerRole=DOCUMENTATION
    Task: lookup_booking → Task: confirm_or_review
  Workflow: Collect payment · ownerRole=FINANCE
    Task: reconcile_invoice → Task: confirm_receipt

Role catalog đề xuất

Role	Workflow chịu trách nhiệm (ví dụ)	Task capability (ví dụ)
FIELD_OPERATIONS	Điều phối hiện trường, kiểm tra Cont/Seal	Đọc ảnh, kiểm tra ISO/seal, ghi nhận xe, báo ngoại lệ
DOCUMENTATION	Booking và chứng từ	Đối chiếu booking, EIR, hồ sơ; chuẩn bị bộ chứng từ
FLEET_DISPATCH	Điều phối xe và tiến độ	Phân xe, kiểm tra chậm/trễ, cập nhật tiến độ
CUSTOMER_SERVICE	Thông báo và trao đổi khách hàng/nhà xe	Soạn/gửi template, yêu cầu bổ sung, trả trạng thái
FINANCE	Đối soát và thu tiền	Đối chiếu phí, hóa đơn, xác nhận thanh toán
SUPERVISOR	Workflow xử lý ngoại lệ/duyệt	Approve/reject/correct với audit

Đây là taxonomy đề xuất theo nghiệp vụ; role thật, tên, quyền và task catalog cần được owner nghiệp vụ xác nhận trước khi migration. Current runtime chỉ seed OPS và CUSTOMER_SERVICE cho vertical slice Cont/Seal; Master Orchestrator có catalog 5 persona tĩnh riêng, chưa tương đương Role runtime.

Runtime ports

Port	Input → output
RolePolicyResolver	tenant + role + workflow version → permissions/capabilities
TaskContextBuilder	process/workflow/task + context profile → scoped facts/evidence với provenance
TaskExecutorRegistry	task executor kind/code + pinned version → executor implementation
AI Connector	approved model capability + request → structured completion + usage metadata
ToolBroker	tool call + tenant/workflow/task scope → typed result + audit
TaskResultValidator	task output + schema + expected aggregate version → ACCEPT / REVIEW / REJECT

Context và quyền

Task context gồm Business Case references, process/workflow state, facts/evidence được phép, SOP của Role và thread history cần thiết. Mỗi fact giữ nguồn, thời gian và độ tin cậy. Model output không tự thành verified fact. Quyền hiệu lực là giao của tenant policy, Role policy, Workflow scope, Task capability và integration scope; adapter tự xác thực lại trước side effect.

AI use and guardrails

Chỉ task cần diễn giải/vision/generation mới gọi model; routing có thể dùng rule trước, AI chỉ hỗ trợ khi cần.
AI nhận task contract và context tối thiểu, trả typed result; không chọn Workflow tùy ý ngoài allowlist.
Tool permissions gắn với Task capability và Role policy, không dựa trên prompt.
Human task là executor hợp lệ; approve/correct/reject phải có identity và audit.
Model route, quota, cost/usage thuộc AI Connector/Stats; Role không sở hữu provider setting.

TDD acceptance

Workflow bind nhiều hơn một Role owner → reject khi publish.
Task executor trả output sai schema hoặc thiếu evidence → workflow chuyển REVIEW/FAILED theo policy, không commit fact.
Task thuộc workflow của Role khác → không thực thi bằng quyền Role hiện tại.
Thay Role/Task/Workflow version khi instance đang chạy → instance dùng pinned snapshot.
AI provider lỗi → retry bounded; hết retry chuyển human review/failed path; không tạo task side effect trùng.
Task cần handoff sang Role khác → kết thúc/handoff child workflow qua Process Orchestrator, không gọi Role trực tiếp.
Cross-tenant case reference hoặc RAG match → không rò facts/context.