myep/docs/booking-flow.md

Booking Flow Reference

Last updated: 2026-07-15

This document traces the booking create and edit flows from controller entry point through to session/DTO state. It is intended as orientation for developers unfamiliar with the flow, not as a substitute for reading the code.

---

Shared Concepts

BookingDto

The central data object for both flows. Holds room selections, participants, payment method, and travel reference. Lives in the HTTP session between requests. Has two modes: MODE_CREATE and MODE_EDIT.

BookingSessionManager

Owns all reads and writes to session-stored BookingDto instances. Also manages the baseline room snapshot used for change detection in the create flow.

BookingCreateContextFactory

Assembles the view model (BookingCreateContext) passed to create-flow templates. Handles room grouping (by-pax vs. by-room) and wires summary sidebar data.

---

Create Flow

Step 1 (room selection)
  → Step 2 (participants)
    → Step 2 sub-form (per-participant, HTMX)
  → Step 3 (payment + API pre-validation)
  → Step 4 (confirmation + final submission)
  → Success

Entry / Bootstrap

AbstractBookingCreateController::loadBookingCreateDto() is called by every step controller and delegates to BookingSessionManager::getOrCreateBookingCreateDto(). If no DTO exists in session, BookingConfigurator::startFreshBooking() loads travel data and initialises a fresh BookingDto.

Step 1 — Room Selection

Controller: Create/Step1Controller
Route: GET|POST /bookings/create/rooms

1. Load or create DTO via getOrCreateBookingCreateDto()
2. BookingSessionManager::getOrCreateBaselineSnapshot() — saves the current room selection as a comparison point for change detection
3. Render BookingCreateStep1Type form
4. On submit:
   • If room selection changed from baseline: BookingDto::resetParticipantAssignments() — clears stale assignments
   • BookingConfigurator::updateBookingStatusFromRoomSelection() — may switch booking to inquiry mode if capacity constraints require it
   • BookingSessionManager::saveBookingDto(), advance currentStep to 2
   • BookingSessionManager::clearBaselineSnapshot()
   • Redirect to Step 2

HTMX refresh (/bookings/create/refresh): processes the form without validation and returns updated room selection + summary sidebar blocks.

Step 2 — Participants (Card Overview)

Controller: Create/Step2Controller
Route: GET|POST /bookings/create/participants

1. Load DTO from session (or redirect to Step 1 if missing)
2. TravelDataProvider::enrichWithFreshAvailabilities() — refreshes room availability
3. ensureCorrectNumberOfParticipants() — syncs the BookingDto::participants array length with the room selections (e.g., 2× double room → 4 participants). Preserves existing participant data for slots that still exist.
4. ParticipantDataPrefiller::shouldPrefillApplicant() + prefillApplicantFromUser() — prefills participant[0] from user profile on first visit
5. RoomAssigner::validateAndResetInvalidAssignments() — clears any room assignments that no longer match the current room selection (handles back-navigation from Step 2 → Step 1 → Step 2)
6. RoomAssigner::assignRoomsIfNeeded() — auto-assigns participants to rooms
7. BookingConfigurator::preselectDefaultServices() — selects mandatory and auto-book services for all participants
8. BookingConfigurator::applyCreateBookingStatusRules() — re-evaluates booking status (book / inquiry / not-bookable)
9. BookingSessionManager::saveBookingDto()
10. On form submit (all participants valid): advance to Step 3, redirect

Step 2 — Individual Participant Form (HTMX)

Controller: Create/Step2ParticipantController
Routes: GET|POST /bookings/create/participants/{index} and /participants/{index}/refresh

Each participant card lazy-loads its form via HTMX. The controller:

1. Verifies the participant slot exists
2. Refreshes availability
3. Handles dummy data fill (ParticipantDataPrefiller::isDummyDataFillRequested() / fillDummyParticipant())
4. On submit: re-applies status rules, saves to session, redirects to card overview
5. ParticipantFormSupport is used for form creation options and notification draining

Step 3 — Payment + API Pre-Validation

Controller: Create/Step3Controller
Route: GET|POST /bookings/create/payment

1. Load DTO from session
2. BookingConfigurator::applyCreateBookingStatusRules()
3. On submit:
   • ApiClient::createBookingInquiry() — submits booking to API for validation without committing it
   • If inquiry fails with "nicht möglich" + "Anfrage" in message: auto-switch to inquiry mode, advance to Step 4
   • If inquiry fails otherwise: show error, stay on step
   • Price verification: BookingPriceCalculator::calculateGrandTotal() is compared against the API response total (accounting for promotional/goodwill voucher discounts and API-applied group discounts). Mismatch triggers BookingPriceMismatchAnalyzer for detailed logging.
   • On success: advance currentStep to 4, redirect

