feat: unfiltered product export for the website's catalogue import

2026-09-30 12:19:10 +02:00
1 parent 272c811f4f
commit 1d42565a84
@@ -12,8 +12,8 @@ A Symfony application exposing a read-mostly JSON API under the `/api` prefix. A
 - Enabled grants: **client_credentials**, **authorization_code** (PKCE required for public clients), **refresh_token**. Password and implicit grants are disabled.
 - Access token TTL is **10 minutes** for every grant.
  Do not hardcode it — read `expires_in` from the token response, it is authoritative and may be tuned.
-  A token can therefore expire part-way through a long page walk of `GET /api/exports/travels`; re-request one on
-  401 and resume at the page you were on. At the default `perPage=500` the whole export is a single page today.
+  A token can therefore expire part-way through a long page walk of `GET /api/exports/*`; re-request one on
+  401 and resume at the page you were on. At the default `perPage=500` either export is a single page today.
 - Available scopes: `email`, `id`, `profile`, `roles`, `api`. Default scope if none requested: `email`.
 - Each granted scope maps to a role `ROLE_OAUTH2_<SCOPE_UPPERCASE>` (e.g. scope `api` → `ROLE_OAUTH2_API`).
 - Send the token as `Authorization: Bearer <access_token>`.
@@ -52,7 +52,7 @@ There is no single error envelope; three shapes occur:

 Validation failures on endpoints using mapped query strings / payloads (`/api/contingents/*`, `/api/exports/*`, `/api/newsletter-subscriptions`) return **400** with Symfony's constraint-violation body. Missing/invalid token yields **401**; insufficient scope yields **403**.

-`GET /api/exports/travels` deliberately uses real status codes throughout and never the 200-with-an-`error`-key shape: a failure there is a 5xx, so retry logic can key on the status code alone.
+`GET /api/exports/*` deliberately uses real status codes throughout and never the 200-with-an-`error`-key shape: a failure there is a 5xx, so retry logic can key on the status code alone.

 The HTTP methods listed below are the intended ones. Several read routes do not restrict methods server-side; clients should still use `GET` for them.

@@ -148,7 +148,7 @@ This is a full overwrite, not a merge.
 Bulk export of every travel date × hotel pair with its boarding points resolved, for clients that mirror the
 disposition locally. One request replaces a walk over `GET /api/travels` plus a per-pair detail call.

-This is the only paginated endpoint and the only one with a `meta` envelope.
+The two `/api/exports/*` endpoints are the only paginated ones and the only ones with a `meta` envelope.

 It sits under `/api/exports`, not `/api/travels`, on purpose: `/api/travels/{dateCode}` accepts an
 arbitrary string, so an export hung off that collection would share a namespace with every date code.
@@ -246,6 +246,149 @@ same value `GET /api/last-update` reports, as ISO-8601 — or `null` if it could
 replace the cached copy while you are walking the pages; if `sourceGeneratedAt` differs from the value you saw on
 page 1, you have stitched two exports together. Discard what you have and restart from page 1.

