Scheduling & Bookings — Behavior

State machines

Class session (class_sessions.status, enum publish_status)

archived is in the enum but not used for class sessions (it’s the course terminal state).

Booking (bookings.status, enum booking_status)

Invariants

• One active booking per (session, member) — DB-level unique(class_session_id, membership_id) on bookings. The service additionally guards by status: existing booking in ('confirmed','waitlisted') raises BadRequestException('Already booked for this session').
• Capacity is hard — booking inserts only happen when count(confirmed) < session.capacity (or capacity is null = unlimited). waitlisted only when count(waitlisted) < session.waitlistCapacity. Check + insert run inside one SERIALIZABLE transaction.
• Org isolation — every session read joins classType → program → organizationId. Writes use a subquery to constrain the UPDATE: inArray(classSessions.id, orgScopedSessionIds) (see ClassSessionsService.update/publish/unpublish/cancel/checkIn).
• A draft cannot be booked — book() throws BadRequestException('Session is not open for booking') unless session.status === 'published'.
• Cancelled sessions cancel all bookings — cancel() runs the status update and a bulk bookings update in a single transaction.
• Unpublishing requires no active bookings — unpublish() throws BadRequestException('Cannot unpublish a session that has active bookings') if getBookingCounts returns > 0.
• Bulk-delete is soft-delete — sets deletedAt. Active bookings get cancelled. Audit row created with batchId, sessionIds, filter payload.
• Bulk-publish forces status filter to draft — caller’s filter status is overwritten regardless of input. Defense-in-depth.
• Plan-credit consistency — credit deduction (deductCreditAtomic) and refund (refundCreditAtomic) run inside the same booking transaction. Unlimited subs (plan.type='subscription' AND classCredits IS NULL) skip both. Course-type subs are excluded entirely from resolveSubscription*.
• Subscription re-verified inside the write transaction (FIT-254 review Wave C, C5) — activeSub is resolved BEFORE book()’s transaction opens; a concurrent cancel/sweep/debt-entry could move it to a terminal status in that gap. The transaction now re-selects the subscription’s own status and rejects (BadRequestException('Subscription not found or not active')) unless it’s still active/past_due, before any quota/credit/write logic runs. Flag-independent — plain correctness, not gated by booking-entitlement-sweep.
• Late cancel never refunds credit — even if allowLateCancellation=true, shouldRefund = wasConfirmed && !isLateCancellation && subscriptionId != null.
• Coach role validation — classSession.coachMembershipId only accepts memberships with role ∈ {owner, admin, coach} and status='active'.
• External (guest) coach — a session can instead carry externalCoachName: a one-time guest who is not an org member (display-only, no account or permissions). Mutually exclusive with coachMembershipId — setting one clears the other, and supplying both in one request is rejected with 400.

Golden paths

Owner: weekly schedule

1. GET /organizations/:orgId/class-types to see programs/class types.
2. POST /organizations/:orgId/sessions for each slot (default status='draft'). Pre-validated against classType + location + coach membership.
3. Optionally PUT /sessions/:id/workouts to attach pre-built workouts, or POST /sessions/:id/workouts/inline to create one in place.
4. POST /sessions/:id/publish (or POST /sessions/bulk-publish with a filter for a whole week of drafts).
5. Members now see the session inside their schedule and may book.

Coach: daily class

1. GET /organizations/:orgId/sessions?weekStart=… for the assigned slots.
2. Open session, see roster via GET /sessions/:id/bookings.
3. Tap Open check-in screen (from the dashboard session sheet or the member schedule drawer) to launch the authenticated kiosk at /[lang]/kiosk/:sessionId — full-screen QR (GET /sessions/:id/qr-token) plus a live, tappable roster for a fixed front-desk tablet.
4. Throughout class, POST /sessions/:id/check-in/:bookingId (tap on the kiosk roster) for any member who hasn’t self-checked-in.
5. Optionally POST /sessions/:id/workouts/inline to log what was actually trained that day.

Member: book + attend

1. GET /sessions?weekStart=… — receives sessions with bookingEligibility per session.
2. If eligibility.status='eligible' and the chosen plan is unblocked, POST /sessions/:id/book (server picks the single active sub automatically; passing subscriptionId explicitly for ambiguous multi-plan case).
3. Receives confirmed or waitlisted (depends on capacity). Push + email fire after commit.
4. T-30 minute reminder push lands (scheduled BullMQ job).
5. On arrival, scan QR or tap GPS check-in → POST /sessions/:id/self-checkin. selfCheckin validates: confirmed booking exists, check-in window open (isWithinCheckinWindow), QR signature valid OR GPS distance ≤ GPS_MAX_METERS.
6. Booking status → attended, checkedInAt, checkinMethod populated.

Member: cancel

1. DELETE /organizations/:orgId/sessions/:sessionId/book.
2. Service checks org.cancellationWindowHours against session.startsAt. If past deadline:
   • If allowLateCancellation=false → BadRequestException.
   • If allowLateCancellation=true → cancel proceeds, no credit refund.
3. Otherwise cancel proceeds, credit refunded (if booking had subscriptionId).
4. If the cancelled booking was confirmed, promoteFromWaitlist looks up the lowest waitlistPosition booking on the same session, flips it to confirmed, and fires the “you’re in” email.

Edge cases & error states

Side effects

Permissions matrix

isStaffRole returns true for owner|admin|coach — used for credit/quota bypass on booking but not for the booking RBAC check (members can still book).