Step 4 — Confirmation + Final Submission

Controller: Create/Step4Controller
Route: GET|POST /bookings/create/confirmation

1. Load DTO from session
2. Newsletter subscription check for opt-in display
3. On submit:
   • BookingConfigurator::applyCreateBookingStatusRules()
   • ApiClient::createBooking() — final booking submission (already validated in Step 3)
   • Newsletter double-opt-in if selected
   • On success: store booking number + total in flash (for analytics), clear travel data cache, BookingSessionManager::clearBookingDto(), redirect to success page

---

Edit Flow

Entry (start)
  → Load (session or API + draft restore)
    → Participant sub-forms (HTMX, per-participant)
  → Submission

Entry

Controller: Edit/IndexController::start()
Route: GET /bookings/{id}/edit/start

Clears any existing session DTO for edit mode and invalidates the API booking cache, then redirects to the edit page. This ensures a clean load from API on every intentional re-entry.

Load

Controller: Edit/IndexController::index()
Route: GET|POST /bookings/{id}/edit

Loading is delegated entirely to BookingEditDataLoader::loadFormData():

If session DTO exists and matches the requested booking ID:

• TravelDataProvider::enrichWithFreshAvailabilities() — refreshes room availability
• TravelDataProvider::getMutabilityData() + patchMutability() — applies cached mutability state to DTO

If no session DTO (first load or after start):

initializeFromApi():

1. fetchBookingData() — ApiClient::getBooking() with 5-minute cache (tagged by user ID for bulk invalidation)
2. TravelDataProvider::getTravelData() — loads travel data (XML or snapshot)
3. TravelDataProvider::getAvailabilityData(forceRefresh: true) + patchAvailabilities() — force-refreshes availability at edit start, populates cache for subsequent loads within the session
4. TravelDataProvider::getMutabilityData(cached: true) + patchMutability() — applies which service categories are currently editable
5. BookingDataProcessor::createBookingDtoFromBooking() — hydrates BookingDto from API booking entity
6. Agency code resolved via AgencyLoader (used by field state conditions)
7. BookingChangeTracker::generateFingerprint() — sets originalFingerprint on DTO before draft is applied, so dirty detection compares against original API data
8. BookingEditDraftManager::findDraft() + applyDraftToDto() — if draft exists, merges user edits on top of fresh API data. Sets draftWasRestored = true if successful.
9. BookingSessionManager::saveBookingDto()

Back in the controller: shows "draft restored" flash if applicable, fetches booking data for surcharge/status display, renders the card overview with BookingEditContextFactory::createOverviewContext().

Individual Participant Form (HTMX)

Controller: Edit/ParticipantController
Routes: GET|POST /bookings/{id}/edit/participants/{index} and /{index}/refresh

Per-participant forms are lazy-loaded, matching the create flow pattern.

1. BookingEditContextFactory::prepareBookingDto() — refreshes availabilities on the DTO travel object
2. ParticipantFormSupport — form creation, notification draining
3. On submit: BookingSessionManager::saveBookingDto() + BookingEditDraftManager::saveDraft() — persists participant edits to both session and draft

Submission

Service: BookingEditSubmitter::handleSubmission()
Called from Edit/IndexController on valid form submit.

1. Invalidate API cache, fetch fresh booking data
2. Force-refresh mutability data (TravelDataProvider::getMutabilityData(forceRefresh: true)) and patch DTO travel
3. BookingEditSubmitGuard::reconcileImmutableCategories() — reverts any DTO fields that have become immutable since the session was loaded. Shows flash if anything was reverted.
4. ApiClient::updateBooking() — submit
5. On success: invalidate cache again, BookingSessionManager::clearBookingDto(), BookingEditDraftManager::deleteDraft()

Other Edit Routes

Route	Action
GET /bookings/{id}/edit/reload	Shows confirmation modal
POST /bookings/{id}/edit/reload	Clears session + deletes draft, reloads from API
GET /bookings/{id}/edit/cancel	Clears session, preserves draft, redirects to booking list

The distinction between reload and cancel is intentional: cancel keeps the draft so the user can return to their changes later; reload discards everything.

---

Key Invariants

• currentStep on the DTO gates forward navigation in create mode; controllers redirect to the current step if a higher step is requested directly.
• The original fingerprint is set before draft application in edit mode. Dirty detection (BookingChangeTracker::isDirty()) always compares the live session DTO against the original API state, not against the draft.
• Mutability is always patched from fresh or cached data before rendering. The DTO travel object is the authoritative source of which fields are editable at render time.
• Drafts survive cancel but not reload, and are deleted on successful submission.