Design baseline · 28 SEP 2026 · 04 / 23
Database design
PostgreSQL · tenant-scoped relations · Process / Workflow versioning
database.sql là reference design để review tenant keys, version pins và quan hệ; phải chuyển thành migration sau khi chốt contracts.DESIGN DIAGRAMS · TARGET ARCHITECTURE 2.0
01 · ERD catalog Process / Workflow / Task
Process Definition version tham chiếu Workflow versions; mỗi Workflow pin đúng một Role version và chứa task graph; task bindings pin schema/executor version. Ký hiệu: || = một, ○| = 0..1, ○< = 0..N. Cột hiển thị là khóa/state; tải SQL để xem đầy đủ.
02 · ERD runtime: event → case → process → workflow → task
Business Case có thể có nhiều Process Instances; mỗi Process Instance chứa nhiều Workflow Instances; mỗi Workflow Instance có nhiều Task Instances. Event chỉ là trigger/evidence, không mặc định tạo task mới. Ký hiệu: || = một, ○| = 0..1, ○< = 0..N. Cột hiển thị là khóa/state; tải SQL để xem đầy đủ.
03 · ERD kết quả, review và sự thật nghiệp vụ
Result gắn execution và Task Instance cùng tenant. Facts truy về result/evidence; outbox gắn task hoặc workflow side effect. Ký hiệu: || = một, ○| = 0..1, ○< = 0..N. Cột hiển thị là khóa/state; tải SQL để xem đầy đủ.
04 · ERD tenant, channel, integration và audit
Mỗi đường nối biểu diễn FK trong reference DDL. tenant_scope/session_scope ánh xạ identity hiện có; audit và idempotency được phân vùng logic theo tenant. Ký hiệu: || = một, ○| = 0..1, ○< = 0..N. Cột hiển thị là khóa/state; tải SQL để xem đầy đủ.
Schema logisa2 là namespace tham chiếu của target design, không phải schema đang chạy. Runtime đang chạy dùng schema core_*; file dưới đây mô tả schema target tách riêng Business Case, Process Instance, Workflow Instance và Task Instance. Tải reference DDL. File là tài liệu thiết kế, không phải Flyway migration để chạy tự động.
role_definitions → role_versions
task_definitions → task_versions
process_definitions → process_versions
process_workflow_bindings
workflow_definitions → workflow_versions
workflow_task_bindings · integrations
events → routing_decisions → event_process_instances
task_instances ↔ task_events / task_evidence
business_cases → process_instances → workflow_instances
workflow_instances → task_instances → executions
executions → results → result_evidence / reviews / outbox
shipments → shipment_facts
evidence · audit_events
audit_events · idempotency_keys
tenant/session identity (existing)
Catalog và cấu hình
| Bảng | Cột và constraints chủ chốt |
|---|---|
| role_definitions / role_versions | (tenant_id,id), code UNIQUE trong tenant; version composite FK. Lưu trách nhiệm, policy, capability và context profile; provider/model thuộc AI Connector policy. |
| task_definitions / task_versions; workflow_task_bindings | Version pin task type, executor kind và schemas; node binding thuộc Workflow version. Task kế thừa Role owner của Workflow, không assign Role tùy ý. |
| process_definitions / process_versions; workflow_definitions / workflow_versions | Definitions version hóa độc lập. Process version tham chiếu nhiều Workflow versions qua bindings; Workflow version bắt buộc một owner_role_id/version và graph đã validate. |
| session_scope_link | FK session thuộc tenant; channel, group_id và display-name snapshot cho channel-triggered Workflow config. |
| integrations | type, secret_ref, config JSONB; config chứa spreadsheet ID/range, không chứa access token. |
Runtime và sự thật nghiệp vụ
| Bảng | Cột và constraints chủ chốt |
|---|---|
| events / evidence | Provider event key UNIQUE(tenant,channel,session,provider_event_id); evidence giữ object_key, sha256, mime, size; không lưu URL có credential lâu dài. |
| routing_decisions / event_process_instances | Persisted routing proposal/action, Business Case correlation và Process Instance links; event có thể gắn nhiều process/workflow paths theo policy. |
| task_instances / task_events / task_evidence | Mỗi task instance thuộc một workflow instance và graph node; pin Task version, state, lease, idempotency. Event/evidence liên kết M:N. |
| business_cases / process_instances / workflow_instances | Business Case được correlate theo tenant + business key. Process Instance pin Process version; Workflow Instance thuộc Process Instance, pin Workflow/Role version; idempotency theo trigger key. |
| executions / results | Task/instance,node_id,attempt, lease_until, worker_id, fencing_token; unique(task,node,attempt). Results append-only, evidence refs và validation verdict. |
| reviews / outbox | Review expected aggregate version, actor/reason; outbox command_id UNIQUE, payload_hash, destination snapshot, state, provider receipt. |
| shipments / shipment_facts | Shipment lock_version; facts provenance result_id + evidence refs + confirmed_by. Chỉ validator/approved review được commit. |
| audit_events | Tenant, actor, action, aggregate/version, trace_id và structured details. |
| idempotency_keys | (tenant,operation,key), request_hash,response,status. Cùng key khác payload → conflict; retention ít nhất bằng replay horizon. |
Constraints bắt buộc
- Mọi FK business dùng cặp tenant_id + id; Process/Workflow versions và task bindings cũng tenant-scoped composite FK. Session FK trỏ identity/session của tenant hiện có qua migration mapping; không tạo hệ identity thứ hai.
- JSONB dùng cho task graph, config và structured payload; Process/Workflow/Task identities, ownership, versions, state và idempotency là quan hệ/cột có constraints.
- Không hard-delete version/evidence đang được tham chiếu. Archive identity; retention xóa object phải giữ tombstone và provenance.
- Index worker: (state,available_at) cho Task Instance/outbox; (tenant,shipment,created_at), (tenant,session,thread,occurred_at) cho context.
Transaction cookbook
| Lệnh | Một transaction / sau commit |
|---|---|
| Accept event | Insert event ON CONFLICT + evidence metadata + dispatch queue marker. Commit rồi ACK; lỗi DB không ACK thành công. |
| Publish Process/Workflow Definition | Validate versioned child references, single Workflow owner Role và task graph; insert immutable version, update published pointer và audit. |
| Dispatch / plan | Lock event/task; persist decision/plan + tasks/links/instance + audit. Worker nhìn thấy công việc sau commit. |
| Complete step | CAS state + lock_version + fencing token; insert result; validate; update facts/state; tạo next task/outbox + audit trong một transaction. External call không nằm trong transaction DB. |
| Review | Lock review + aggregate; compare expectedVersion; record actor/decision, revalidate and schedule continuation atomically. |
| Deliver | Claim outbox bằng SKIP LOCKED + lease; commit; gọi gateway với commandId ổn định; lưu SENT/UNKNOWN/FAILED. Timeout sau gửi có thể là UNKNOWN, phải reconcile. |
Không chỉnh lịch sử migration
Reference DDL không phải migration và không mô tả schema đang chạy. Khi triển khai cần additive migration, map tenant/session identity, backfill và validate FK/unique constraints; không sửa migration production đã áp dụng.