feat: make boarding point price levelling switchable

src/BusProNet/XmlParser/TravelParser.php

@@ -29,8 +29,20 @@ class TravelParser extends AbstractParser
         Constants::PSEUDO_PRICE_ROOM_CODE,
     ];
 
+    /**
+     * `$levelBoardingPointPrices` carries no default on purpose: a hand-built parser would
+     * otherwise silently ignore APP_BPN_LEVEL_BOARDING_POINT_PRICES and price one travel tier
+     * differently from the others. The registry gave up its own default along with it, so that
+     * there is one way to build this class — through the container, or explicitly in a test.
+     *
+     * @param bool $levelBoardingPointPrices Whether to compensate the BusPro export defect that
+     *                                       omits a boarding point's return-leg price. The
+     *                                       container wires it from
+     *                                       APP_BPN_LEVEL_BOARDING_POINT_PRICES.
+     */
     public function __construct(
-        private readonly AgeConstraintParserRegistry $ageConstraintRegistry = new AgeConstraintParserRegistry(),
+        private readonly AgeConstraintParserRegistry $ageConstraintRegistry,
+        private readonly bool $levelBoardingPointPrices,
     ) {
     }
 
@@ -88,7 +100,9 @@ class TravelParser extends AbstractParser
         $travel->dropOffs = $this->getPickups($node->filterXPath('.//zustiege_rueck/zustieg_rueck'), $dateTo, false);
 
         // A boarding point costs the same in both directions
-        $this->levelBoardingPointPrices($travel->pickups, $travel->dropOffs);
+        if ($this->levelBoardingPointPrices) {
+            $this->applyBoardingPointPriceLevelling($travel->pickups, $travel->dropOffs);
+        }
 
         $travel->guide = $this->getGuide($node);
 
@@ -465,10 +479,15 @@ class TravelParser extends AbstractParser
      * Where both directions state a price they agree in practice; the outbound one wins
      * to keep the outcome deterministic. Points without a counterpart are left as they are.
      *
+     * Compensating the defect locally is provisional, so it is switchable: with
+     * `$levelBoardingPointPrices` off the export is reported verbatim and the affected
+     * travels undercharge the return leg again. See
+     * `docs/buspro-database-reference.md` section A7.
+     *
      * @param array<int, Pickup> $pickups  Pickups indexed by ID (modified in place)
      * @param array<int, Pickup> $dropOffs Drop-offs indexed by ID (modified in place)
      */
-    private function levelBoardingPointPrices(array &$pickups, array $dropOffs): void
+    private function applyBoardingPointPriceLevelling(array $pickups, array $dropOffs): void
     {
         foreach ($dropOffs as $pickupId => $dropOff) {
             if (false === isset($pickups[$pickupId])) {