03 · Cancel Transitions

* → CANCELLED. File lớn nhất vì tổ hợp cao: starting booking status × payment status × performer × cancellation window.

Code ref:

• booking.service.ts:updateStatus — transition + window guard + event emit
• cancellation-refund-policy.ts:decideCancellationRefund — payment decision matrix
• payment-integration.service.ts:onBookingCancelled — command dispatch

1. Performer mapping

cancelledBy trong BookingCancelledPayload derive từ performer role:

const cancelledBy = performer?.role === 'CUSTOMER' ? 'CUSTOMER' : 'SALON';

Quan sát: hiện STAFF = SALON trong policy → staff cancel hộ khách (kể cả khách chủ động yêu cầu) luôn được full refund. Có thể bug — xem P2-1.

2. State machine allowed transitions

Từ booking-status.constants.ts:

PENDING      → CANCELLED ✅
CONFIRMED    → CANCELLED ✅
ARRIVED      → CANCELLED ✅
IN_PROGRESS  → CANCELLED ❌ (chỉ → COMPLETED)
COMPLETED    → CANCELLED ❌ (terminal)
CANCELLED    → CANCELLED ❌ (terminal)
NO_SHOW      → CANCELLED ❌ (terminal)

OWNER/ADMIN + SYSTEM bypass state machine qua isAdminTransition → có thể force IN_PROGRESS → CANCELLED. Nhưng Payment policy không xử lý nhất quán cho state này (xem §7).

3. Cancellation window guard

booking.service.ts:804:

if (newStatus === CANCELLED && !isSystem) {
  validateCancellationWindow(settings, booking.startTime);
  // throws BOOKING_CANCELLATION_TOO_LATE nếu hoursUntilStart < cancellationHours
}

Hành vi hiện tại:

• CUSTOMER out-of-window → 422 block ✅ (đúng spec)
• STAFF out-of-window → 422 block ⚠️ (docs ghi STAFF "in-window only", trừ khi có escalation path — hiện không có)
• OWNER/ADMIN out-of-window → 422 block ❌ trái docs (booking-status-flow.md role matrix cho OWNER force override)
• SYSTEM → skip ✅

→ Gap P0-1: OWNER/ADMIN phải bypass + endpoint nhận { force, reason }.

4. Payment decision matrix (decideCancellationRefund)

4a. cancelledBy = CUSTOMER

4b. cancelledBy = SALON (consumer protection — always refund)

4c. Defensive branch (code payment-integration.service.ts:144)

Nếu decision = FULL_REFUND nhưng capturedAmount - refundedAmount <= 0 → đổi thành VOID (ví dụ payment AUTHORIZED nhưng chưa capture lại đi vào FULL_REFUND branch do logic sai).

5. Full matrix: cancel × booking state × payment state × performer

Legend: [V] VOID, [R] FULL_REFUND, [F] FORFEIT (capture), [N] NO_ACTION, [x] NOT_APPLICABLE, [—] transition blocked.

5a. From PENDING

5b. From CONFIRMED

5c. From ARRIVED

Booking đã ARRIVED → Payment đã CAPTURED (primary capture point). hoursUntilStart thường âm → out-of-window.

5d. From IN_PROGRESS

State machine block cho STAFF/CUSTOMER. Chỉ OWNER/ADMIN force được qua isAdminTransition.

→ Real-world: staff làm hỏng dịch vụ giữa chừng, OWNER phải cancel + refund. Hiện có thể force nhưng UI chưa có path, chắc phải làm partial refund thủ công qua Payment UI rồi force status. Gap P2-5.

5e. From COMPLETED / CANCELLED / NO_SHOW

Terminal. Cancel không áp dụng.

• Refund: OWNER vẫn có thể refund qua Payment UI (POST /payments/:id/refund) mà không đụng booking status.

6. Events emitted

BookingCancelled {
  bookingId, tenantId, cancelledAt,
  bookingStartTime,                     // để policy tính hoursUntilStart
  cancelledBy: 'CUSTOMER' | 'SALON',
  cancellationWindowHours: settings.cancellationHours,
  reason?,                              // TODO: chưa chạy qua request body
  idempotencyKey: `bk-${bookingId}-cancelled`,
}

Subscribers:

• PaymentIntegrationService.onBookingCancelled — payment command
• LoyaltyL4.onBookingCancelled (pending) — restore stamps / clawback points nếu RESERVED

Implementation

• Event emit
• Payload includes window hours
• [!] reason field chưa được nhận từ endpoint (controller không đọc body) — P0-1
• [!] cancelledBy không phân biệt STAFF-cancel-for-customer vs STAFF-salon-decision — P2-1

7. Customer-facing cancel

→ P1-1 resolved 2026-04-24. Frontend: account/BookingsSection exposes a "Cancel" CTA (ConfirmDialog) on PENDING/CONFIRMED/ARRIVED rows. Out-of-window UX (P1-2) still open.

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

9. Reschedule (alternative to cancel)

Hiện booking update time qua PATCH /bookings/:id — payment không phản ứng. Trong spec Fresha/Booksy: reschedule = đổi startTime, giữ payment hold nguyên.

→ Gap P1-7: reschedule guard rules + UX "đổi lịch thay vì hủy" khi out-of-window.

10. Checklist cancel

State machine

• PENDING/CONFIRMED/ARRIVED → CANCELLED (staff path)
• Admin/OWNER force bypass isValidTransition
• Terminal states block cancel

Guards

• Cancellation window cho CUSTOMER
• [!] Cancellation window block OWNER/ADMIN (P0-1)
• [!] { force, reason } body params missing (P0-1)

Events

• BookingCancelled emit
• cancelledBy + cancellationWindowHours payload
• [!] reason không được persist (không đọc từ body)
• Phân biệt STAFF-for-customer vs SALON (P2-1)

Payment integration

• decideCancellationRefund all combos
• VOID / FULL_REFUND / FORFEIT / NO_ACTION dispatch
• Defensive fallback FULL_REFUND → VOID khi outstanding=0
• Idempotency key per decision

Customer UX

• Public POST /public/.../bookings/:id/cancel endpoint (P1-1, shipped 2026-04-24)
• "Contact salon" CTA khi out-of-window (P1-2)
• Preview "Refund amount" trước confirm cancel (P1-8)

Admin UX

• Force cancel với reason modal (P0-1)
• Audit log CONFIRMED_FORCE_CANCEL với reason (P0-1)
• Partial refund workflow khi force cancel IN_PROGRESS (P2-5)

→ gaps-and-plan.md tổng hợp priority.