# 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.