--- title: App auth provider handoff description: Bằng chứng kiểm thử AI Platform theo app-auth revision 2 và các bước còn cần nghiệm thu với Omni. status: draft --- # Bàn giao app auth phía AI Platform Phần provider đã triển khai theo baseline `omni-ai-platform-app-auth`, revision 2, ngày 2026-09-30. Spec trong repo là `docs/specs/ai-platform-lead-scoring.md`; OpenAPI và fixtures tại `contracts/lead-scoring/v2/` là artifact provider-generated. Trạng thái `review_ready` của spec dành cho nghiệm thu liên dịch vụ, không phủ nhận quyền triển khai đã được phê duyệt. ## Phạm vi hoàn tất - POST/GET dùng Bearer app key, suy ra app ID ổn định; kiểm tra active và quyền `lead_scoring`. Thiếu/sai/revoked/inactive trả 401, thiếu quyền trả 403; GET run của app khác trả 404. - Request có account ID không rỗng, UUID chuẩn và subject khớp snapshot lead. Run/replay unique theo `(app_id, account_id, request_id)`; 202 mới, 200 replay, 409 body khác. PostgreSQL test kiểm tra POST đồng thời chỉ schedule một run. - Summary/detail/outbox/webhook dùng app/account/request/run identity. Rotate key giữ ownership/replay và permission. Tenant auth/provisioning runtime, endpoints, UI và env cũ đã thay trực tiếp. Theo quyết định gộp schema chưa phát hành của người dùng, source hiện chỉ còn baseline `0001_initial`. - Mapping backend `AI_PLATFORM_APP_WEBHOOKS` định tuyến URL/secret theo app. Thiếu mapping chặn run mới với 503 sau replay lookup. Event/body ổn định qua retry, timestamp gửi mới mỗi attempt, chữ ký HMAC trên raw bytes, không follow redirect. Hết năm attempts giữ dead event; CLI redeliver cùng event, không rescore. - CLI cấp/rotate/revoke key; DB chỉ lưu verifier. Admin session/CSRF độc lập; Web chỉ list/revoke, không nhận raw app key. Fixture runner dùng app key server-only; demo seed yêu cầu key đã cấp, không tự provisioning. - Generated OpenAPI khai báo Bearer auth và lỗi HTTP. Generator xuất summary/detail/webhook từ serializers; điểm và breakdown của examples được tính bằng scoring hiện tại từ request fixture. Chế độ `--check` phát hiện fixture drift mà không ghi file. - Scoring pipeline, giới hạn snapshot, rules-only/hybrid/fallback/failed và RAM-only `X-Tenant-VKey` được giữ trong regression suite. Lỗi validation/DB trên scoring API trả thông báo an toàn, không echo credential hoặc SQL. ## Bằng chứng provider local Chạy tại root AI Platform, dùng môi trường project-local Python 3.13.14 và PostgreSQL test database `ai_platform_test` cho database tests: - `uv run --no-sync ruff check src tests scripts migrations`: PASS. - `uv run --no-sync ruff format --check src tests scripts migrations`: PASS, 78 files đã đúng format. - `uv run --no-sync pyright`: PASS, 0 errors / 0 warnings. - `uv run --no-sync lint-imports`: PASS, 3 contracts kept / 0 broken. - `make contract`: PASS; sinh OpenAPI và serializer-derived fixtures. - `uv run --no-sync python scripts/export_contract_fixtures.py --check`: PASS. - `set -a; . ./.env.test; set +a; uv run --no-sync python /tmp/verify_ai_platform_baseline.py`: PASS, 193 passed; 1 cảnh báo deprecation Starlette/httpx đã có. Harness tạm tạo schema mới, chạy Alembic upgrade/check rồi pytest, sau cùng chỉ xóa schema nó tạo và xác nhận public revision không đổi. `make test` trực tiếp trên public schema cũ chưa chạy lại vì public vẫn mang revision đã gộp bỏ; cần xử lý DB local riêng trước. - `make check-fast`: PASS, Ruff/format/YAML/TOML/conflict/private-key hooks. Lệnh này chỉ xử lý tracked files; untracked source được kiểm tra bằng các lệnh Ruff/Pyright/pytest và review trực tiếp. - `docker compose config --quiet`: PASS. - `uv run --no-sync alembic heads`: PASS, `0001_initial` là head duy nhất. - `make build`: PASS ở phiên app-auth trước khi gộp migration, tạo `ai-platform-backend:local` và `ai-platform-web:local`. Chưa rebuild Docker images sau gộp; không deploy hoặc chứng minh runtime toàn Compose stack. - `git diff --check`: PASS. Chạy tại `apps/web`: - `bun run format:check`: PASS. - `bun run check`: PASS, 0 errors / 0 warnings; sinh lại types từ OpenAPI. - `bun run test`: PASS, 6 files / 16 tests. - `bun run build`: PASS. Có thông báo empty chunk và plugin timing; exit 0. Docker Web build cũng pass với artifact/fixture được copy vào build context. Các tests auth/replay/outbox sử dụng PostgreSQL thật và HTTP AI/webhook giả lập. Chúng không gọi hai backend AI Platform và Omni qua mạng thực tế, không xác minh EMS writeback hoặc AIHub sandbox. ## Migration baseline và database local Người dùng đã cho phép gộp source migration vì AI Platform chưa phát hành. Source hiện chỉ có `migrations/versions/0001_initial.py`, tạo đủ tám bảng của schema hiện tại. Đã bỏ chuỗi tenant→app cùng guard tests; `tests/test_initial_migration.py` kiểm tra khởi tạo, schema/model drift gồm server defaults và indexes, FK/unique theo app-account-request, unique notification/run và cascade xóa outbox, rồi downgrade/upgrade trong schema tạm. Đồng bộ metadata ORM với các defaults/index đã có trong DDL: AI profile active=false, run degraded=false và index dispatch outbox. Không đổi ownership, API hoặc hành vi scoring. Database test hiện hữu vẫn ở `0009_app_auth`; việc dọn đúng 97 legacy audit rows đã được phép diễn ra ở phiên trước và không được lặp lại. Phiên gộp source này không reset/stamp hoặc thay dữ liệu public. Full suite chạy trên schema mới tạm trong `ai_platform_test`; Alembic upgrade/check và 193 tests đều pass, schema tạm đã dọn, public revision giữ nguyên. Database local có revision cũ cần xử lý riêng trước khi chạy lại backend/migrate/tests trực tiếp. Có thể dùng database mới; việc dựng lại/xóa hoặc stamp database hiện hữu cần kiểm tra schema và xác nhận phạm vi dữ liệu cần giữ/bỏ. Startup vẫn từ chối revision không khớp, không tự migrate. Các migration phát hành sau baseline này được giữ lịch sử như bình thường. ## Review và giới hạn nghiệm thu Review áp dụng `docs/project_quality.md` cho tracked/untracked changes, gồm HTTP/application/persistence/bootstrap, schema/migrations, env/Compose/CI, serializers/fixtures và Admin Web. Các module lớn hiện hữu như wiring, persistence models và HTTP schemas vẫn giữ boundary hiện tại; không mở rộng thành refactor ngoài phạm vi app auth. Phần Omni có hồ sơ kiểm thử riêng trong tài liệu phối hợp. Phiên provider không sửa repo Omni và không chạy lại hoặc xác nhận các kết quả consumer đó. Những việc sau còn pending: 1. Omni import đúng artifact provider revision 2 và đối chiếu request/summary/detail/webhook; không coi contract provisional riêng là artifact đã thống nhất. 2. Chạy hai backend local cùng credential test và AI/EMS giả lập: admission, terminal callback, GET, đối chiếu request nguồn và ghi đúng lead. Kiểm tra early callback, timeout/replay, duplicate/conflict, account authorization và ordering trong flow thực tế. 3. Xác minh AIHub sandbox về protocol/model/timeout/quota và các điều kiện production: TLS, secret distribution, backup/restore/retention, alerting và deployment runtime. Các kết quả trên chỉ xác nhận phần provider local. Chưa commit, stage, push hoặc deploy trong phiên triển khai này.