Booking Lifecycle

The booking system manages tee time reservations through a state machine with holds, confirmations, cancellations, and rescheduling.

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  POST /hold     │────▶│  PENDING         │────▶│  POST /confirm  │
│  (create hold)  │     │  (slot held)     │     │  (finalize)     │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │                         │
                               ▼                         ▼
                        ┌──────────────────┐     ┌─────────────────┐
                        │  DELETE          │     │  CONFIRMED      │
                        │  (release)       │     │  (booked)       │
                        └──────────────────┘     └─────────────────┘
                               │                         │
                               ▼                         ▼
                        ┌──────────────────┐     ┌─────────────────┐
                        │  CANCELLED       │◀────│  DELETE         │
                        │  (slot free)     │     │  (cancel)       │
                        └─────────────────┘     └─────────────────┘

Source: libs/tee-time-services/src/lib/facade/booking.controller.ts

Slot States

State	Description	Booking Status
AVAILABLE	Open for booking	None
HELD	Temporarily reserved	PENDING
BOOKED	Permanently reserved	CONFIRMED
BLOCKED	Administratively blocked	None

Booking States

Status	Description	Next States
PENDING	Hold created, awaiting confirmation	CONFIRMED, CANCELLED
CONFIRMED	Booking finalized with payment	CANCELLED
CANCELLED	Booking cancelled, slot released	Terminal

Payment Status

Status	Trigger
UNPAID	Default on hold creation
AUTHORIZED	Payment authorized but not captured
CAPTURED	Payment captured on confirm
REFUNDED	Refund processed after cancellation

Hold Creation

Endpoint

POST /bookings/hold

// Request
{
  "tenantId": "tenant-123",
  "slotId": "slot-456",
  "bookingChannel": "online",            // Optional: online | phone | walkIn
  "contactName": "John Smith",
  "contactEmail": "john@example.com",
  "contactPhone": "+1234567890",
  "externalRef": "ext-ref-789",           // Idempotency key
  "additionalItems": [
    { "additionalItemId": 123, "quantity": 1 }
  ]
}

// Response
{
  "id": "booking-abc",
  "status": "PENDING",
  "slotId": "slot-456",
  "contactName": "John Smith"
}

// Headers
X-Booking-Status: PENDING
X-Idempotent: false
X-Booking-Channel: phone | walkIn | online  // Optional override (header wins over body)

Hold Flow

1. Tenant Isolation — Verify user has access to tenant
2. Idempotency Check — Return existing booking if externalRef matches
3. Slot Validation — Verify slot exists and belongs to tenant
4. Advance Window — Enforce advanceWindowDays policy
5. Channel enforcement — Apply course bookingChannels toggles; phone/walkIn are staff-only
6. Additional Items — Validate and create item reservations
7. Create Booking — Status: PENDING, linked to slot
8. Publish Event — slot.held gateway event

Idempotency

Three-layer protection:

// Layer 1: Database unique constraint
@@unique([tenantId, externalRef])

// Layer 2: Hard lookup before validations
if (externalRef) {
  const existing = await findByTenantAndExternalRef(tenantId, externalRef);
  if (existing) return existing;  // Return with X-Idempotent: true
}

// Layer 3: Redis distributed lock
const key = `idemp:tt:booking:${tenantId}:${externalRef}`;
const acquired = await cache.setIfAbsent(key, ttlSeconds);
if (!acquired) {
  // Lock busy - check for concurrent booking
  const concurrent = await findByTenantAndExternalRef(tenantId, externalRef);
  if (concurrent) return concurrent;
  throw new Error('Idempotency lock busy; retry');
}

Configuration:

BOOKING_IDEMPOTENCY_TTL_SECONDS=60  # Default lock TTL

Confirmation

Endpoint

POST /bookings/:id/confirm

// Request
{
  "amountCents": 5000,                    // Payment amount
  "paymentMethod": "card",                // Optional
  "benefitMembershipNumber": "M-001",     // For discounts
  "benefitProviderCode": "GOLFRSA"        // Benefit provider
}

// Response
{
  "id": "booking-abc",
  "status": "CONFIRMED",
  "paymentStatus": "CAPTURED",
  "paidAt": "2025-12-15T08:00:00Z"
}

// Headers
X-Booking-Status: CONFIRMED
X-Idempotent: false

Confirmation Flow

