EP/myep
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c1fa08fed07a76ad5aa09e52ba28ec5cd77ba870
myep/docs/mobile-app/backend-plan.md
T

18 KiB
Raw Blame History

Mobile App — Backend Plan (myep / Symfony)

Audience: sessions working in this repository (myep, Symfony 6.4). Companion: docs/mobile-app/app-plan.md — the React Native side. That document is written to be self-contained and is meant to be copied into the RN repository, whose sessions have no access to this codebase.

1. Context

myep is the booking engine behind the separate CMS marketing site (ep-reisen.de; see BookingSessionManager::DEFAULT_RETURN_URL and CmsDataProvider). It serves:

  • Individual travel bookings — system of record is BusProNet (BPN), an external XML service reached through src/BusProNet/ApiClient.php.
  • Groups / accommodation bookings — system of record is local Doctrine entities under src/Entity/Groups/.

The public UI is Twig + HTMX + Tailwind. The admin UI under /admin is out of scope for the mobile app and stays web-only.

What we are building and why

A React Native app covering the full public surface, including the booking create flow. Drivers: App Store presence/brand and a native-feeling booking experience. A PWA was explicitly ruled out. Push notifications were not named as a driver — worth remembering, since push is normally what makes native unarguable; the payoff here rests on brand and UX.

The decision that shapes everything

The sibling project is the React Native app only. The API stays in this repository.

A second backend would recreate exactly the duplication of validation and business rules this plan exists to prevent. The API is a new src/Controller/Api/App/ namespace reusing the existing services and DTOs.

Client strategy: server-driven UI (SDUI). The server emits a JSON field schema per participant/step; RN renders it generically. Business rules never leave PHP.

Why this codebase can actually support that

The rules are already headless:

  • Validation lives on DTOs, not form types. src/Form/Model/ParticipantDto.php (21 constraints), BookingDto.php, BankAccountDto.php, RegistrationDto.php carry Assert\* plus custom App\Validator\Constraints\Participant, with validation groups (booking_create, booking_edit, strict_required, applicant_address). An API endpoint can denormalize → validate($dto, groups: [...]) and get identical results.
  • Dynamic field logic is a rules engine. src/Form/Service/ holds Contract/FieldStateProviderInterface (hidden / readonly / disabled / required / static_text), Contract/FieldOptionsProviderInterface (labels + choices), ParticipantFieldHandlerRegistry (25 handlers) and 27 reusable Condition/ classes.
  • Orchestration is in services, not controllers. BookingConfigurator (652 lines), RoomAssigner, BookingPricingAssembler, BookingSummaryAssembler, VoucherValidator, BookingEditSubmitGuard, BookingEditSubmitter. Controllers are thin — Step2Controller is 147 lines, mostly session handling and redirects.

2. The four real obstacles

Everything else is mechanical. These need design work before the increments that depend on them.

Obstacle 1 — The create flow is session-bound

src/Service/BookingSessionManager.php keys the entire create flow off $request->getSession() (booking_create, booking_create_baseline_snapshot, booking_return_url). Stateless OAuth2 clients have no session.

Fix: a server-persisted draft addressed by UUID. The pattern already exists for edit — src/Entity/BookingEditDraft.php plus BookingEditDraftManager / BookingEditDraftMerger. Generalise into a BookingDraft store and put BookingStateStoreInterface in front, with two backends: session (web, unchanged) and draft (app). Do not fork the flow logic.

Obstacle 2 — FieldStateProviderInterface leaks Symfony Form

Two leaks:

  • getBookingDtoFromForm(FormInterface $form) is pure Form coupling and belongs in a form-side adapter, not the interface.
  • getFieldState() returns Symfony form options (disabled, required, attr => ['readonly' => true]), and ParticipantFieldOptionsProvider returns choices as domain objects (Service, Pickup, Insurance) plus occasional choice_loader.

Fix: a neutral FieldDescriptor value object — name, type, label, required, readonly, disabled, hidden, staticText, choices, value. Both BookingParticipantType and the new JSON serializer consume it. Conditions and handlers are untouched.

