EP/myep
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: update documentation files

Browse Source
This commit is contained in:
Björn Fromme
2026-04-22 11:33:08 +02:00
parent d5dfb6c550
commit df7885ca1c
2 changed files with 32 additions and 277 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/contingent-api-plan.md
+32 -155
View File
@@ -1,162 +1,39 @@
# Contingent API with XML Caching (Crawler-Based) — Plan (Updated)
# Contingent API Status
## Summary
Implement a cache-only contingent API backed by XML files in `var/xmlexportzimmer`, using Symfony cache (tag-aware) and Flysystem. Parsing uses DOM/Crawler and caches DTO arrays only. Add loader/parser/services/controllers and integrate cache invalidation into the existing XML sync flow. Provide endpoints for contingents, rooms, and calendar events.
The contingent API is implemented on `master`. It serves cached availability data from `HotelZimmer_*.xml` files in `var/xmlexportzimmer`, using Flysystem and the tag-aware `bpn.cache` pool. XML sync now covers both travel and contingent datasets, invalidates `xml-sync` tagged cache entries, and logs dataset transfer errors without aborting the command.
## Current Status (feature/contingents-api)
- Implemented: parser, loader, data service, controller endpoints, XML sync for contingent dataset, and tests for parser/loader/service/controller.
- Implemented: hotel/date reference resolution (`hotelRef`/`dateRef`) with numeric passthrough and code mapping.
- Implemented: root-link one-hop behavior and BelKal control-room override semantics.
- Implemented: contingent caching via `bpn.cache` with `xml-sync` tagging strategy.
- In progress: enrich rooms payload with booking URL and additional travel metadata fields.
## Implemented
- OAuth-protected endpoints:
- `GET /api/contingents?hotelRef={hotelRef}&dateRef={dateRef}`
- `GET /api/contingents/rooms?hotelRef={hotelRef}&dateRef={dateRef}&dateFrom={Y-m-d}&dateTo={Y-m-d}`
- `GET /api/contingents/calendar?hotelRef={hotelRef}&dateFrom={Y-m-d}&dateTo={Y-m-d}`
- `hotelRef` and `dateRef` accept numeric IDs or business codes; date codes are sanitized before lookup.
- Parser/loader/service/controller flow is implemented via `ContingentParser`, `ContingentLoader`, `ContingentDataService`, and `ContingentController`.
- Room responses include per date + room availability, pricing, status, and `bookingUrl`.
- BelKal control-room rows override date status and set room availability to `0` for affected dates.
- Room-level contingent links and one-hop root-level file links are supported.
- `app:bpn:xml-sync` syncs travel and contingents, invalidates `xml-sync` cache tags, and refreshes travel snapshots only when travel data synced.
- `app:bpn:xml-cache-invalidate` checks both travel and contingent local XML exports.
## Public API / Interface Changes
- **New endpoints (OAuth-protected)**:
1. `GET /api/contingents?hotelRef={hotelRef}&dateRef={dateRef}`
- Returns: object keyed by date with `{ date, minNights, total, capacity }`.
2. `GET /api/contingents/rooms?hotelRef={hotelRef}&dateRef={dateRef}&dateFrom={Y-m-d}&dateTo={Y-m-d}`
- Returns: **per date + room** rows with pricing and travel metadata.
3. `GET /api/contingents/calendar?hotelRef={hotelRef}&dateFrom={Y-m-d}&dateTo={Y-m-d}`
- Returns per date `{ date, status, pax, available }` (status is worst-case across rooms).
- **New config**:
- `.env`: `XML_EXPORT_CONTINGENTS_PATH="%kernel.project_dir%/var/xmlexportzimmer"`
- `config/packages/flysystem.yaml`: `xml_export_contingents.storage` and `xml_source_contingents.storage`.
- **New cache pool usage**:
- `bpn.cache` used for contingent file map + hotel cache entries, tagged with `xml-sync`.
## Config
- `.env` defines `XML_EXPORT_CONTINGENTS_PATH` and `SFTP_XML_EXPORT_CONTINGENTS_*`.
- `config/packages/flysystem.yaml` defines:
- `xml_export_contingents.storage`
- `xml_source_contingents.storage`
- `config/services.yaml` wires contingent storage, `bpn.cache`, and `APP_BASE_URL` for booking URL generation.
## Key Decisions Locked
- **Parsing approach**: DOM/Crawler (SimpleXML/Crawler), not XMLReader.
- **Cache contents**: DTO arrays (scalars + `\DateTimeImmutable`) only. No SimpleXML/Crawler objects in cache.
- **Rooms response shape**: **per date + room** (not aggregated).
- **BelKal override**:
- BelKal is a control room that can override availability.
- If BelKal is A/S on a date, **all rooms** on that date are treated as on-request/blocked.
- **Root-level link**: one hop only; do not chain if linked file also has link attribute.
- **Room-level link**: link only affects which `zimmer[@idbuspro]` node is used for capacity.
## Behavior Notes
- Missing contingent XML returns empty data.
- Unknown travel/date or hotel/date mismatches return `404` from the API.
- Invalid date ranges or formats return `400`.
- Dataset transfer failures are shown and logged as warnings, but `app:bpn:xml-sync` still completes with exit code `0`.
## Detailed Implementation Plan
## Remaining TODOs
- Decide whether room responses still need travel metadata fields such as `summer`, `servicesIncluded`, and `servicesOptional`; these are not currently implemented.
- If the XML files grow materially or cold-cache parsing becomes slow, revisit whether `ContingentParser` should move from DOM/Crawler parsing to a streaming parser.
- Validate the deployed contingent SFTP environment variables before enabling scheduled sync in production.
### 1) Configuration
1. Add `XML_EXPORT_CONTINGENTS_PATH` to `.env`.
2. Add Flysystem storage in `config/packages/flysystem.yaml`:
- `xml_export_contingents.storage` with `directory: '%env(resolve:XML_EXPORT_CONTINGENTS_PATH)%'`.
- `xml_source_contingents.storage` for SFTP contingent source.
3. Wire service injection in `config/services.yaml`:
- Bind `xml_export_contingents.storage` into `ContingentLoader`.
- Inject `@bpn.cache` explicitly into `ContingentLoader` and `BpnXmlSyncCommand`.
### 2) Parser (Crawler)
**New** `src/BusProNet/XmlParser/ContingentParser.php`
Responsibilities:
- Parse a single `HotelZimmer_*.xml` (string or Crawler root) and return:
- Room types: `{ idBusPro, code, pax, label, controlRoom, link }`
- Contingent rows (DTO arrays) with:
- `date` (`\DateTimeImmutable`)
- `roomCode`, `roomLabel`
- `pax`, `available`, `status` (`OK|ON_REQUEST|BLOCKED`)
- `minPrice`, `minNights`
- `additionalNightMinPrice`, `additionalNightMinNights`
- Logic:
- Room types from `unterbringungen/unterbringung`.
- Skip `code=PDGS`.
- Control room is `code=BelKal`.
- For each date node (`kapazitaeten/kapazitaet @termin d.m.Y`) and room type, resolve `zimmerliste/zimmer` by id:
- Use `roomType.link ?? roomType.idBusPro`.
- BelKal rows:
- status `A` => ON_REQUEST
- status `S` => BLOCKED
- Non-BelKal rows:
- `pax = kontingent * pax_max`
- `available = frei * pax_max`
- Return arrays (no XML objects) to be cache-safe.
### 3) Loader (Cache + Flysystem)
**New** `src/BusProNet/XmlLoader/ContingentLoader.php`
Responsibilities:
- Extend `AbstractLoader`.
- `generateFilesMap()`:
- List `HotelZimmer_*.xml` in `xml_export_zimmer.storage`.
- Build mapping `hotelId => filename`.
- Cache as `bpn_contingent_files` for 3h on `bpn.cache`.
- `loadByHotelId(int $hotelId): array`:
- Use file map to find filename; return `[]` if missing.
- Read XML content.
- **Root-level link**: if root has `idbuspro_kontingent_aus`, load that file **instead** (one hop only).
- Parse using `ContingentParser`.
- Cache result in `bpn.cache` as `contingent_hotel_{hotelId}` TTL 3600, tagged `xml-sync`.
### 4) Data Service (No DB)
**New** `src/Service/ContingentDataService.php`
Dependencies: `ContingentLoader`, `TravelLoader`, optional booking URL base.
Functions:
- `getAvailableContingents(int $hotelId, int $dateId): array`
- Load travel via `TravelLoader->loadById($dateId)` to get `dateFrom/dateTo`.
- Load contingents by hotel.
- Filter within range (inclusive).
- Aggregate per date: `minNights` (min), `total` (sum of available), `capacity` (sum pax).
- **BelKal override**: if BelKal is A/S on a date, mark all rooms on that date as on-request/blocked for outputs.
- `getAvailableRooms(string $dateFrom, string $dateTo, int $hotelId, int $dateId, string $myEpUrl = ''): array`
- Filter contingents by range; build **per date + room** rows.
- Compute `priceForSelection = minPrice + max(0, nights - minNights) * additionalNightMinPrice`.
- Add bookingUrl (see below).
- Add `summer/servicesIncluded/servicesOptional` if travel metadata available; otherwise empty.
- **BelKal override**: if BelKal is A/S on a date, force each row’s `status` to ON_REQUEST/BLOCKED (and optionally available to 0 if desired by frontend).
- `getCalendarEvents(int $hotelId, string $dateFrom, string $dateTo): array`
- Aggregate per date:
- Exclude BelKal rows from `pax` and `available`.
- Status is worst-case across **all** rows (BelKal included).
- Return `{ date, status, pax, available }`.
### 5) Booking URL Utility
- Add `src/BusProNet/Utility/BookingUrlUtility.php`.
- URL format: `<base>/bookings/create?date_id={dateId}&hotel_id={hotelId}`.
- Base resolution: use optional `my_ep_url` when provided, otherwise `APP_BASE_URL` (default `https://my.ep-reisen.de`).
### 6) Controller + Routes
**New** `src/Controller/Api/ContingentController.php`
- Base: `#[Route('/api')]` and `#[IsGranted('ROLE_OAUTH2_API')]`.
- Canonical query routes:
1. `/api/contingents/calendar` with query `hotelRef`, `dateFrom`, `dateTo`
2. `/api/contingents` with query `hotelRef`, `dateRef`
3. `/api/contingents/rooms` with query `hotelRef`, `dateRef`, `dateFrom`, `dateTo`
- Reference resolution:
- Numeric `hotelRef` / `dateRef` values are treated as IDs.
- Non-numeric `hotelRef` is mapped as hotel code.
- Non-numeric `dateRef` is sanitized (`-` and `/` removed, uppercase) and mapped as date code.
### 7) Cache Invalidation on Sync
Update `src/Command/BpnXmlSyncCommand.php`:
- Inject `TagAwareCacheInterface $bpnCache` (bind to `@bpn.cache`).
- In `invalidateCaches()`:
- Invalidate `xml-sync` tag after successful sync.
- Sync now covers two datasets (`travel` and `contingents`) in one command run.
## Edge Cases & Failure Modes
- Missing `HotelZimmer_{hotelId}.xml`: loader returns empty array; API returns empty result or 404 (match existing pattern).
- Root-level link missing target file: return empty array (optionally log), no fallback to original.
- Travel not found for `dateId`: return 404.
- Hotel not in travel: optionally validate using TravelLoader mapping and return 404.
- Date parsing: `d.m.Y` -> `\DateTimeImmutable` with server timezone.
## Tests / Scenarios
1. **Parser – happy path**: room types, capacities, prices parsed correctly.
2. **Parser – room link**: `idbuspro_kontingent_aus` on room type uses linked id for `zimmerliste/zimmer`.
3. **Parser – root link**: root `idbuspro_kontingent_aus` loads alternate file exactly once.
4. **Parser – BelKal override**:
- BelKal A/S forces all rooms on that date to on-request/blocked.
- Calendar status uses BelKal and sums exclude BelKal.
5. **Service – getAvailableContingents**: correct per-date aggregation.
6. **Service – getAvailableRooms**: per date + room rows with correct pricing.
7. **Calendar**: worst-case status across rooms, with correct sums excluding BelKal.
8. **Cache**: entries tagged and invalidated after `app:bpn:xml-sync`.
## Performance Notes
- DOM/Crawler parsing should be acceptable for ~7MB XMLs, especially with cached DTOs.
- If XML size grows materially (>20-30MB) or cold-cache concurrency spikes, consider adding an XMLReader streaming parser as a future enhancement.
## Assumptions / Defaults
- `hotelRef` accepts either numeric `hotelId` (`idbuspro`) or hotel code.
- `dateRef` accepts either numeric `dateId` or date code.
- Rooms endpoint returns per date + room rows.
- Return structure follows existing API patterns (`TravelController`, `PickupController`) for HTTP status and JSON formatting.
## Verification
- Covered by parser, loader, data service, controller, booking URL, XML sync, and cache invalidation tests.
- Current verification command: `php bin/phpunit`.