+#### `GET /api/exports/products` — scope `api`
+
+Bulk export of every travel date × hotel pair with its **whole record**, for clients that import the product
+catalogue: rooms with prices and availability, the pseudo price, all selection groups, the three service lists,
+boarding points with prices, and the guide. Same grain, paging, query parameters, `meta` envelope, status codes and
+page-consistency rule as `GET /api/exports/travels` above; only the rows differ.
+
+**Unfiltered on purpose.** Nothing is dropped or rewritten for you. Return-leg (`RUECK`) services, `EIN` services,
+`Buchungsstop` rooms and services, rooms without a price and boarding points with id `0` are all emitted. Which of
+them a website shows, and how, is the client's rule, not this endpoint's.
+
+At current volumes the export is ~420 rows and ~3.8 MB of JSON (a row is 4–24 kB), so the default `perPage=500`
+returns it in one page.
+
+```json
+{
+  "data": [
+    {
+      "product": { "code": "DKIWE", "busProId": 1127 },
+      "date": {
+        "code": "DKIWE041226",
+        "busProId": 12437,
+        "from": "2026-12-04",
+        "to": "2026-12-06",
+        "type": "F"
+      },
+      "hotel": { "code": "DKIWEKT", "busProId": 222931 },
+      "pseudoPrice": null,
+      "selectionGroups": [
+        {
+          "busProId": 7,
+          "label": "Leistungen Skipass",
+          "selections": [ { "busProId": 92, "label": "3 Tage Skipass" } ]
+        }
+      ],
+      "transportServices": [
+        { "busProId": 193804, "subType": "PKW", "label": "Eigene Anreise mit Rabatt", "price": -50, "status": "Frei", "direction": "HIN" }
+      ],
+      "dateServices": [
+        { "busProId": 193805, "subType": "SON", "label": "Keycard-Pfand (Pflichtabgabe)", "price": 5.4, "status": "Frei", "direction": null }
+      ],
+      "hotelServices": [
+        { "busProId": 193805, "subType": "SON", "label": "Keycard-Pfand (Pflichtabgabe)", "price": 5.4, "status": "Frei", "direction": null }
+      ],
+      "rooms": [
+        {
+          "busProId": 74,
+          "code": "MBZET",
+          "label": "Bett im Mehrbettzimmer Etagendusche/-WC",
+          "category": "GR",
+          "minPax": 1,
+          "maxPax": 1,
+          "nights": 2,
+          "price": 229,
+          "available": 24,
+          "status": "Frei",
+          "boardCode": "Lt. Auss.",
+          "boardBusProId": 2
+        }
+      ],
+      "pickups": [
+        {
+          "busProId": 4,
+          "code": "FRA-Route",
+          "city": "Frankfurt",
+          "street": "Flughafen (P36 zwischen Terminal 1 und 2)",
+          "price": 5.9,
+          "datetime": "2026-12-03T23:30:00+01:00"
+        }
+      ],
+      "guide": null
+    }
+  ],
+  "meta": {
+    "page": 1,
+    "perPage": 500,
+    "total": 419,
+    "totalPages": 1,
+    "skipped": 0,
+    "pickupsWithoutMasterData": 0,
+    "sourceGeneratedAt": "2026-09-30T11:11:01+02:00",
+    "generatedAt": "2026-09-30T14:05:00+02:00"
+  }
+}
+```
+
+**Row identity.** `(date.busProId, hotel.busProId)` is unique across the whole export — upsert on that pair.
+`product.code` and `hotel.code` are verbatim and suitable for matching against your own records. No row depends on
+hotel master data, so `skipped` counts only travel dates whose dates could not be parsed.
+
+**Types.**
+
+- Every price is a JSON **number** in euros, never a formatted string: `229`, `5.4`, `-50`. A price the source does
+  not state is `null`, and `0` means a stated zero ("included"). Do not treat the two alike.
+- `selectionGroups`, `selections`, `transportServices`, `dateServices`, `hotelServices`, `rooms` and `pickups` are
+  always arrays, possibly empty, never null. `pseudoPrice` and `guide` are nullable.
+- All arrays are in **source order**. Sort for display yourself; do not depend on the order.
+
+**Rooms.** One entry per room offered on the date at that hotel.
+
+- `code` is trimmed. `available` is a count of **rooms**, not persons — person capacity is `available × maxPax`.
+- `status` is passed through verbatim: `Frei`, `Anfrage` or `Buchungsstop`.
+- `available`, `price`, `minPax`, `maxPax`, `nights` and `boardBusProId` are `null` where the source leaves them
+  empty.
+
+**`pseudoPrice`.** A struck-through comparison price for the date, carried upstream by a pseudo room with code
+`PDGS`. It is lifted onto the row and never appears in `rooms`. It is `null` in most rows.
+
+**Services.** Three lists, deliberately kept apart:
+
+- `transportServices` — the date's transport services (bus, own arrival, train …). Both directions.
+- `dateServices` — the date's general services.
+- `hotelServices` — the services listed on this hotel for this date. Upstream repeats most date-level services
+  here, possibly with hotel-specific prices, so expect overlap with `dateServices`. If you merge the two, key by
+  `busProId`: it identifies a service across both lists.
+
+`subType` is the upstream service subtype (`BUS`, `PKW`, `BAH`, `SON`, `SPA`, `VER`, `EIN`, …), passed through.
+`direction` is `HIN` or `RUECK` on transport services and `null` on general ones. A negative `price` is a discount,
+such as for arriving by car.
+
+**Selection groups.** Every group on the date, not only the `Leistungen *` ones. Match groups by `busProId`, not by
+`label`: labels are editorial and can be renamed upstream. The ids of the included-services groups are stable:
+
+| `busProId` | Label |
+|---|---|
+| 7 | Leistungen Skipass |
+| 8 | Leistungen Sonstige |
+| 71 | Leistungen Verpflegung |
+| 85 | Leistungen Übernachtung |
+| 86 | Leistungen Programm |
+| 87 | Leistungen Kurse |
+| 89 | Leistungen Events |
+| 90 | Leistungen Transport |
+
+**Pickups.** Outbound boarding points only, in source order. `datetime` follows the same resolution rules as in
+`GET /api/exports/travels`, including rolling a bare time past midnight onto the next day. There is no separate
+`time` field; format `datetime` for display. `price` is the outbound boarding surcharge exactly as upstream states
+it: `null` where upstream states none. It is not levelled against the return leg. An id absent from
+`GET /api/pickups` is emitted with `code`, `city` and `street` null and counted in `pickupsWithoutMasterData`. An id
+of `0` is emitted as-is but not counted.
+
+**`guide`.** `{ "name": …, "phone": … }` for the first outbound bus service that has a guide assigned, else `null`.
+
 ---

 ### Travels