01 · Booking Creation

Mọi đường booking được sinh ra. Kết quả là booking row với status ban đầu ∈ {PENDING, CONFIRMED, IN_PROGRESS} + Payment + Loyalty side effects.

Code ref: booking-api/src/core/booking/booking.service.ts — create(), walkIn().

1. Đường tạo booking

2. Guards (pre-conditions)

Mọi path cùng chạy qua BookingService.create (ngoại trừ walk-in có nhánh riêng). Guards chung:

Implementation

• G1 businessHours enforce ở API + UI
• G2 bookingMode enforce ở API + UI
• G3 resource skill check
• G4 conflict check + forceOverlap override cho OWNER/ADMIN
• G5 lead-time cap (D3)
• G6 walkIn toggle
• G7 guest loyalty reject
• G8 loyalty preflight (L3)

3. Initial status decision (resolveInitialStatus)

settings.autoConfirm === true          → CONFIRMED
settings.autoConfirm === false         → PENDING
walk-in                                → IN_PROGRESS (bypass autoConfirm)

Vấn đề chưa rõ ràng: nếu depositEnabled=true + autoConfirm=true, booking xuất phát đã là CONFIRMED trước khi Payment init. Khi PaymentAuthorized đến, listener thấy status != PENDING → skip → booking CONFIRMED nhưng không bao giờ bị cancel nếu payment fail. Xem gap P1-5 trong gaps-and-plan.md.

Implementation

• autoConfirm branch
• Walk-in direct IN_PROGRESS
• [!] autoConfirm=true + depositEnabled=true không có guard ngăn mix — rủi ro "confirmed không deposit".

4. Events emitted

Sau khi commit transaction, BookingCreated enqueue vào domain_event_outbox:

BookingCreated {
  bookingId, tenantId, startTime,
  totalAmount: payableTotal,            // = rawTotal - discountAmount (loyalty)
  originalAmount?, discountAmount?,     // chỉ có khi discount > 0
  depositAmount,                        // computed on payableTotal
  currency, idempotencyKey,
  intent: 'DEPOSIT' | 'FULL_PAYMENT',
  captureMode: 'MANUAL' | 'AUTO',       // DEPOSIT = MANUAL, FULL = AUTO
  returnUrl, cancelUrl, webhookUrl,
  customer?: { email, phone, name },
  metadata?,
}

• Walk-in: KHÔNG emit BookingCreated hiện tại (status IN_PROGRESS, không cần deposit flow, không loyalty reserve). Cần xác nhận — gap P2-3.

Implementation

• BookingCreated emit với full payload (A, B)
• [~] Walk-in không emit → mất cơ hội auto-earn stamp trên BookingCompleted (vì listener L4 vẫn fire nếu booking reach COMPLETED, nhưng reservation không tồn tại)

5. Payment side effect (post-commit)

PaymentIntegrationService.onBookingCreated:

if depositAmount <= 0: return (no-op)
else: dispatch InitiatePaymentCommand({
  intent: DEPOSIT | FULL_PAYMENT,
  captureMode: MANUAL | AUTO,
  amount: depositAmount, currency, urls, customer, idempotencyKey
})

→ Payment row created, provider.createSession() gọi Bambora, trả về redirectUrl vào Payment.metadata + enqueue PaymentInitiated event.

Implementation

• depositAmount > 0 → Payment init
• depositAmount = 0 → no-op
• Provider unavailable → markFailed + PaymentFailed event
• Admin UI hiển thị depositStatus = PAYMENT_FAILED với CTA retry (Flow 14 payment-flow.md) — chưa wire FE

6. Loyalty side effect (intra-transaction)

Nếu dto.redemption present:

preflight (đọc ngoài tx) → reserveInTx (ghi trong tx):
  VISIT_BASED:  LoyaltyRedemption{ status: RESERVED, cycleNumber }
                booking.appliedRedemptionId = redemption.id
                booking.discountAmount = preflight.discountAmount
  POINTS_BASED: LoyaltyPointTransaction{ type: REDEEM, points: -N, bookingId }
                booking.discountAmount = preflight.discountAmount
                (no redemption row)

Implementation

• VISIT_BASED reserve + link
• POINTS_BASED debit ledger
• Guest reject ngay preflight
• Atomic commit booking + redemption + outbox
• Admin UI tạo booking hộ khách + áp redemption — chưa build (L6)

7. Notification side effect

fire-and-forget qua NotificationQueue:

• BOOKING_CREATED → customer email/SMS nếu có customerPhone/Email.
• Nội dung: confirmation với deposit info nếu requiresPayment = true + payment link.

Implementation

• Notification enqueue trong booking.service.ts
• [~] Deposit link trong notification — payload chưa gắn paymentRedirectUrl do Payment init async, chỉ có sau outbox flush. Customer nhận mail "booking tạo" rồi một lúc sau mới có link pay.
• Email template cho case PAYMENT_FAILED khi customer cần retry — chưa có

8. Real-world cases (salon thật)

9. Checklist tổng hợp path create

• POST /bookings admin flow
• POST /public/tenants/:slug/bookings public flow
• POST /bookings/walk-in walk-in flow
• Tất cả guards G1–G8
• autoConfirm branch
• BookingCreated outbox + payload
• Loyalty reserve intra-tx
• Payment init async
• Notification enqueue
• [~] Walk-in không emit BookingCreated (ảnh hưởng loyalty auto-earn path)
• [!] autoConfirm=true + depositEnabled=true: booking CONFIRMED trước khi payment verify → payment-failed listener skip
• Admin tạo booking + áp loyalty redemption UI (L6)
• Retry payment UI cho FAILED / EXPIRED (P1-4)
• VIP per-customer flag để skip deposit (P2-2)
• paymentMode: IN_PERSON cho phone booking (P1-3)

→ Xem gaps-and-plan.md cho ưu tiên + plan.