From 0ff312c0c086320ebec892925511684e814d6ed2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Fromme?= Date: Tue, 10 Nov 2026 14:47:16 +0100 Subject: [PATCH] feat: add bookable flag to product export rooms --- docs/api-consumer-guide.md | 8 ++++ docs/chatbot-mcp.md | 9 +++-- src/BusProNet/Model/Room.php | 13 +++++++ src/BusProNet/Model/Travel.php | 6 +-- .../XmlParser/ProductExportParser.php | 12 ++++-- src/Chatbot/TripCatalog.php | 8 ++-- src/Model/Chatbot/TravelDateFacts.php | 39 +++++++++++++------ tests/BusProNet/Model/RoomTest.php | 33 ++++++++++++++++ tests/Chatbot/TripCatalogTest.php | 24 +++++++++++- tests/Service/ProductExportBuilderTest.php | 2 + 10 files changed, 126 insertions(+), 28 deletions(-) create mode 100644 tests/BusProNet/Model/RoomTest.php diff --git a/docs/api-consumer-guide.md b/docs/api-consumer-guide.md index 62976245..c721dada 100644 --- a/docs/api-consumer-guide.md +++ b/docs/api-consumer-guide.md @@ -268,6 +268,13 @@ page-consistency rule as `GET /api/exports/travels` above; only the rows differ. `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. +**Which rooms can be booked.** Each room carries `bookable`, the one derived field: `true` exactly when the +booking flow offers the room for a new booking. That is status `Frei` with `available` above 0. A room on request +(`Anfrage`) is not bookable even with rooms left, because booking it would only produce an inquiry; neither is a +room with `available` 0 or `null`. Show a room that is not bookable as sold out and do not count it towards places +or the "ab" price. Read `bookable` rather than deriving it from `status` and `available`, so a change to the rule +reaches you without a client change. + 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. @@ -313,6 +320,7 @@ returns it in one page. "price": 229, "available": 24, "status": "Frei", + "bookable": true, "boardCode": "Lt. Auss.", "boardBusProId": 2 } diff --git a/docs/chatbot-mcp.md b/docs/chatbot-mcp.md index 83f4a981..e70a33c4 100644 --- a/docs/chatbot-mcp.md +++ b/docs/chatbot-mcp.md @@ -79,9 +79,12 @@ Trip rules (`App\Chatbot\TripCatalog`): ("NEU Sportclub Lederer Wochenenden und Kurztrips", "Vacanceole Résidence L'Edelweiss"), so a hotel is shown under its TYPO3 title, and under BusPro's name only when TYPO3 has no hotel for its code. `query` searches both. Trips have no name in BusPro's export, only a code; their names are TYPO3's. -- A room is bookable unless its status is `Buchungsstop`. The baby row (room code `Baby`) is not a room. - `available` counts rooms, so the places of a date at a hotel are `Σ available × maxPax` over its - bookable rooms. The tools never output room counts, only `frei` or `auf Anfrage`. +- A room is listed unless its status is `Buchungsstop`. The baby row (room code `Baby`) is not a room. + A listed room is bookable when the booking flow offers it (`Frei` with rooms left, the export's `bookable`); + any other room, including one on request (`Anfrage`), is sold out, as the website shows it. Dates with + only sold-out rooms stay in `search_trips`, marked `ausgebucht`. `available` counts rooms, so the places + of a date at a hotel are `Σ available × maxPax` over its bookable rooms, and the "ab" price is the + cheapest bookable room's. The tools never output room counts, only `frei` or `ausgebucht`. - `search_trips` only offers products that TYPO3 lists in its own website search (`searchable`) and does not mark as unbookable. Closed group trips and staff trainings are `searchable: false`. `get_trip` still answers when someone names their code. diff --git a/src/BusProNet/Model/Room.php b/src/BusProNet/Model/Room.php index a8bb5448..02d3c6b8 100644 --- a/src/BusProNet/Model/Room.php +++ b/src/BusProNet/Model/Room.php @@ -4,6 +4,7 @@ declare(strict_types=1); namespace App\BusProNet\Model; +use App\BusProNet\Constants; use Symfony\Component\Serializer\Attribute\Context; use Symfony\Component\Serializer\Attribute\Groups; use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer; @@ -20,6 +21,18 @@ class Room public const SELECTION_TYPE_BY_PAX = 'by_pax'; public const SELECTION_TYPE_BY_ROOM = 'by_room'; + /** + * Whether a room with this status and availability is offered for new bookings. + * + * Only 'Frei' rooms with rooms left. A room on request ('Anfrage') would turn the booking + * into an inquiry, so it is treated as sold out. Static and taking the raw values so the + * product export and the chatbot, which hold rooms as arrays, apply the same rule. + */ + public static function isBookableState(?string $status, ?int $available): bool + { + return Constants::STATUS_AVAILABLE === $status && ($available ?? 0) > 0; + } + #[Groups(['api:list', 'api:single', 'snapshot'])] public ?int $id = null; diff --git a/src/BusProNet/Model/Travel.php b/src/BusProNet/Model/Travel.php index a2695f3e..9926c9ae 100644 --- a/src/BusProNet/Model/Travel.php +++ b/src/BusProNet/Model/Travel.php @@ -4,7 +4,6 @@ declare(strict_types=1); namespace App\BusProNet\Model; -use App\BusProNet\Constants; use App\BusProNet\Traits\SortByPriceTrait; use Symfony\Component\Serializer\Attribute\Context; use Symfony\Component\Serializer\Attribute\Groups; @@ -280,8 +279,7 @@ class Travel /** * Retrieves all bookable rooms. * - * Returns rooms with status 'Frei' and availability greater than zero. Rooms on request - * ('Anfrage') are not offered: they would turn the booking into an inquiry. + * Returns the rooms Room::isBookableState() accepts: status 'Frei' with rooms left. * * @return array The filtered array of bookable rooms, indexed by room ID */ @@ -289,7 +287,7 @@ class Travel { $result = []; foreach ($this->rooms as $room) { - if ($room->available > 0 && Constants::STATUS_AVAILABLE === $room->status) { + if (Room::isBookableState($room->status, $room->available)) { $result[$room->id] = $room; } } diff --git a/src/BusProNet/XmlParser/ProductExportParser.php b/src/BusProNet/XmlParser/ProductExportParser.php index f17b1e99..5957d2d2 100644 --- a/src/BusProNet/XmlParser/ProductExportParser.php +++ b/src/BusProNet/XmlParser/ProductExportParser.php @@ -5,6 +5,7 @@ declare(strict_types=1); namespace App\BusProNet\XmlParser; use App\BusProNet\Constants; +use App\BusProNet\Model\Room; use Symfony\Component\DomCrawler\Crawler; /** @@ -61,7 +62,8 @@ class ProductExportParser extends AbstractParser * The hotel's rooms, without the PDGS pseudo room. * * `available` is a count of rooms, not persons. Occupancy is read case-insensitively: - * the travel export writes `MinPax`/`MaxPax`. + * the travel export writes `MinPax`/`MaxPax`. `bookable` is the one derived field: whether + * the booking flow offers the room, so a consumer need not re-derive that rule. * * @return list> */ @@ -76,6 +78,9 @@ class ProductExportParser extends AbstractParser return; } + $available = $this->getIntAttrOrNullValue($room, 'verfuegbar'); + $status = $this->getAttrOrNullValue($room, 'status'); + $rooms[] = [ 'busProId' => $this->getIntAttrOrNullValue($room, 'idbuspro_zimmer'), 'code' => $code, @@ -85,8 +90,9 @@ class ProductExportParser extends AbstractParser 'maxPax' => $this->getIntAttrOrNullValue($room, 'maxpax'), 'nights' => $this->getIntAttrOrNullValue($room, 'naechte'), 'price' => $this->stringToFloat($this->getAttrOrNullValue($room, 'preis')), - 'available' => $this->getIntAttrOrNullValue($room, 'verfuegbar'), - 'status' => $this->getAttrOrNullValue($room, 'status'), + 'available' => $available, + 'status' => $status, + 'bookable' => Room::isBookableState($status, $available), 'boardCode' => $this->getAttrOrNullValue($room, 'vpcode'), 'boardBusProId' => $this->getIntAttrOrNullValue($room, 'idbuspro_vp'), ]; diff --git a/src/Chatbot/TripCatalog.php b/src/Chatbot/TripCatalog.php index af43503d..28823471 100644 --- a/src/Chatbot/TripCatalog.php +++ b/src/Chatbot/TripCatalog.php @@ -40,8 +40,6 @@ class TripCatalog /** The feed's only language for now; trips are joined in it. */ public const LANGUAGE = 'de'; - private const STATUS_FREE = 'Frei'; - private const DATES_WITH_PICKUPS = 3; private const BODY_LIMIT = 20000; private const HOTEL_BODY_LIMIT = 8000; @@ -571,7 +569,7 @@ class TripCatalog */ private function matches(array $row, TravelDateFacts $facts, ?HotelType $hotelType, TripCriteria $criteria): bool { - if (!$facts->isBookable()) { + if (!$facts->isListed()) { return false; } @@ -696,7 +694,7 @@ class TripCatalog 'board' => $room['boardCode'] ?? null, 'nights' => $room['nights'] ?? null, 'price' => $room['price'] ?? null, - 'availability' => self::STATUS_FREE === ($room['status'] ?? null) ? TravelDateFacts::AVAILABILITY_FREE : TravelDateFacts::AVAILABILITY_ON_REQUEST, + 'availability' => TravelDateFacts::isBookableRoom($room) ? TravelDateFacts::AVAILABILITY_FREE : TravelDateFacts::AVAILABILITY_SOLD_OUT, ], static fn (mixed $value): bool => null !== $value); } @@ -712,7 +710,7 @@ class TripCatalog 'hotel' => $this->hotelName($catalog, $hotel, $row), 'hotelCode' => $row['hotel']['code'], 'rooms' => $rooms, - 'bookable' => [] !== $rooms, + 'bookable' => in_array(TravelDateFacts::AVAILABILITY_FREE, array_column($rooms, 'availability'), true), ]; } diff --git a/src/Model/Chatbot/TravelDateFacts.php b/src/Model/Chatbot/TravelDateFacts.php index 3495fefe..9c58624c 100644 --- a/src/Model/Chatbot/TravelDateFacts.php +++ b/src/Model/Chatbot/TravelDateFacts.php @@ -4,26 +4,28 @@ declare(strict_types=1); namespace App\Model\Chatbot; +use App\BusProNet\Model\Room; use App\Enum\RoomType; /** * What the website's travel search knows about one travel date at one hotel, derived from * a product export row the way TYPO3's DateImportService derives it, with two deliberate - * differences: rooms in `Buchungsstop` are not bookable, and neither is the baby row. + * differences: rooms in `Buchungsstop` are not listed, and neither is the baby row. A listed + * room is bookable when Room::isBookableState() says so, as the booking flow offers it; + * the others are sold out, as the website shows them. * * - places: Σ available × maxPax over the bookable rooms (`available` counts rooms); - * - priceFrom ("ab" price): cheapest bookable room with places left, else cheapest bookable room; - * - minPax: the smallest group a bookable room takes; + * - priceFrom ("ab" price): cheapest bookable room, else cheapest listed room; + * - minPax: the smallest group a listed room takes; * - inclusions from the selection groups (7 Skipass, 71 Verpflegung, 86 Programm, 87 Kurse, * 89 Events) and the outbound bus service (a price of 0 means included). */ final readonly class TravelDateFacts { public const AVAILABILITY_FREE = 'frei'; - public const AVAILABILITY_ON_REQUEST = 'auf Anfrage'; + public const AVAILABILITY_SOLD_OUT = 'ausgebucht'; public const STATUS_BOOKING_STOP = 'Buchungsstop'; - private const STATUS_FREE = 'Frei'; private const GROUP_SKIPASS = 7; private const GROUP_BOARD = 71; @@ -32,7 +34,7 @@ final readonly class TravelDateFacts private const GROUP_EVENTS = 89; /** - * @param list $roomTypes distinct, of the bookable rooms + * @param list $roomTypes distinct, of the listed rooms * @param list $boards included board labels */ private function __construct( @@ -71,12 +73,14 @@ final readonly class TravelDateFacts continue; } - $available = (int) ($room['available'] ?? 0); - $places += $available * (int) ($room['maxPax'] ?? 0); + $bookable = self::isBookableRoom($room); + if ($bookable) { + $places += (int) $room['available'] * (int) ($room['maxPax'] ?? 0); + } $roomTypes[$type->value] = $type; - $availability = self::STATUS_FREE === ($room['status'] ?? null) || self::AVAILABILITY_FREE === $availability + $availability = $bookable || self::AVAILABILITY_FREE === $availability ? self::AVAILABILITY_FREE - : self::AVAILABILITY_ON_REQUEST; + : self::AVAILABILITY_SOLD_OUT; if (is_int($room['minPax'] ?? null) && (null === $minPax || $room['minPax'] < $minPax)) { $minPax = $room['minPax']; @@ -86,7 +90,7 @@ final readonly class TravelDateFacts $price = (float) $room['price']; $priceFrom = null === $priceFrom ? $price : min($priceFrom, $price); - if ($available > 0) { + if ($bookable) { $priceFromWithPlaces = null === $priceFromWithPlaces ? $price : min($priceFromWithPlaces, $price); } } @@ -131,11 +135,22 @@ final readonly class TravelDateFacts ); } - public function isBookable(): bool + /** + * Whether the website search lists the date at all, sold out or not. + */ + public function isListed(): bool { return null !== $this->availability; } + /** + * @param array $room a room of a ProductExportBuilder row + */ + public static function isBookableRoom(array $room): bool + { + return Room::isBookableState($room['status'] ?? null, $room['available'] ?? null); + } + /** * What the price includes, as the website lists it on a result. * diff --git a/tests/BusProNet/Model/RoomTest.php b/tests/BusProNet/Model/RoomTest.php new file mode 100644 index 00000000..42a23be1 --- /dev/null +++ b/tests/BusProNet/Model/RoomTest.php @@ -0,0 +1,33 @@ + + */ + public static function bookableStateProvider(): iterable + { + yield 'free with rooms left' => [Constants::STATUS_AVAILABLE, 3, true]; + yield 'free but sold out' => [Constants::STATUS_AVAILABLE, 0, false]; + yield 'free without a count' => [Constants::STATUS_AVAILABLE, null, false]; + yield 'on request with rooms left' => [Constants::STATUS_ON_REQUEST, 5, false]; + yield 'on request and sold out' => [Constants::STATUS_ON_REQUEST, 0, false]; + yield 'booking stop' => [Constants::STATUS_BLOCKED, 5, false]; + yield 'no status' => [null, 5, false]; + } +} diff --git a/tests/Chatbot/TripCatalogTest.php b/tests/Chatbot/TripCatalogTest.php index 5ecf5283..95945f28 100644 --- a/tests/Chatbot/TripCatalogTest.php +++ b/tests/Chatbot/TripCatalogTest.php @@ -59,7 +59,7 @@ class TripCatalogTest extends TestCase self::assertSame(500.0, $hotelOne['priceFrom'], 'the cheapest room with places left; the stopped room does not count'); self::assertSame(['Skipass', 'Bus', 'Halbpension', 'Programm'], $hotelOne['includes']); self::assertSame(['neu'], $hotelOne['flags']); - self::assertSame('auf Anfrage', $result['results'][2]['availability']); + self::assertSame('ausgebucht', $result['results'][2]['availability'], 'a room on request is sold out'); self::assertSame('2026-10-08T06:00:00+00:00', $result['dataAsOf']); self::assertSame(1, count($this->catalog([$this->row('VTH', 2, '2026-12-05', 'HOT1', [$this->room(1)]), $this->row('VTH', 3, '2027-01-09', 'HOT1', [$this->room(1)])])->search(new TripCriteria(limit: 1))['results'])); } @@ -78,6 +78,28 @@ class TripCatalogTest extends TestCase self::assertSame(['VTH2'], array_column($this->catalog($rows)->search(new TripCriteria(persons: 2))['results'], 'dateCode')); } + public function testRoomsOnRequestOrWithoutRoomsLeftAreListedAsSoldOut(): void + { + $rows = [ + // The room on request has rooms left but is sold out: its 6 places and lower price do not count. + $this->row('VTH', 2, '2026-12-05', 'HOT1', [$this->room(400, available: 1, maxPax: 2), $this->room(300, available: 3, maxPax: 2, status: 'Anfrage')]), + $this->row('VTH', 3, '2027-01-09', 'HOT1', [$this->room(500, available: 0), $this->room(450, status: 'Anfrage')]), + ]; + $catalog = $this->catalog($rows); + + $results = $catalog->search(new TripCriteria())['results']; + self::assertSame(['VTH2', 'VTH3'], array_column($results, 'dateCode'), 'sold-out dates stay listed, as on the website'); + self::assertSame([400.0, 450.0], array_column($results, 'priceFrom')); + self::assertSame(['frei', 'ausgebucht'], array_column($results, 'availability')); + self::assertSame([], $catalog->search(new TripCriteria(persons: 3))['results']); + + $trip = $catalog->get('VTH'); + self::assertNotNull($trip); + self::assertSame(['frei', 'ausgebucht'], array_column($trip['dates'][0]['hotels'][0]['rooms'], 'availability')); + self::assertTrue($trip['dates'][0]['hotels'][0]['bookable']); + self::assertFalse($trip['dates'][1]['hotels'][0]['bookable']); + } + public function testTheTravelPeriodContainsTheTripAndPricesApplyToTheAbPrice(): void { $rows = [$this->row('VTH', 2, '2026-12-05', 'HOT1', [$this->room(450), $this->room(700)])]; diff --git a/tests/Service/ProductExportBuilderTest.php b/tests/Service/ProductExportBuilderTest.php index 29f2a8c5..a1156642 100644 --- a/tests/Service/ProductExportBuilderTest.php +++ b/tests/Service/ProductExportBuilderTest.php @@ -69,12 +69,14 @@ class ProductExportBuilderTest extends TestCase 'price' => 229.5, 'available' => 24, 'status' => 'Frei', + 'bookable' => true, 'boardCode' => 'Lt. Auss.', 'boardBusProId' => 2, ], $rooms[0]); // Buchungsstop rooms reach the consumer: "ausgebucht" is its call. self::assertSame('Buchungsstop', $rooms[1]['status']); + self::assertFalse($rooms[1]['bookable']); self::assertSame(3, $rooms[1]['maxPax'], 'MaxPax is read despite its casing'); }