From bd2d8b58a32019a368f0bdfcc49cfca2a2f89cae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Fromme?= Date: Wed, 15 Jul 2026 18:00:30 +0200 Subject: [PATCH] chore: update documentation --- docs/body-dimensions-transition-plan.md | 2 + docs/booking-flow.md | 6 +-- docs/technical-documentation.md | 60 ++++++++++++++++++++----- 3 files changed, 54 insertions(+), 14 deletions(-) diff --git a/docs/body-dimensions-transition-plan.md b/docs/body-dimensions-transition-plan.md index 690e293..5d5fed5 100644 --- a/docs/body-dimensions-transition-plan.md +++ b/docs/body-dimensions-transition-plan.md @@ -1,5 +1,7 @@ # Body Dimensions Transition Plan (Stakeholder Draft) +> **STATUS (verified 2026-07-15): NOT IMPLEMENTED.** `src/Form/BodyDimensionsType.php` still declares `height`, `shoeSize`, and `weight` as `IntegerType` fields, and `src/Validator/Constraints/ParticipantValidator.php` has no regex/legacy-format handling — only numeric range checks. This plan has not been acted on. + ## Goal Prevent edit-form failures for existing bookings while we transition from legacy body-dimension values to a better long-term field model. diff --git a/docs/booking-flow.md b/docs/booking-flow.md index 2f01706..0d350c5 100644 --- a/docs/booking-flow.md +++ b/docs/booking-flow.md @@ -1,6 +1,6 @@ # Booking Flow Reference -Last updated: 2026-04-16 +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. @@ -35,7 +35,7 @@ Step 1 (room selection) ### Entry / Bootstrap -`BookingExceptionHandlerTrait::getOrCreateBookingCreateDto()` is called by every step controller. If no DTO exists in session, it calls `BookingConfigurator::startFreshBooking()` which loads travel data and initialises a fresh `BookingDto`. +`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 @@ -62,7 +62,7 @@ HTMX refresh (`/bookings/create/refresh`): processes the form without validation 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::shouldPrepopulateApplicant()` + `prepopulateApplicantFromUser()` — prefills participant[0] from user profile on first visit +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 diff --git a/docs/technical-documentation.md b/docs/technical-documentation.md index eac7a6b..91aae2a 100644 --- a/docs/technical-documentation.md +++ b/docs/technical-documentation.md @@ -125,8 +125,6 @@ Delete Draft on Success ``` src/ -├── Admin/ # EasyAdmin custom fields -│ └── Field/JsonDataField.php ├── BusProNet/ # BusProNet API integration layer │ ├── ApiClient.php # Main API client │ ├── Constants.php # Service tokens and constants @@ -134,12 +132,12 @@ src/ │ ├── DataProvider/ # Data providers (countries) │ ├── Exception/ # API-specific exceptions │ ├── Form/ # Form choice loaders -│ ├── Model/ # Data models (39 classes) +│ ├── Model/ # Data models (41 classes) │ ├── Traits/ # Shared traits │ ├── Utility/ # Helper utilities │ ├── XmlLoader/ # Cached XML file loaders -│ └── XmlParser/ # XML response parsers (28 classes) -├── Command/ # CLI commands (9 commands) +│ └── XmlParser/ # XML response parsers (29 classes) +├── Command/ # CLI commands (15 commands) ├── Controller/ # HTTP controllers │ ├── Account/ # Account management │ ├── Admin/ # EasyAdmin controllers @@ -151,6 +149,7 @@ src/ │ ├── RegistrationController.php │ ├── ResetPasswordController.php │ └── SecurityController.php +├── Email/ # Transactional email builders ├── Entity/ # Doctrine entities │ ├── User.php │ ├── LogEntry.php @@ -160,16 +159,19 @@ src/ ├── Form/ # Form system │ ├── Model/ # DTOs (BookingDto, ParticipantDto, etc.) │ ├── Service/ # Field handlers & conditions -│ │ └── Condition/ # 22+ condition classes +│ │ └── Condition/ # 25 condition classes │ ├── DataTransformer/ # Form data transformers │ └── Extension/ # Form extensions (XSS protection) ├── Htmx/ # HTMX utilities ├── Logger/ # Custom Monolog handlers/processors +├── Menu/ # Navigation menu builders +├── Message/ # Messenger message classes +├── MessageHandler/ # Messenger message handlers ├── Model/ # Application models ├── Repository/ # Doctrine repositories ├── Security/ # Authentication & authorization │ └── Voter/ # Custom voters -├── Service/ # Business logic services (21 services) +├── Service/ # Business logic services (43 services) ├── Twig/ # Template extensions └── Validator/ # Custom validation constraints └── Constraints/ # Constraint classes @@ -196,7 +198,7 @@ assets/ ├── app.js # Main entry point ├── bootstrap.js # Stimulus initialization ├── loading.js # HTMX loading indicator -├── controllers/ # Stimulus controllers (10) +├── controllers/ # Stimulus controllers (14) ├── styles/ # TailwindCSS styles │ ├── app.css # Main stylesheet │ └── components/ # Component styles @@ -1001,6 +1003,10 @@ public function deleteExpiredDrafts(): int; | `toast_controller` | Toast notifications via Toastify | | `tooltip_controller` | Tooltips via Tippy.js | | `backbutton_controller` | Browser back navigation | +| `data_layer_controller` | Pushes analytics events to the data layer | +| `mobilenav_controller` | Mobile navigation menu | +| `password_reveal_controller` | Show/hide password input | +| `sidebar_menu_controller` | Sidebar menu state | ### 9.2 HTMX Integration @@ -1121,6 +1127,22 @@ php bin/console app:bpn:xml-sync [--force|-f] [--dry-run] Synchronizes XML export files from remote SFTP. Invalidates caches on completion. +#### app:bpn:refresh-travel-snapshot + +```bash +php bin/console app:bpn:refresh-travel-snapshot +``` + +Refreshes active travel snapshots using extended availability data. + +#### app:bpn:xml-cache-invalidate + +```bash +php bin/console app:bpn:xml-cache-invalidate +``` + +Invalidates BPN XML caches when local `uebertragung.info` changes. + ### 10.2 Maintenance Commands #### app:draft:cleanup @@ -1185,6 +1207,22 @@ Creates or deletes the Mailjet `unsub` callback for `POST /webhooks/mailjet/news - `register` prints the API response payload so you can note the callback ID. - `remove` and `deactivate` require the callback ID returned by Mailjet. +#### app:db:anonymize + +```bash +php bin/console app:db:anonymize +``` + +Anonymizes personal data in the local database. + +#### app:log-entry:backfill-error-codes + +```bash +php bin/console app:log-entry:backfill-error-codes +``` + +Backfills the `error_code` column from extra data in existing log entries. + ### 10.3 Setup Commands #### app:crypto:generate-keys @@ -1288,7 +1326,7 @@ This section documents known API behaviors and the solutions implemented. **Solution:** Automatic retry with configurable attempts (default: 3) and delay (default: 1s). -**Location:** `src/BusProNet/ApiClient.php:625-659` +**Location:** `src/BusProNet/ApiClient.php:646` (`executeWithRetry`) ```php private function executeWithRetry(callable $operation, ?string $type = null): mixed @@ -1347,7 +1385,7 @@ public function shouldProcess(...): bool **Solution:** Exclude `personId` and `addressId` from create mode payload. -**Location:** `src/BusProNet/DataProcessor/BookingPayloadBuilder.php:247-249` +**Location:** `src/BusProNet/DataProcessor/BookingPayloadBuilder.php:275,313` ### 13.6 Personal Data Mutability Flag @@ -1365,7 +1403,7 @@ public function shouldProcess(...): bool **Solution:** Inject synthetic option with ID '0' that satisfies validation but is excluded from API transmission. -**Location:** `src/BusProNet/Model/Insurance.php:19-26` +**Location:** `src/BusProNet/Model/Insurance.php:26` (constant), `:201` (`isNoInsurance()`) ```php public const NO_INSURANCE_ID = '0';