Every hotel field now has one job. The hotel's code and aliases are import codes only (dates, lookups); a new Kalender-Code (calendar_code) decides the availability a record shows and may be shared by a house's summer and winter records. The product's "Unterkunft für Belegungskalender" is replaced by the checkbox "Kalender anzeigen" (show_calendar): a product page shows the calendar of the hotel it displays, the season still decides which one. - Price calendar, price tables, Belegungskalender, iCal feeds and /api/calendar-hotels read the Kalender-Code. A feed without one answers 404 instead of an empty calendar. - The upgrade wizard epProductsCalendarCode fills both fields from calendar_hotel, preserving today's calendars; the deploy runs it between the schema update and the switch. calendar_hotel stays in the database, so the previous release keeps working. ep:calendar-codes lists the product pages whose calendar differs from it. - HotelCodeResolver is the one lookup of import codes (date import, /api/hotel, Travelinfo); a code on several records resolves to the record whose own code it is, then the lowest uid, with a warning. Saving a code that is already another visible record's import code is refused with a message naming that record. - /api/product without hotel attaches the product's only visible Unterkunft (422 otherwise) and adds board_description, additional_services and calendar_hotel_code. Co-Authored-By: Claude Opus 5.5 <[email protected]>
122 lines
7.7 KiB
Markdown
122 lines
7.7 KiB
Markdown
# Availability and prices on product pages
|
||
|
||
TYPO3 shows three things built from contingent data. None of them talks to bpn-connect directly:
|
||
all go through **MyE&P**, which keeps a local snapshot of bpn-connect's availability and holds the
|
||
group house prices.
|
||
|
||
| What | Where | Shown for | MyE&P endpoint |
|
||
|---|---|---|---|
|
||
| **Price calendar** + price tables | product detail, tab "Termine/Preise" | products with a calendar and season **summer** (`s`) | `contingents/calendar`, `contingents/prices` |
|
||
| **Belegungskalender** (availability calendar) | product detail, sidebar | products with a calendar and season **not summer** | `contingents/availability` (+ `contingents/calendar` for the months to leave out) |
|
||
| **iCal feed** for booking portals | `https://www.ep-reisen.de/contingents/<hotel>.ical` | every hotel with a Kalender-Code | `contingents/availability` |
|
||
|
||
So every product with a calendar shows exactly one. The MyE&P side is documented in
|
||
its `docs/api-consumer-guide.md` (`EP/myep`).
|
||
|
||
## Hotel codes
|
||
|
||
Every field has one job:
|
||
|
||
| Field | Job |
|
||
|---|---|
|
||
| Hotel › **Import-Code** (`code`) and **Weitere Import-Codes** (matchcode aliases) | The BusPro codes whose imported dates land on this record, and by which `/api/hotel`, `/api/product?hotel=` and the Travelinfo page find it (`HotelCodeResolver`). A code belongs to one visible record; saving it on a second one is refused. Nothing to do with the calendars. |
|
||
| Hotel › **Kalender-Code** (`calendar_code`) | The BusPro code whose contingent this record shows: calendars, price tables, iCal feed. Empty = no calendar, the feed answers `404`. Records may share it: a house's summer record (`…GRP`) and its winter record both carry the house's code. |
|
||
| Product › **Kalender anzeigen** (`show_calendar`) | Whether the product page shows a calendar at all. |
|
||
| Product › **Saison** (`season`) | Which one: `s` the price calendar, anything else the Belegungskalender. |
|
||
|
||
**The calendar on a product page is the Kalender-Code of the hotel that page shows**: the hotel
|
||
pinned in the Produktdetail element, else the product's only Unterkunft, else the one picked in
|
||
its hotel list (`Product::getCalendarHotelFor()`).
|
||
|
||
MyE&P only understands **BusPro codes** that it syncs (e.g. `DGS`, `LPJ`, `DKS`). When BusPro has
|
||
several entries for a house (Mitterlengau: nine), only one carries the house's contingent; the
|
||
office says which one, and that is the Kalender-Code.
|
||
|
||
The product's old "Unterkunft für Belegungskalender" (`calendar_hotel`) is no longer read. The
|
||
upgrade wizard `epProductsCalendarCode` filled the new fields from it; `vendor/bin/typo3
|
||
ep:calendar-codes` lists the product pages whose calendar differs from it, until it is removed.
|
||
|
||
## Price calendar (summer)
|
||
|
||
- `Product/Detail.html`, section `Dates`, partial `Product/PriceCalendar`;
|
||
`AjaxCalendarController::priceCalendarAction` → `contingents/calendar` (status and price per
|
||
day), `priceTableAction` → `contingents/prices` for the current and the next year (loaded when
|
||
scrolled into view).
|
||
- Only works for hotels that are an **accommodation with prices** in MyE&P (summer group houses).
|
||
|
||
## Belegungskalender (winter)
|
||
|
||
- `Product/Detail.html`, section `AvailabilityCalendar`, loaded by htmx when it scrolls into view
|
||
(`intersect once`, so the hidden copy of the sidebar on the other breakpoint does not load);
|
||
`AjaxCalendarController::availabilityAction`, template `AjaxCalendar/Availability.html`,
|
||
month select `calendar_controller.js`.
|
||
- All months in one response; the select only switches between them. 12 months from the current
|
||
one, extended to the last month MyE&P has data for.
|
||
- **Months with prices are left out**: they are summer, covered by the price calendar. Only summer
|
||
months have prices today; that is the whole distinction. If `contingents/calendar` fails, all
|
||
months are shown (not cached).
|
||
- Colours as on TYPO3 10: green available (`OK`, and days without data), yellow on request
|
||
(`ON_REQUEST`), red not available (`BLOCKED`), past days grey; a status change from the previous
|
||
day is drawn as a diagonal. The `availability-*` classes are built in PHP, so they are safelisted
|
||
in `tailwind.config.js`; without that Tailwind purges them.
|
||
- Works for every hotel MyE&P syncs, with or without an accommodation (see below).
|
||
|
||
## iCal feed
|
||
|
||
- `IcalController::contingentsAction`, `IcalService`; route `/contingents/{hotel}.ical` on the
|
||
`ep-reisen` site (`config/sites/ep-reisen/config.yaml`, page 9, type 1710), `{hotel}` is the
|
||
hotel's path segment. The feed shows the record's Kalender-Code; without one it answers `404`.
|
||
- One `Unavailable` event per run of `BLOCKED` or `ON_REQUEST` days with the same status, as on
|
||
TYPO3 10.
|
||
- Never cached. When MyE&P has no availability it answers `503` with `Retry-After: 900` instead of
|
||
an empty calendar, which the portals would read as "every day free"; they keep their last import.
|
||
|
||
## Which hotels MyE&P has availability for
|
||
|
||
MyE&P syncs its snapshot from bpn-connect every 15 minutes during the day and hourly at night, for
|
||
the calendar codes of its accommodations **plus** every code in TYPO3's `/api/calendar-hotels`
|
||
(see [cms-api.md](cms-api.md)), which lists the Kalender-Code of every visible hotel record. So a
|
||
hotel offered only in winter needs nothing in MyE&P: giving the record a Kalender-Code is enough;
|
||
it is synced with the next run.
|
||
|
||
`contingents/availability` answers:
|
||
- `400` for a code that is not synced (not an accommodation, not in TYPO3's list),
|
||
- `502` when the hotel's snapshot is missing or older than 6 hours (sync failing),
|
||
- `200` with one entry per known day otherwise.
|
||
|
||
`contingents/calendar` and `contingents/prices` additionally need an accommodation with prices.
|
||
|
||
MyE&P's `GET /api/contingents/status` lists every synced code with its source, prices, last sync
|
||
and last error: the first place to look when a calendar does not load.
|
||
|
||
## Caching
|
||
|
||
- The AJAX responses (price calendar, price tables, Belegungskalender) are page-cached on the AJAX
|
||
page for at most **1 hour** (`cache_period = 3600`) and never past midnight
|
||
(`cache_clearAtMidnight`, past days must turn grey). Browsers do not cache them
|
||
(`sendCacheHeaders = 0`).
|
||
- **Errors are not cached** (`disablePageCache()`): the next visitor triggers a new attempt.
|
||
- Every AJAX URL carries a cHash (required for `tx_epproducts_ajax`), so each hotel and year has its
|
||
own cache entry.
|
||
- Entries are tagged `ep_hotel_<code>`. Nothing flushes them automatically; a deploy flushes all
|
||
caches. To refresh by hand: `vendor/bin/typo3 cache:flush --group pages`, or flush the tag via
|
||
the `CacheManager` for a single hotel.
|
||
- On top of that comes MyE&P's sync interval, so a calendar is at most about 1¼ hours behind
|
||
bpn-connect.
|
||
|
||
## When a calendar does not load
|
||
|
||
The message is "Der Kalender konnte aktuell nicht geladen werden."; the iCal feed answers `503`.
|
||
|
||
| Cause | How to tell | Fix |
|
||
|---|---|---|
|
||
| No calendar at all | product's "Kalender anzeigen" off, or the shown hotel has no Kalender-Code | tick it / set the Kalender-Code of the hotel the page shows |
|
||
| Kalender-Code is not a BusPro code (`…GRP`, `…SO`) | MyE&P `400`, bpn-connect `404` | set the house's BusPro code as Kalender-Code |
|
||
| Code not synced by MyE&P | not in `contingents/status`; MyE&P `400` | check that the hotel record is visible (then its code is in `/api/calendar-hotels`) |
|
||
| Sync failing for the hotel | `contingents/status`: `available: false`, `lastError` | MyE&P / bpn-connect |
|
||
| MyE&P unreachable or its OAuth failing | all hotels fail; TYPO3 log `EP.EpProducts.MyEP.ApiClient` | MyE&P |
|
||
| Price calendar only: no accommodation or no prices | MyE&P `400` / empty | prices are maintained in MyE&P's Groups admin |
|
||
|
||
TYPO3 logs every failed MyE&P call in `var/log/typo3_*.log` (component
|
||
`EP.EpProducts.MyEP.ApiClient`, for the iCal feed also `EP.EpProducts.Service.IcalService`).
|