--- title: AI Platform Lead Scoring v2 description: Hành vi nhà cung cấp Lead Scoring và ranh giới với DotB-Omni trong bản rebuild. status: review_ready --- # Lead Scoring v2 Thiết kế app auth được người dùng cho phép triển khai theo baseline chung `omni-ai-platform-app-auth`, revision 2, ngày 2026-09-30. Đặc tả này ghi lại phần provider trong repo; generated OpenAPI và các fixture tại `contracts/lead-scoring/v2/` xác định wire shape. Tên thư mục `v2` chỉ là vị trí artifact hiện có, không tạo yêu cầu tương thích tenant auth cũ. Nghiệm thu liên dịch vụ với Omni/AIHub vẫn cần bằng chứng riêng. ## Sở hữu - DotB-Omni quản lý users/accounts, quyền EMS, connection, enabled/config, snapshot, rules/points, weights, score bands, HITL/review/override và CRM writeback. Omni gửi app key và V-Key từ backend, không từ browser. - AI Platform xác thực installation bằng app key, kiểm tra active và quyền `lead_scoring`, thực thi scoring, lưu run và thông báo kết thúc. Không đăng ký account hoặc xác thực user/credential EMS. - AI profile nội bộ có phiên bản chọn AIHub hoặc OpenAI-compatible cho service; Omni không chọn provider từng request. Admin Web chỉ quản lý AI profile, xem/chạy fixtures và xem/thu hồi app access; không quản lý nghiệp vụ khách hàng hoặc hiển thị raw app key. - DotB EMS là nguồn sự thật CRM. Webhook chỉ thông báo; Omni GET chi tiết, đối chiếu identity/lead/request nguồn trước khi ghi EMS. ## Admission và idempotency `POST /v1/lead-scoring/runs` nhận `Authorization: Bearer `, `Idempotency-Key: ` và `X-Tenant-VKey` tùy chọn. App ID được suy ra từ key, không từ body. Body có đúng `request_id`, `account_id`, `subject_ref`, `snapshot`, `scoring_config`, `ai_profile`. - `request_id` là UUID chuẩn lowercase có dấu gạch ngang; header phải biểu diễn cùng UUID. `account_id` là chuỗi 1–255 ký tự không chỉ whitespace, giữ nguyên case/whitespace, Omni dùng `account.id.to_s`. Provider không kiểm tra account tồn tại ở Omni. `subject_ref` phải khớp `snapshot.lead_profile.ems_lead_id`. Field dư gồm app/tenant/callback bị từ chối 422. - Thiếu/sai/revoked key hoặc inactive app trả 401; app hợp lệ thiếu quyền Lead Scoring trả 403, cả POST và GET. GET run thuộc app khác hoặc không tồn tại trả 404. Omni sở hữu account/user isolation trong app của mình. - Fingerprint SHA-256 của canonical body sau HTTP validation, không chứa secret headers. Lookup `(app_id, account_id, request_id)` trước khi chọn AI profile hoặc kiểm tra webhook availability. Cùng identity/body trả 200 cùng run hiện tại, không schedule lại; body khác trả 409. PostgreSQL unique constraint và transaction giải quyết POST đồng thời. Account/app khác được dùng cùng request UUID. - Run mới đóng băng profile đang active, INSERT + COMMIT trước schedule, trả 202 và `Location`. Thiếu mapping callback trả 503 trước INSERT; replay vẫn hoạt động khi mapping bị gỡ. DB unavailable hoặc scheduling failure trả 503; scheduling failure terminalize run thay vì để pending giả. Omni retry cùng UUID/body vì timeout/503 có thể xảy ra sau commit. - Summary/detail có app/account/request/run identity, không tenant ID. Chấm lại hoặc dùng profile mới cần UUID mới. Không reuse UUID quá retention 90 ngày: run và fingerprint bị xóa, không có tombstone. - Giữ rule/operator/value validation, tổng weights bằng 1, score/points và snapshot limits: 10 conversations, 50 messages, 20.000 ký tự nội dung, 90 ngày evidence, snapshot 100KB và hard cap toàn body. Không hard-code category/action/review state. - Mỗi `scoring_config.rules[]` có `description` tùy chọn, chuỗi tối đa 99 ký tự Unicode. Thiếu hoặc `null` giữ wire body chuẩn hóa cũ để bảo toàn fingerprint/replay; chuỗi rỗng hoặc chỉ whitespace được nhận nhưng không thêm vào AI context. Mô tả có nội dung được lưu cùng request và tham gia fingerprint, nên đổi mô tả với cùng identity trả 409. Mô tả không thay đổi điều kiện khớp, points hoặc breakdown của bộ chấm quy tắc. ## Kết quả và lỗi - `ai_weight=0`: `rules_only`, `degraded=false`, `ai_score=null`, không gọi AIHub và không cần V-Key. - `ai_weight>0` thiếu V-Key với AIHub hoặc provider lỗi: `rules_only_fallback`, `degraded=true`, `ai_score/ai_confidence=null`, `final_score=rule_score`, mã lỗi chuẩn hóa. Không tự AI retry. - AI thành công: `hybrid`, `degraded=false`, `final_score=clamp(round(rule_score*rule_weight + ai_score*ai_weight), 0, 100)`; breakdown/reasoning/evidence/confidence có giới hạn. Chỉ gửi các `description` có nội dung làm ngữ cảnh bổ sung ở bước chấm AI cho cả AIHub và OpenAI-compatible; không gửi rule IDs, điều kiện, points hoặc weights. Mô tả được đóng gói như dữ liệu JSON, không phải chỉ dẫn hệ thống hay bằng chứng về khách hàng; snapshot và evidence vẫn là căn cứ chấm điểm. - Bug/code/DB failure thành `failed`, không giả là AI fallback. Đổi profile/provider cần version mới và audit trong cùng transaction. Medium two-pass là mặc định khi dùng AI; Light/Heavy cần nhu cầu và xác minh riêng. ## Credential và runtime - Một app ID ổn định và một key cho mỗi Omni installation/environment, dùng chung các account. DB chỉ lưu SHA-256 verifier, active và quyền Lead Scoring. Rotate giữ app ID, GET/replay run cũ và permission; key cũ hết hiệu lực. Không tenant provisioning endpoint/secret, account registration hoặc dual auth. - Vận hành dùng CLI `create-app`, `rotate-app-key`, `revoke-app-key`; raw key chỉ trả ở thao tác CLI cấp/rotate. Admin session độc lập, password hash, CSRF mutation, cookie bảo vệ, logout/expiry và audit không chứa secret. Web chỉ list/revoke app access. - `X-Tenant-VKey` giữ tên hiện tại vì là giao tiếp provider AI riêng; chỉ giữ trong RAM current task, forward Bearer tới AIHub. OpenAI-compatible dùng URL versioned trong profile, server API key chỉ gửi tới URL được cấu hình cho key đó. HTTP chỉ cho loopback development, production yêu cầu HTTPS. Không persist/log/trace/error/browser raw secret. - Một backend process với asyncio tasks. Startup đọc migration head, không tự migrate; terminalize pending/running bị mất thành `failed/worker_interrupted`. Không resume V-Key hoặc tự chấm lại sau crash. - Schema chưa phát hành được gộp thành một migration `0001_initial`, tạo thẳng app auth hiện tại; không giữ chuỗi chuyển đổi tenant cũ. Database local mang revision cũ cần xử lý riêng trước khi chạy lại, không tự stamp/reset hoặc xóa dữ liệu. Sau lần phát hành đầu tiên, giữ lịch sử migration đã phát hành. ## Terminal delivery - Terminal transition và outbox commit cùng transaction. `AI_PLATFORM_APP_WEBHOOKS` là JSON mapping `app_id → {"url":"...","signing_secret":"..."}`; secret tối thiểu 32 ký tự, HTTPS hoặc development loopback HTTP, không credentials/query/fragment trong URL. Không request callback hoặc subscription framework. - Webhook tới endpoint Omni `/api/v1/internal/lead-scoring/notifications`, body đúng `event_id`, `app_id`, `account_id`, `request_id`, `run_id`, `status`, `occurred_at`. Identity lấy từ run đã lưu; không điểm/snapshot/evidence/secret. Event/body bất biến qua retry; timestamp header mới cho từng attempt. - HMAC-SHA256 trên byte UTF-8 `timestamp + "." + raw_body`, header `X-Webhook-Signature: sha256=`, `X-Webhook-Timestamp` ISO UTC. Omni xác minh raw bytes, constant-time, ±5 phút, giới hạn body 8192 bytes rồi parse/schema. - Omni lưu event trước ACK 202, duplicate đúng body trả 200, dedupe `(app_id,event_id)`, identity/conflicting duplicate trả 409. App/request nguồn không khớp trả 404. Omni GET bằng app key và đối chiếu app/account/request/run/lead trước writeback. Callback sớm tra được request nguồn đã commit trước POST. - Provider retry non-2xx/network tối đa 5 attempts rồi dead. `redeliver-notification ` đặt lại delivery của cùng event, không tạo run hoặc rescore. Không follow redirect khi gửi webhook. ## Privacy và nghiệm thu - Retention xóa run/snapshot/fingerprint/evidence và outbox liên quan sau 90 ngày. App/account offboarding và backup lifecycle phải chốt trước production; DB deletion không chứng minh backup đã xóa. - Omni lưu request nguồn bất biến trước HTTP, retry cùng UUID/body, bind run atomically, giữ account/subject ordering namespace `lead-scoring`, recheck enabled/EMS trước writeback. Đây là trách nhiệm consumer cần nghiệm thu ở Omni, không được suy ra từ tests provider. - Nghiệm thu: app auth/permission, cross-app GET, account/app replay isolation, concurrent POST, rotation, callback availability, HMAC và redelivery, rules-only/hybrid/fallback/failed regression, migration khởi tạo/schema/constraints/lifecycle, secret safety và Web checks. Một test liên ứng dụng với AI/EMS giả lập vẫn bắt buộc trước kết luận integration chạy đúng. - AIHub sandbox protocol/model/timeout/quota và production hosting/TLS/secret injection/backup/alerts chưa được xác minh. Không tuyên bố production-ready từ local checks.