Note the hidden vs static_text distinction documented in AbstractFieldStateProvider: hidden means excluded entirely; static_text means "show the value, don't let them edit it". The app must honour both, so FieldDescriptor has to carry them separately.

Obstacle 3 — Token lifetimes and refresh-token rotation

config/packages/league_oauth2_server.yaml sets access_token_ttl: PT10M — deliberately, since the bundle's own default is PT1H. Find out why before changing it.

TTLs are global. They live under authorization_server; the bundle has no per-client TTL. Any change affects the CMS and M2M clients too. "Raise it just for the app" is not available without a custom grant or response type.

Two values are unset and defaulted, and both matter:

  • refresh_token_ttl → P1M (1 month)
  • revoke_refresh_tokens → true, so refresh-token rotation is on

Rotation is correct security, and it is also the main source of mobile auth bugs: two requests 401 concurrently, both refresh, one rotates, the second presents a revoked refresh token and the user is logged out mid-booking. At a 10-minute TTL with step 2 firing schema refreshes per field change, this will happen. The mitigation is client-side — single-flight refresh — and it is a hard requirement in app-plan.md §4.

A longer access-token TTL does not create an unrevocable window here: persist_access_token defaults to true and BearerTokenValidator checks isAccessTokenRevoked() on every request, so tokens can be killed immediately. The usual argument for a very short TTL does not apply.

Recommendation: access_token_ttl: PT1H, refresh_token_ttl: P3M set explicitly, rotation left on. Rotation issues a fresh refresh token each time, so the refresh TTL is a sliding window — active users never re-auth, only ~3 months of true inactivity forces it. M2M clients get fewer token round-trips. Extra token rows are already handled by league:oauth2-server:clear-expired-tokens, scheduled in config/packages/zenstruck_schedule.yaml.

Settle this before the RN auth layer is written, not after.

Otherwise auth is ready: enable_auth_code_grant: true with require_code_challenge_for_public_clients: true (PKCE), and enable_password_grant: false / enable_implicit_grant: false — correct for a native app.

Obstacle 4 — BPN per-user calls need the user's plaintext password

ApiClient::getBookings(), getBooking(), getPersonalData(), updatePersonalData(), updateNewsletterRegistration() all take (string $email, string $password). src/Controller/Booking/IndexController.php supplies them via $this->crypt->decrypt($user->getPassword()) — the local User stores the BPN password RSA-encrypted (src/Security/Crypt.php).

Consequences:

  • The app must never see BPN credentials. The API layer resolves them server-side from the authenticated User, exactly as the web controllers do. This is not a change, but it must be stated so nobody "simplifies" it by proxying credentials.
  • BPN-backed user data only works for users with a local User record carrying the encrypted password. Guest flows and app-only accounts cannot read BPN bookings. Confirm how registration-via-app populates this before Increment 3.
  • The OAuth2 token identifies the user; it does not carry BPN authority. Every BPN-backed endpoint needs an explicit ownership check, not just a valid token.

3. Increments

Ordered local-data-first, BPN-last, so each stage ships something usable and the riskiest integration lands after the SDUI machinery is proven.

Increment 0 — Foundations

No user-visible feature. Backend side:

  • Register an OAuth2 client for the app (authorization_code + PKCE, native redirect URI).
  • Resolve Obstacle 3 (TTL).
  • Resolve device→DDEV access: .ddev/config.yaml has ngrok_args; ddev share is the path. Redirect URIs must be registered against whatever host the app actually calls.
  • Create docs/app-api/ with the contract skeleton and the fixtures directory.

Increment 1 — Accommodation & group offers (pilot)

Local Doctrine data, UUID-addressed, and a write endpoint already exists. Zero BPN risk.

  • Reuse GET /api/accommodation-bookings/{uuid} and POST /api/accommodation-bookings/{uuid}/accept (src/Controller/Api/AccommodationBookingController.php).
  • Add a list endpoint scoped to the authenticated user.
  • Mirrors src/Controller/Groups/Offer/IndexController.php; reuse AccommodationBookingService, AccommodationBookingBreakdownCalculator, AccommodationBookingApiResponse.
  • Validates: auth, serialization conventions, RN navigation, the fixture pipeline.

