Release Report — Stage Beta · Sprint Beta-4 · Partner Management Foundation

Mục tiêu: nền quản lý Partner để onboard đối tác đầu tiên chuẩn hoá, Founder điều hành không cần SQL thủ công.
Không mở rộng Platform Core · không Payment · không Frontend đầy đủ · không đổi deployment.

1. Những gì đã hoàn thành

Code (surgical — 3 file infra)

• Cổng Partner ở auth (auth/api-key-store.ts): findActiveKey từ chối key nếu Partner chủ quản không active.

⇒ suspend/reactivate THUẬN NGHỊCH (không huỷ key). Không migration (customers.status đã có).

• Vòng đời Partner + audit (provisioning/provisioning-service.ts): createPartner(pending) · activatePartner ·

suspendPartner(reversible) · reactivatePartner · revokePartner(terminal) với guard invariant (PartnerTransitionError/PartnerNotFoundError); audit cho 7 thao tác (partner.* + apikey.issued/rotated/revoked), scope tenantId=partnerId, metadata sanitize.

• Ops CLI (ops/cli.ts): create-partner · create-tenant · seed-inventory · activate-partner · suspend-partner ·

reactivate-partner · revoke-partner(--confirm) · deliver-key · show-audit; issue-key thêm cờ opt-in --deliver (mặc định giữ nguyên pending_delivery). Transition sai → exit 2 (không throw thô, không 5xx).

Tài liệu (Deliverables #1/#2/#3/#5)

• docs/platform/PARTNER-LIFECYCLE.md — trạng thái, transition hợp lệ/không, invariant, audit.
• docs/operations/PARTNER-OPERATIONS.md — mọi thao tác + quy trình nghi lộ API key (không secret).
• docs/demo/PARTNER-MANAGEMENT-DEMO.md — 10 bước Founder tự chạy, mỗi bước có tiêu chí PASS.
• docs/platform/PARTNER-AUDIT-VERIFICATION.md — cách kiểm chứng audit (tự động + thủ công).

Test (Deliverable #4) — chạy trong CI (platform-ci.yml → test:infra)

• partner-management-e2e.test.ts — luồng DoD qua HTTP thật: create→activate→issue→availability 200→rotate→

key cũ 401→key mới 200→suspend→401→reactivate→200; assert đủ 7 audit event; assert không 5xx; assert key không bị huỷ khi suspend (bằng chứng thuận nghịch).

• ops-partner.test.ts — vòng đời qua CLI (Founder path), invariant→exit 2, partner-không-tồn-tại→exit 2,

bootstrap CLI trọn vẹn → key auth → suspend chặn → reactivate khôi phục, audit không lộ raw key.

Kết quả kiểm chứng (đã chạy)

• npm run lint ✅ · npm run typecheck:all ✅
• npm run test:infra (Postgres ephemeral qua Docker): 185/185 PASS, 0 fail — gồm test mới + toàn bộ test cũ vẫn xanh.
• Không có lỗi 5xx trong E2E (assert tường minh).

2. Những gì CHƯA hoàn thành / cố ý không làm

• Không UI/Frontend Portal quản lý Partner (ngoài scope) — điều hành qua ops CLI.
• Không self-serve onboarding cho đối tác (cấp key vẫn do ops thực hiện + giao one-time).
• Không wrap audit + state-change trong cùng transaction (hiện append awaited ngay sau update — xem Rủi ro).
• CI live-run: chưa quan sát một lần chạy job platform-ci.yml thật trên GitHub trong sprint này (đã verify cục bộ bằng chính lệnh CI dùng: lint + typecheck:all + test:infra). Job sẽ chạy khi push/PR lên main.
• Giữ song song provisionCustomer (tạo active, cho seed/back-compat) và createPartner (tạo pending, có audit) — không hợp nhất để tránh phá seed/Alpha.

3. Rủi ro còn lại

1. Audit chưa atomic với state-change (Trung bình): tiến trình chết giữa update và append có thể để lệch 1 event.

*Giảm thiểu:* thao tác là single-row, cửa sổ hẹp. *Khắc phục:* Beta-5 gói prisma.$transaction.

1. Cổng Partner thêm 1 truy vấn customer mỗi lần auth key có customerId (Thấp): 2 point-lookup có index; chấp nhận được.

*Tối ưu sau:* cache/@relation join khi cần (đo trước).

1. Hai lối tạo (provisionCustomer active vs createPartner pending) (Thấp): có thể gây nhầm. *Giảm thiểu:* tài liệu nêu rõ; Beta-5 cân nhắc hợp nhất.
2. Key gắn customerId=null không bị cổng Partner (Thấp, chủ ý): key legacy/seed không có partner vẫn auth như cũ (không hồi quy). Partner thật luôn có customerId.
3. revoke-partner terminal, không hoàn tác (Thấp, chủ ý): đúng thiết kế; khôi phục = tạo Partner mới.

4. Đề xuất Beta-5

1. Atomic audit: gói mỗi thao tác Partner/Key + audit trong một prisma.$transaction (khử rủi ro #1).
2. Partner read/report API + Founder viewer tối giản: endpoint/CLI liệt kê partner theo status + audit timeline (chỉ đọc), tiến tới màn hình Founder (M4B) — không mở Core.
3. Self-serve onboarding có kiểm soát: luồng cấp sandbox key + allowlist IP tự động (nối tiếp ma sát #1 của Beta-3 PIK).
4. Hợp nhất create path: gộp provisionCustomer/createPartner về một API có status khởi tạo rõ ràng (giảm rủi ro #3), kèm test hồi quy seed/Alpha.
5. Quan sát CI thật: xác nhận một lần chạy xanh của platform-ci.yml trên PR; cân nhắc thêm job đo thời gian E2E.

QA — Definition of Done

Trạng thái Sprint: deliverable + DoD đạt trên kiểm chứng cục bộ (lint/typecheck/test:infra xanh, E2E phủ toàn luồng). Còn lại để "CI PASS" theo nghĩa quan sát: một lần chạy xanh platform-ci.yml khi mở PR lên main. Chờ Founder review.