1. Status Check — Must be PENDING (or CONFIRMED for idempotent retry)
2. Eligibility Check — Validate benefit membership if provided
3. Update Booking — Status: CONFIRMED, payment captured
4. Facilities Release — Release cart assignment if applicable
5. Sync Items — Confirm item reservations, cancel unselected
6. Publish Events — teetime.booking.confirmed, slot.booked
7. Record Benefit — Log benefit application for audit

Idempotent Confirmation

Re-confirming an already confirmed booking:

• Updates payment fields if amountCents provided
• Returns existing booking with X-Idempotent: true
• Safe to retry without side effects

Cancellation

Endpoint

DELETE /bookings/:id?playerType=member

// Response
{
  "id": "booking-abc",
  "status": "CANCELLED"
}

Cancellation Flow

1. Booking Validation — Verify exists and tenant access
2. Policy Check — Enforce cancellation window
3. Cancel Booking — Status: CANCELLED
4. Release Facilities — Return cart assignment
5. Cancel Items — Update item reservations to CANCELLED
6. Waitlist Processing — Notify waitlisted players
7. Publish Events — teetime.booking.cancelled, slot.released

Cancellation Policy

interface CancellationOptions {
  minHoursBefore: number;      // Hours before tee time
  allowReschedule?: boolean;   // Allow within window
  perType?: Record<string, {   // Per-player-type overrides
    minHoursBefore: number;
    allowReschedule?: boolean;
  }>;
}

Example Configuration:

{
  minHoursBefore: 24,          // Default: 24h notice
  allowReschedule: true,
  perType: {
    'member': { minHoursBefore: 4, allowReschedule: true },
    'visitor': { minHoursBefore: 48, allowReschedule: false }
  }
}

Policy Errors:

// Within cancellation window
throw new BadRequestException('Cancellation not allowed within cancellation window');

// Slot unavailable (for reschedule)
throw new BadRequestException('Target slot is no longer available');

Rescheduling

Endpoint

PATCH /bookings/:id/reschedule

// Request
{
  "newSlotId": "slot-789",
  "playerType": "member",         // Policy override
  "notifyPlayers": true,          // Send notifications
  "moveCartAssignment": true      // Move cart to new slot
}

// Response
{
  "id": "booking-abc",
  "status": "CONFIRMED",
  "slotId": "slot-789"
}

Reschedule Rules

• Must be same club (prevents provider desync)
• Subject to cancellation policy unless allowReschedule: true
• Moves cart assignment if configured
• Publishes teetime.booking.rescheduled event

Additional Items

Items (carts, caddies, etc.) can be added during hold:

// In HoldBookingDto
additionalItems: [
  { additionalItemId: "cart-electric", quantity: 1 },
  { additionalItemId: "caddie", quantity: 1 }
]

Item Lifecycle:

• Created with PENDING status on hold
• Updated to CONFIRMED on booking confirm
• Updated to CANCELLED on booking cancel
• Unselected items cancelled during confirm

Events

Domain Events (Outbox)

Event	Trigger
teetime.booking.confirmed	Booking confirmed
teetime.booking.cancelled	Booking cancelled
teetime.booking.rescheduled	Booking moved to new slot
teetime.booking.reminder	Scheduled reminder (24h before)

Gateway Events (WebSocket)

Event	Trigger
slot.held	Hold created
slot.booked	Booking confirmed
slot.released	Booking cancelled
booking.updated	Any status change
booking.cancelled	Cancellation

Tenant Isolation

Three-layer protection:

1. JWT Scope — User must have tenantId in claims
2. Parameter Validation — Request tenant matches user's tenant list
3. Resource Check — Slot/booking belongs to same tenant

// Throws ForbiddenException if mismatch
assertTenantAccess(user, tenantId);
assertSlotTenant(slot, tenantId, 'hold');

Response Headers

Header	Values	Description
X-Booking-Status	PENDING, CONFIRMED	Current booking status
X-Idempotent	true, false	Whether request was idempotent hit
X-Idempotency-Key	<key>	Echo of provided key

Error Handling

Error	Status	Cause
SlotUnavailableError	400	Slot already claimed
CancellationWindowError	400	Within cancellation window
ForbiddenException	403	Tenant access denied
NotFoundException	404	Booking/slot not found
ConflictException	409	Duplicate externalRef

Metrics

Metric	Description
booking_hold_latency	Hold creation time
booking_confirm_latency	Confirmation time
booking_errors	Errors by type and operation
booking_idempotent_hits	Idempotent request count