Pilot Runbook

Quy trình vận hành để Founder tự onboard đối tác Pilot đầu tiên mà không phụ thuộc đội phát triển.
Mọi lệnh đã kiểm chứng thật trong Gamma-1. Source of truth = file này (Markdown). Không sửa HTML trực tiếp.
Liên quan: Support Playbook · Onboarding Package · Execution Plan.

Ký hiệu

• Lệnh CLI chạy tại packages/platform-infrastructure: npm run ops -- <command> [--json] (cần DATABASE_URL trỏ DB tương ứng).
• partnerId == customerId. Tenant có vòng đời riêng (xem TENANT-LIFECYCLE).

1. Chuẩn bị trước Pilot

• Xác nhận sandbox/staging chạy: GET https://staging-api.booking.bngagency.vn/health → {"status":"ok"}.
• Bộ tài liệu bàn giao sẵn sàng (xem Onboarding Package §1).
• Nhận từ đối tác: tên tổ chức, môi trường (sandbox), IP egress (server sẽ gọi API).
• Xác định unitId sandbox cho đối tác (vd u_muongthanh_deluxe).

2. Cấp Sandbox (provision partner + tenant + inventory)

npm run ops -- create-partner --name "<Tên đối tác>" --owner founder --json     # → partnerId (pending)
npm run ops -- activate-partner --partner <partnerId>                            # → active
npm run ops -- provision-tenant --partner <partnerId> --tenant <tenantId> --name "<Tên>" --json
npm run ops -- activate-tenant --tenant <tenantId>                               # → active
npm run ops -- seed-inventory --tenant <tenantId> --json                        # inventory mẫu (Availability có dữ liệu)

• PASS: npm run ops -- tenant-health --tenant <tenantId> --json → status:"active", units > 0, partnerId khớp.

3. Allowlist IP (bắt buộc cho staging)

/api/booking/* trên staging trả 403 nginx nếu IP đối tác chưa được allowlist. Đây là thao tác ops trên VPS (ssh kqxs, sửa allowlist nginx), không thuộc phạm vi thay-đổi-code.

• Thêm IP egress của đối tác vào allowlist nginx staging.
• Reload nginx.
• PASS: từ phía đối tác (hoặc IP đã allowlist): GET /api/booking/availability?... không trả trang 403 HTML của nginx.

Nếu chưa thể allowlist (hoặc muốn tránh đụng staging), có thể chạy Pilot trên sandbox local production-like (xem Execution Plan §Ghi chú) — cùng code/migration/kit.

4. Cấp API Key

npm run ops -- issue-key --customer <partnerId> --env sandbox --deliver --json

• Output: banner + raw key ở dòng kế tiếp (KHÔNG nằm trong JSON summary) + JSON {keyId, prefix, status:"active"}.
• Copy raw key, giao đối tác qua one-time secret link / password manager (không email/chat thô).
• PASS: đối tác báo nhận key; key có status:"active".

Mất/lộ key ⇒ npm run ops -- rotate-key --key <keyId> --json (cấp key mới, key cũ revoke). Xem Support Playbook §401.

5. Smoke Check (BNG tự kiểm trước khi giao)

# Với key vừa cấp + base URL:
curl -s -H "x-bng-api-key: <KEY>" \
  "<BASE>/api/booking/availability?unitId=<unitId>&start=2026-09-10&end=2026-09-12&quantity=1&adults=2&children=0"

• PASS: HTTP 200 {"ok":true,"data":{"available":true,...}}.
• (khuyến nghị) chạy docs/integration/examples/curl/flow.sh với BNG_BASE_URL/BNG_API_KEY/BNG_UNIT_ID → exit 0 (Availability→Booking→Confirm→Cancel).

6. Bàn giao cho đối tác

• Gửi: base URL · unit IDs · xác nhận allowlist · bộ tài liệu.
• Đối tác bắt đầu theo Sandbox Checklist.

7. Checklist TRONG Pilot

• Theo dõi Success Metrics: onboarding time, integration time, API success, booking count.
• Mọi vấn đề của đối tác → ghi Issue Log (phân loại Hotfix/Backlog/Won't Fix).
• Chỉ hỗ trợ theo Support Playbook; chỉ mở Hotfix cho blocker (xem tiêu chí trong Playbook).
• Kiểm tra định kỳ: npm run ops -- show-audit --tenant <tenantId> --json (lịch sử tenant) · --partner <partnerId> (lịch sử key).
• Kiểm tra sức khoẻ: npm run ops -- health · tenant-health --tenant <tenantId>.

8. Checklist SAU Pilot

• Ghi Decision Log: GO / GO WITH NOTES / NO-GO + lý do.
• Tổng hợp metrics + feedback đối tác.
• Chuyển issue chưa xử lý sang Backlog Hardening.
• Nếu tiếp tục: giữ quyền; nếu dừng: thực hiện §9.

9. Thu hồi quyền (khi Pilot kết thúc / cần cắt truy cập)

# Tạm ngưng (thuận nghịch — giữ dữ liệu, có thể mở lại):
npm run ops -- suspend-tenant --tenant <tenantId> --reason pilot-ended       # booking → 403 TENANT_INACTIVE
npm run ops -- suspend-partner --partner <partnerId> --reason pilot-ended    # mọi key → 401

# Chấm dứt vĩnh viễn:
npm run ops -- revoke-key --key <keyId> --reason pilot-ended --confirm       # key → 401 ngay
npm run ops -- archive-tenant --tenant <tenantId> --reason pilot-ended --confirm   # terminal
npm run ops -- revoke-partner --partner <partnerId> --reason pilot-ended --confirm # terminal, huỷ mọi key

• Gỡ IP đối tác khỏi allowlist nginx (nếu đã thêm).
• PASS: đối tác không còn gọi được API (401/403); audit ghi nhận thao tác thu hồi.

Suspend là thuận nghịch (reactivate khôi phục). Revoke/Archive là terminal. Xem PARTNER-LIFECYCLE / TENANT-LIFECYCLE.