163 lines
9.0 KiB
Markdown
163 lines
9.0 KiB
Markdown
# Contingent API with XML Caching (Crawler-Based) — Plan (Updated)
|
||
|
||
## 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.
|
||
|
||
## 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.
|
||
|
||
## 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`.
|
||
|
||
## 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.
|
||
|
||
## Detailed Implementation Plan
|
||
|
||
### 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.
|