02 · Happy Path Transitions

Các transition thuận: PENDING → CONFIRMED → ARRIVED → IN_PROGRESS → COMPLETED. Không bao gồm cancel / no-show (xem 03-cancel.md, 04-no-show.md).

Endpoint chung: POST /bookings/:id/status/:status (roles: OWNER/STAFF/ADMIN). Flow: updateStatus() → isValidTransition OR isAdminTransition → guard → prisma.update + outbox enqueue → audit log → notification.

State diagram + capture trigger

stateDiagram-v2
    [*] --> PENDING: BookingCreated\n(default)
    PENDING --> CONFIRMED: T1\nguard C2: deposit-required (P0-2)\nautoConfirm OR PaymentAuthorized listener
    CONFIRMED --> ARRIVED: T2\nstaff bấm "Check-in"
    CONFIRMED --> IN_PROGRESS: T3\nstaff skip ARRIVED
    ARRIVED --> IN_PROGRESS: T4\nstaff bấm "Start"
    IN_PROGRESS --> COMPLETED: T5\nstaff bấm "Complete"
    COMPLETED --> [*]
    note right of ARRIVED
      Capture trigger PRIMARY:
      onBookingArrived → MANUAL+AUTHORIZED
      Booksy/Timely/Vagaro pattern
    end note
    note right of COMPLETED
      Capture trigger FALLBACK
      (nếu skip ARRIVED)
      Loyalty: RESERVED→CONSUMED (L4)
      TenantCustomer: visitCount++
    end note

T1 · PENDING → CONFIRMED

Performer matrix

Guards

Events + side effects

• BookingConfirmed emit (payload: bookingId, confirmedAt, confirmedBy).
• Notification: BOOKING_CONFIRMED template gửi customer.
• Payment: KHÔNG capture (giữ hold, capture ở ARRIVED).
• Loyalty: no-op.

Real-world

Implementation

• State machine transition
• Event emit BookingConfirmed
• Audit log
• Notification
• Guard C2 (deposit required) — shipped P0-2 (force override cho OWNER/ADMIN với audit reason)

T2 · CONFIRMED → ARRIVED

Performer matrix

Guards

Events + side effects

• BookingArrived emit.
• Payment: onBookingArrived → capture MANUAL+AUTHORIZED payment (primary capture trigger).
• Notification: none mặc định (docs mô tả optional).
• Stats: none.

Real-world

Implementation

• State machine
• BookingArrived event
• Payment capture MANUAL+AUTHORIZED
• Idempotent (duplicate event → capture command idempotent key)
• UI "Check-in" button chỉ visible từ X phút trước startTime (nice-to-have)

T3 · CONFIRMED → IN_PROGRESS (skip ARRIVED)

Path ngắn khi staff/owner bấm "Start" luôn (khách đến, staff cầm máy bấm start thay vì 2 bước).

Performer matrix

Guards

Events + side effects

• KHÔNG emit event (code booking.service.ts:969 default branch return null).
• → Không có Payment capture ở bước này.
• Notification: none.

Real-world

Implementation

• State machine
• BookingStarted event (docs mention, code không emit) — cần quyết định có emit không
• S2 resource busy guard

T4 · ARRIVED → IN_PROGRESS

Performer matrix

Guards

Events + side effects

• KHÔNG emit event (cùng default branch).
• Payment đã capture ở ARRIVED bước trước.
• Notification: none.

Implementation

• State machine
• BookingStarted event + guard I2

T5 · IN_PROGRESS → COMPLETED

Performer matrix

Guards

Events + side effects

• BookingCompleted emit.
• Payment: onBookingCompleted → capture fallback nếu MANUAL+AUTHORIZED (ví dụ skip Arrived). Idempotent (đã CAPTURED → no-op).
• Loyalty: OnBookingCompletedListener (hiện pre-L3 — cần check L4):
  • RESERVED → CONSUMED nếu có appliedRedemptionId
  • autoStamp tạo stamp cho card VISIT_BASED qualifying
  • autoEarn cộng points cho card POINTS_BASED qualifying
• TenantCustomer metrics: visitCount++, lastVisit, totalSpent += payableTotal.

Real-world

Implementation

• State machine
• BookingCompleted event
• Payment capture fallback
• [~] Loyalty: pre-L3 listener có autoStamp/autoEarn, L4 RESERVED → CONSUMED chưa verify
• TenantCustomer metrics update
• M2/M3 full-payment guard (POS-gated)

Summary checklist

PENDING → CONFIRMED

• State machine
• Event BookingConfirmed
• Audit + notification
• Deposit-required guard — shipped P0-2

CONFIRMED → ARRIVED

• State machine
• Event BookingArrived
• Payment capture MANUAL+AUTHORIZED
• Check-in window UX (nice-to-have)

CONFIRMED → IN_PROGRESS

• State machine
• Event emit BookingStarted (docs promise, code không emit)
• Resource busy guard

ARRIVED → IN_PROGRESS

• State machine
• Event + guard (như trên)

IN_PROGRESS → COMPLETED

• State machine
• Event BookingCompleted
• Payment capture fallback
• TenantCustomer metrics
• [~] Loyalty L4 RESERVED → CONSUMED — cần verify
• Full-payment guard khi POS (future)

→ Chi tiết gap + plan: progress/gaps-and-plan.md.