Files
typo3-13/docs/calendars.md
T
frommeandClaude Opus 5.5 5455973dba feat: Kalender-Code replaces the product's calendar hotel
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]>
2026-11-16 17:18:00 +01:00

122 lines
7.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`).