feat: api endpoints and xml sync for contingents data

src/Service/BpnXmlSnapshotRefreshManager.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Service;
+
+use App\Model\BpnXmlSnapshotRefreshPlan;
+use App\Model\BpnXmlSnapshotRefreshResult;
+use App\BusProNet\XmlLoader\TravelLoader;
+use Psr\Log\LoggerInterface;
+
+final class BpnXmlSnapshotRefreshManager
+{
+    public function __construct(
+        private readonly TravelLoader $travelLoader,
+        private readonly TravelDataProvider $travelDataService,
+        private readonly TravelSnapshotManager $snapshotService,
+        private readonly LoggerInterface $logger,
+    ) {
+    }
+
+    public function buildPlan(): ?BpnXmlSnapshotRefreshPlan
+    {
+        try {
+            $xmlFileMap = $this->travelLoader->generateFilesMap();
+        } catch (\Throwable $e) {
+            $this->logger->warning('Failed to generate XML file map after sync; snapshot refresh skipped', [
+                'error' => $e->getMessage(),
+            ]);
+
+            return null;
+        }
+
+        $total = array_sum(array_map(fn (array $entry): int => count($entry['hotels']), $xmlFileMap));
+
+        return new BpnXmlSnapshotRefreshPlan($xmlFileMap, $total);
+    }
+
+    public function refresh(
+        BpnXmlSnapshotRefreshPlan $plan,
+        ?callable $onProgress = null,
+    ): BpnXmlSnapshotRefreshResult {
+        $snapshotResult = $this->travelDataService->syncSnapshotsFromXml(
+            $plan->xmlFileMap,
+            function () use ($onProgress): void {
+                if (null !== $onProgress) {
+                    $onProgress();
+                }
+            },
+        );
+
+        $orphanedDeleted = $this->snapshotService->purgeOrphanedFutureSnapshots(array_keys($plan->xmlFileMap));
+
+        return new BpnXmlSnapshotRefreshResult(
+            $snapshotResult['processed'],
+            $snapshotResult['failed'],
+            $orphanedDeleted,
+        );
+    }
+}