Tenant Lifecycle — Specification (Beta-5)

Đặc tả vòng đời Tenant của BNG Booking Platform — chứng minh mô hình multi-tenant / white-label hoạt động thật.
Nguồn sự thật code: provisioning/provisioning-service.ts (transition + audit), booking-service.ts (assertTenantActive — cổng booking),
prisma/schema.prisma (tenants.status). Kiểm chứng E2E: src/__tests__/tenant-provisioning-e2e.test.ts, src/__tests__/ops-tenant.test.ts.

Tenant là gì

Tenant = một tenants row (đơn vị thuê / thương hiệu white-label). Booking, Inventory, Reservation đều tenant-scoped. Beta-5 thêm cột tenants.status (migration 20260706000000_add_tenant_status, additive DEFAULT 'active').

Trạng thái

Cổng Tenant (booking): BookingService.assertTenantActive chặn availability/booking khi tenant != active
⇒ TENANT_INACTIVE (HTTP 403). Đặt ở BookingService (không ở auth) vì bảng tenants là RLS-FORCE:
auth chạy TRƯỚC khi có tenant context nên không đọc được tenants. Cổng chạy TRONG tenant context (đã `SET LOCAL
app.current_tenant`) ⇒ RLS-safe. Tương thích ngược: tenant không có row lifecycle (legacy/chưa provision qua Beta-5)
giữ hành vi cũ; chỉ chặn tenant đã có row và không active.

Sơ đồ chuyển trạng thái

   provision            activate                suspend
 (∅) ───────▶ provisioned ─────────▶ active ─────────────▶ suspended
                   │                   ▲  │                    │
                   │                   └──┘ reactivate ────────┘
                   │                   │
                   │ archive           │ archive               │ archive
                   ▼                   ▼                        ▼
                            archived  (TERMINAL)

Transition hợp lệ

Transition KHÔNG hợp lệ (⇒ TENANT_INVALID_TRANSITION, exit 2)

• provisioned → suspended (phải active trước).
• provisioned → active qua reactivateTenant (sai ngữ nghĩa — dùng activateTenant).
• suspended → active qua activateTenant (sai ngữ nghĩa — dùng reactivateTenant).
• Bất kỳ transition nào từ archived (terminal).
• Tenant không tồn tại ⇒ TENANT_NOT_FOUND (exit 2).

Invariant

1. Terminal: archived không có transition ra.
2. Suspend thuận nghịch: suspend chỉ đổi tenants.status — không xoá inventory/key/reservation ⇒ reactivate khôi phục nguyên trạng, cùng API key booking lại được.
3. Cổng booking = tenant status: nguồn sự thật cho "booking chạy không" là tenants.status = active. Không đường vòng.
4. Độc lập với Partner (Beta-4): suspend Tenant không đụng Partner status/key; suspend Partner không đụng Tenant status. Hai cổng độc lập, xếp tầng (một request qua cả hai).
5. Audit đầy đủ & bất biến: mỗi transition sinh đúng 1 AuditEvent (append-only), scope tenantId.
6. Không secret trong audit: metadata sanitize ở domain.

Quan hệ Partner ↔ Tenant ↔ Inventory ↔ Booking

Partner (Customer, Beta-4)
  │ 1..1  (provisionTenant gắn customer.tenantId)
  ▼
Tenant (tenants, Beta-5)  ──status gate──▶ Booking API
  │ 1..N (seed-inventory / provision)
  ▼
Inventory (Listing → Unit → Availability + Price)
  │
  ▼
Reservation (Booking, Beta-1/2) — tenant-scoped, RLS

• Partner sở hữu Tenant (1 customer ↔ tối đa 1 tenant, customers.tenantId unique).
• Tenant chứa Inventory (Listing/Unit/Price/Availability), tất cả tenant-scoped (RLS khi bật).
• Booking chạy trên Inventory của Tenant; qua hai cổng: Partner active (auth, Beta-4) và Tenant active (booking, Beta-5).
• Ma trận cổng:

Audit event (Deliverable #5)

Scope AuditEvent.tenantId = tenantId; entityRef = tenantId; actor {kind:"authenticated", source:"ops_cli", role:"ops"}. Kiểm chứng: TENANT-AUDIT-VERIFICATION.md.