Design baseline · 24 SEP 2026 · 22 / 23
Patterns, rules & cookbook
Những quy tắc bắt buộc khi thêm một năng lực mới.
| Rule | Cách áp dụng |
|---|---|
| R01 · Tenant everywhere | Tenant trong PK/FK, repository filter, cache key, RAG, trace context và integration scope. Không tin tenant từ client. |
| R02 · Database is truth | Role dùng chung facts; memory có provenance/TTL. Chỉ validator/orchestrator commit. |
| R03 · Version everything executable | Pin role/skill/flow/task schema/context policy khi plan; active run không đọc latest config tùy ý. |
| R04 · At-least-once + idempotency | Không hứa exactly-once từ provider. Inbox/outbox + stable keys + receipts + reconciliation. |
| R05 · No role-to-role calls | Structured result → orchestrator → next task. Causal chain luôn truy vết được. |
| R06 · AI output is a proposal | Parse schema, validate references, enforce permissions, business rules và state CAS. |
| R07 · No arbitrary flow code | Typed blocks và allowlisted conditions/mappings. Tool registry giới hạn executor. |
| R08 · Evidence before confidence | Confidence model không đủ để VERIFIED; cần field validation, provenance và expected-data checks theo policy. |
| R09 · Bounded work | Budget token/tool calls, timeouts, retries, context và ảnh có giới hạn cấu hình; exhausted → FAILED với reason và audit. |
| R10 · Public docs, private operations | Ví dụ giả; không publish credentials, Zalo IDs thật, Sheet links thật hay ảnh khách hàng. |
Cookbook A · Thêm task type
- Viết story, input/result schemas, invariants và error codes.
- Đăng ký task type và allowed roles; thêm context profile tối thiểu.
- Chọn skill đơn hoặc flow version; khai báo quyền tool/integration.
- Thêm positive/negative dispatcher fixtures và business acceptance.
- Publish cấu hình tenant pilot; kiểm tra trace, review, retry và receipt trước mở rộng.
Cookbook B · Thêm skill
- Chốt typed input/output và evidence contract; chọn CODE/AI/HYBRID.
- Tách pure business logic khỏi adapter IO; inject tools qua ports.
- Ghi timeout, retryable errors, idempotency semantics, side effects và compensation.
- Test output schema, permission denied, dependency failure và duplicate execution.
- Tạo version mới; không sửa version đang được instance tham chiếu.
Cookbook C · Thêm kênh hoặc MCP
- Map provider payload sang InboundEvent và provider receipt sang DeliveryReceipt.
- Resolve tenant/session; durable inbox trước ACK; redaction logs.
- Chuẩn hóa tool schemas và secret reference; limit tải ảnh/URL và request timeout.
- Test outage/replay/out-of-order/UNKNOWN; chỉ enable khi có credentials thật và scoped acceptance.
Definition of done
Mỗi thay đổi có schema/contract, migration additive khi cần, tests cho invariant thực tế, trace IDs, UI failure states và cookbook update. Một demo happy path hoặc model trả JSON đúng chưa đủ chứng minh workflow chạy bền vững.