Increment 2 — Account, personal data, newsletter, registration

  • Mirror src/Controller/Account/, RegistrationController, ResetPasswordController, src/Controller/Newsletter/.
  • Reuse RegistrationDto, the PersonalDataType DTO, NewsletterManager, ProfileCompletenessChecker, and existing /api/newsletter-subscriptions, /api/userinfo, /api/crm-attributes.
  • First real SDUI use, on a small low-risk form, before betting the booking flow on it.
  • Registration here is what makes Obstacle 4 tractable — verify the encrypted-password path is populated for app-registered users.

Increment 3 — Booking read

  • GET /api/app/bookings and /api/app/bookings/{id}, mirroring src/Controller/Booking/IndexController.php (note its TravelLoader::patchBookings() enrichment step).
  • Documents/invoice, mirroring src/Controller/Booking/DownloadController.php.
  • Reuse BookingSummaryAssembler, BookingPricingAssembler, BookingEditDataLoader.
  • BPN reads only, no writes — the safe way to shake out BusProNet\Model normalization (Travel, Booking, Service, Room, Pickup, Insurance), which every later increment depends on.

Increment 4 — FieldDescriptor refactor

Pure internal refactor. No new endpoints. Covered by the existing 155 test files.

  • Introduce FieldDescriptor; split getBookingDtoFromForm out of FieldStateProviderInterface.
  • Adapt BookingParticipantType::mergeFieldState() / addDynamicFields() to consume it.
  • Add ParticipantFieldSchemaSerializer producing the JSON schema, including the dependsOn map derived from FieldConditionInterface::getDependentFields() and ParticipantFieldHandlerInterface::getDependencies().
  • Ship criterion: web behaviour byte-identical, Cypress specs green, no test file changed. A required test change means a behaviour regression.

Increment 5 — Booking edit

Before create, because drafts already exist here.

  • Endpoints over BookingEditDraftManager, BookingEditPreFlightChecker, BookingEditSubmitGuard, BookingEditSubmitter, BookingChangeTracker.
  • Participant schema endpoint from Increment 4.
  • Honour BookingMutabilityDto and BPN's aenderungmoeglich mutability rules — these already drive static_text, so SDUI inherits them.
  • Caution: the participant[0]/applicant block is on hold pending BPN vendor confirmation about the shared customer id. Do not try to resolve it here.

Increment 6 — Booking create

The full flow, last. Web routes being mirrored:

Step Web route Controller
init /bookings/create, /bookings/create/init Create/IndexController.php
1 — rooms /bookings/create/rooms (+ /refresh) Create/Step1Controller.php
2 — participants /bookings/create/participants (+ /{index}, /{index}/refresh) Create/Step2Controller.php, Step2ParticipantController.php
3 — payment /bookings/create/payment (+ /refresh) Create/Step3Controller.php
4 — confirmation /bookings/create/confirmation Create/Step4Controller.php
success /bookings/create/success Create/SuccessController.php
  • Generalise draft storage behind BookingStateStoreInterface (Obstacle 1).
  • Reuse BookingConfigurator (startFreshBooking, preselectDefaultServices, applyCreateBookingStatusRules, updateBookingStatusFromRoomSelection), RoomAssigner, ParticipantDataPrefiller, TravelDataProvider, VoucherValidator, FamilyInsuranceAvailabilityChecker.
  • Submit via BusProNet\ApiClient::createBooking() / createBookingInquiry() with BookingPayloadBuilder, exactly as Step4Controller does.
  • Every HTMX refresh route gets a JSON sibling returning recomputed schema + pricing.

Increment 7 — Discovery (scoping decision, not yet planned)

Travel/hotel browsing lives in the CMS, not here — this repo only proxies it via CmsDataProvider and /api/hotels, /api/products, /api/travels. If the app is to be a standalone entry point rather than a deep-link target, that is a second integration project and should be scoped separately.

4. Files

