Pilot Friction Log

Mọi friction phát hiện khi kiểm tra Partner Integration Kit + dry-run. Không sửa hệ thống trong sprint này (chỉ docs nếu cần).
Mức độ: Blocker (chặn pilot) · High (cản đáng kể) · Medium · Low.

F-1 — Staging /api/booking/* trả 403 nginx cho IP chưa allowlist

• Mô tả: curl https://staging-api.booking.bngagency.vn/api/booking/availability (không allowlist) → 403 nginx (HTML), dù có API key. /health = 200. Kiểm chứng live 2026-07-06.
• Mức độ ảnh hưởng: Blocker cho pilot self-serve (partner tự kết nối). High → chấp nhận được cho pilot BNG-facilitated (BNG allowlist trước).
• Nguyên nhân: nginx access rule (allowlist IP) đứng trước app — biện pháp bảo vệ staging chưa public. Không có self-serve.
• Đề xuất xử lý: (a) Onboarding step bắt buộc: partner gửi IP egress, BNG allowlist trước khi giao key. Đã tài liệu hoá (Integration Guide §2.3, Onboarding Package §3). (b) *Backlog Hardening:* cân nhắc host sandbox riêng có auth-only (không IP-gate) để partner tự kết nối. Không sửa trong sprint này (đụng deployment — ngoài phạm vi).

F-2 — Error Catalog + OpenAPI thiếu TENANT_INACTIVE (drift từ Beta-5)

• Mô tả: Beta-5 thêm mã TENANT_INACTIVE (403) khi tenant suspended/archived/provisioned, nhưng PIK (Beta-3) chưa liệt kê → partner gặp lỗi không có trong tài liệu.
• Mức độ ảnh hưởng: Medium (partner có thể hiểu nhầm 403 là lỗi request của mình).
• Nguyên nhân: PIK viết ở Beta-3, trước khi có Tenant lifecycle (Beta-5). Tài liệu không được cập nhật khi thêm mã lỗi.
• Đề xuất xử lý: ĐÃ SỬA trong sprint này (chỉ docs): thêm TENANT_INACTIVE vào API-ERROR-CATALOG.md + openapi.yaml. *Backlog:* thêm bước "cập nhật PIK" vào Definition of Done mỗi sprint thay đổi error/contract.

F-3 — examples mặc định trỏ Base URL = staging

• Mô tả: Scripts trong examples/ mặc định BNG_BASE_URL=https://staging-api.booking.bngagency.vn. Partner test local/sandbox khác phải override.
• Mức độ ảnh hưởng: Low (đã ghi trong examples/README.md; chỉ cần export biến).
• Nguyên nhân: Mặc định hợp lý cho pilot thật (staging), nhưng gây thao tác thừa khi test nơi khác.
• Đề xuất xử lý: Giữ nguyên (mặc định staging đúng cho pilot). Đảm bảo README nêu rõ (đã có). Không sửa.

F-4 — Trích raw API key từ output issue-key (BNG-side)

• Mô tả: ops issue-key in banner + raw key ở dòng kế tiếp rồi JSON summary. Người vận hành BNG cần biết raw key là dòng sau banner (không nằm trong JSON).
• Mức độ ảnh hưởng: Low (thao tác nội bộ BNG, không phải partner).
• Nguyên nhân: Thiết kế cố ý — raw key không nằm trong JSON summary (chống log lẫn secret).
• Đề xuất xử lý: Ghi rõ trong PARTNER-OPERATIONS.md (đã mô tả "in raw key MỘT LẦN ngay dưới banner"). Không sửa.

F-5 — PIK chưa nhắc vòng đời Partner/Tenant (Beta-4/5) cho partner

• Mô tả: Integration Guide không giải thích rằng partner/tenant có thể bị BNG suspend → request bị từ chối (401/403). Partner có thể bối rối khi bị chặn.
• Mức độ ảnh hưởng: Low → Medium.
• Nguyên nhân: PIK tập trung API booking, chưa phản ánh capability vận hành thêm sau Beta-3.
• Đề xuất xử lý: Đã bổ sung TENANT_INACTIVE vào Error Catalog (F-2) — đủ để partner nhận diện. *Backlog (Low):* thêm một đoạn "trạng thái tài khoản" vào Integration Guide. Không bắt buộc cho pilot.

Tổng hợp

Không có blocker chức năng. Blocker duy nhất (F-1) là truy cập, được xử lý bằng bước onboarding của BNG (không phải sửa code/deploy trong sprint này).