Design baseline · 28 SEP 2026 · 23 / 23
Delivery & migration
Hiện trạng, khoảng cách và thứ tự triển khai 2.0.
DESIGN DIAGRAMS · TARGET ARCHITECTURE 2.0
Dependency map · Triển khai theo capability
Các milestone thể hiện quan hệ phụ thuộc, không phải lịch cam kết. Pilot Cont/Seal kiểm chứng runtime chung trước khi thêm nghiệp vụ.
Snapshot source: 24/09/2026. Trang này phân biệt phần có trong code và thiết kế đích; không thay thế kiểm tra deployment/acceptance ở mỗi release.
| Phần | Hiện có | Cần làm cho 2.0 |
|---|---|---|
| Zalo intake | Gateway, gom album, durable inbox; ảnh khớp flow sinh ASSIGN/task, ảnh ngoài flow ghi IGNORE | Dispatcher tổng quát cho text/đa ý định, ATTACH và task correlation. |
| Cont/Seal | Một OPS task đọc/xử lý album + một CUSTOMER_SERVICE child task gửi kết quả trong cùng legacy workflow instance; image skill, quality gate/review, Sheet snapshot, outbox | Operational acceptance trên nhóm Zalo demo; thêm review-to-report reconciliation. |
| Workflow config | core_workflows / core_workflow_versions; graph Cont/Seal; config projection được snapshot lúc dispatch | Process Definition → role-owned Workflow Definitions → task graph executor; handoff CUSTOMER_SERVICE thành Workflow riêng, không dùng chung legacy instance hai Role. |
| Workflow routing | UC-01 lấy nhóm nhà xe nguồn và nhóm kết quả từ workflow version; không dùng group-role assignment để dispatch | Group labels là tính năng riêng để phân loại/lọc theo US sẽ chốt sau; nhãn không đổi workflow routing. |
| Roles / Context | Tenant role/skill versions và task bindings cho OPS/CUSTOMER_SERVICE của UC-01 | RoleRuntime, ContextBuilder/RAG/memory, TaskRouter và ToolBroker tổng quát. |
| Model | Route Luna đã đọc ảnh synthetic thành công | Eval album thực tế, provider outage, OCR mâu thuẫn và regression set. |
| Other flows | Use cases đích trong cookbook | Booking/EIR/Truck/Customs chưa được coi là đã hoàn thành. |
Scope hiện tại: UC-01 · Check Cont/Seal. M1–M4 xây nền tảng và hoàn thiện UC-01. M5 là định hướng sau này; UC-02–05 chưa được triển khai trong đợt hiện tại.
Implementation sequence
| Milestone | Deliverable | Exit gate |
|---|---|---|
| M1 · UC-01 data contract | Migration V22: role/skill runtime; V23 removes legacy group-role assignments and keeps group display names | Chạy migration trên DB mới và DB đang có V1–V22; kiểm tra FK, seed tenant mới, backfill job. |
| M2 · UC-01 runtime | Rule dispatcher, OPS task, pinned flow/runtime snapshot, Cont/Seal image skill | Source/non-source, duplicate, task binding, config đổi khi task đang chạy. |
| M3 · UC-01 delivery | Legacy CUSTOMER_SERVICE child task trong cùng instance (hiện có); target migration tách thành Workflow gửi kết quả riêng, giữ pinned destination/outbox/receipt | SENT/UNKNOWN transition; không tự resend outcome mơ hồ. |
| M4 · Operational acceptance | Workflow UI nhiều nhóm nhà xe nguồn + nhóm kết quả; read photo → report về nhóm Zalo | Ảnh demo → đúng task/revision → kết quả/ảnh và receipt. Test suite chưa thay cho quyền nhóm/provider thật. |
| M5 · Expand | Booking, EIR, Truck, Customer Service; Customs sau integration contract | Mỗi task có schemas + use-case acceptance + operational evidence. |
Data migration & cutover
- Backup và thử restore; inventory active jobs, reports UNKNOWN, settings và flow revisions.
- Tạo additive schema; map existing tenant/session IDs; import roles/skills/task types và typed Process/Workflow definitions. Giữ stable source IDs.
- Map legacy image jobs/reviews/report IDs vào task provenance. Queued jobs thiếu pinned version phải snapshot cấu hình xác định tại cutover và ghi migration reason; không giả vờ biết revision quá khứ.
- Shadow tạo decision/result để so sánh, chặn outbound và business writes của runtime mới.
- Chuyển từng tenant/session bằng routing ownership flag trong transaction; một event chỉ có một runtime được phép tạo side effects.
- Drain worker cũ, đối soát pending/UNKNOWN; theo dõi pilot rồi mở rộng. Chỉ bỏ compatibility projection sau khi mọi reader đã chuyển.
Rollback
Tạm dừng claim mới, reconcile outbound không rõ kết quả, giữ task/evidence/audit. Rollback code bằng artifact tương thích additive schema; không drop dữ liệu đã tạo. Chỉ bật lại worker cũ khi mapping ownership và command IDs đảm bảo không phát trùng.
Vận hành và kiểm tra repo
bun run app:typecheck
bun run app:test
cd backend/ai-core && mvn test
# Build public cookbook from its source:
python3 docs/logisa-2/build.pyGiữ các README module và hướng dẫn Compose để chạy dịch vụ. Tài liệu migration/parity/Cont-Seal design cũ đã được thay bằng cookbook này; contract runtime hiện tại giữ riêng để không nhầm với v2.