New (representative):

  • src/Controller/Api/App/ — one controller per resource, mirroring the public tree
  • src/Form/Service/Model/FieldDescriptor.php
  • src/Form/Service/ParticipantFieldSchemaSerializer.php
  • src/Service/BookingStateStoreInterface.php + draft-backed implementation
  • src/Entity/BookingDraft.php (generalised from BookingEditDraft) + migration
  • Normalizers for BusProNet\Model\* value objects
  • tests/Controller/Api/App/

Modified:

  • src/Form/Service/Contract/FieldStateProviderInterface.php — drop the Form-coupled method
  • src/Form/Service/Abstract/AbstractFieldStateProvider.php, CreateFieldStateProvider.php, EditFieldStateProvider.php
  • src/Form/BookingParticipantType.php — consume FieldDescriptor
  • src/Service/BookingSessionManager.php — implement the store interface
  • config/packages/league_oauth2_server.yaml — TTL, app client, scopes
  • docs/api-consumer-guide.md / docs/app-api/ — the contract

Unchanged by design: every src/Form/Service/Condition/*, every src/Form/Service/Participant*FieldHandler.php, every src/Validator/Constraints/*, and all pricing services. If an increment starts wanting to edit these, the design has drifted — stop and reconsider.

5. Working across two repos and two sessions

The RN work happens in a separate repo and a separate sandboxed session. The risk that creates is contract drift: the app session guessing at response shapes, or worse, re-deriving business rules in TypeScript because the JSON was ambiguous. That is the original duplication problem arriving through a side door.

The contract is an artifact in this repo

docs/api-consumer-guide.md already opens with "It is self-contained: no access to this codebase is required to use it." That is the format. Extend it — or split out docs/app-api/guide.md once it outgrows one file — in the same commit as the endpoint, every time.

Rule: the RN session never reads this PHP repo. Its ground truth is the guide plus fixtures. If it has to ask "what does the server send here?", the guide has a gap — fix the guide, not the app.

Fixtures decouple the sessions

Parity tests in tests/Controller/Api/App/ write their JSON responses to docs/app-api/fixtures/*.json (mirroring the existing tests/Resources/*.xml convention). Commit them. The RN session mocks against those files, so app work never waits on a deployed endpoint — and because they are test output, they cannot silently go stale.

Per-increment rhythm

  1. Backend session (here): endpoint + parity test + fixtures + guide update.
  2. Handoff: a short brief — endpoints now live, fixtures to mock, what changed in the guide since last time.
  3. App session (RN repo): build against fixtures first, then against DDEV.
  4. Joint verification: run the increment end-to-end against a real backend.

Do not run both sessions on the same increment concurrently. Overlap by one stage: while the app session builds increment N, start N+1 here.

6. Verification

Per increment:

  1. vendor/bin/phpunit — 155 existing test files, notably tests/Form/, tests/Service/, tests/BusProNet/. Increment 4 must pass with no test changes.
  2. vendor/bin/phpstan analyse and vendor/bin/php-cs-fixer fix --dry-run.
  3. npx cypress run — existing specs cover the web booking flow and guard against SDUI refactors leaking into Twig rendering.
  4. Parity tests under tests/Controller/Api/App/, asserting the JSON schema matches what BookingParticipantType builds for the same BookingDto. This is the single most valuable artifact in the project — it mechanically proves web and app share one rule set.
  5. Manual: extend the existing api.http / http-client.env.json collection per increment.
  6. End-to-end: run one booking through the RN client against a DDEV backend and confirm the BPN payload is identical to a web-flow booking with the same inputs — compare via src/Controller/Admin/Log/XmlDumpController.php.

7. Open questions before Increment 6

  • App-client access token TTL (Obstacle 3).
  • How app registration populates the encrypted BPN password (Obstacle 4), and whether guest/unauthenticated create is supported in the app as it is on the web via /bookings/create/init.
  • Draft retention and expiry policy.
  • Whether the app deep-links from the CMS site or must own discovery (Increment 7).
Reference in New Issue View Git Blame Copy Permalink