chore: add inline documentation

src/Service/TravelSnapshotService.php

@@ -97,6 +97,7 @@ class TravelSnapshotService
      */
     public function upsertFromTravel(Travel $travel): void
     {
+        // Both fields form the composite unique key; nothing to persist without them.
         if (null === $travel->id || null === $travel->hotelId) {
             return;
         }
@@ -191,6 +192,10 @@ class TravelSnapshotService
         $extendedResponseByDateId = [];
 
         foreach ($candidates as $snapshot) {
+            // Skip travels whose XML is still live; their snapshot is kept authoritative
+            // by the XML load path (getTravelDataFromXml → upsertFromTravel). An empty
+            // $xmlAvailableDateIds means the file map could not be loaded, so fall back
+            // to refreshing everything rather than skipping all candidates.
             if ([] !== $xmlAvailableDateIds && in_array($snapshot->getDateId(), $xmlAvailableDateIds, true)) {
                 continue;
             }
@@ -203,6 +208,8 @@ class TravelSnapshotService
                 continue;
             }
 
+            // Cache the API response by dateId: multiple hotel snapshots share one travel
+            // date, so a single API call covers all of them within the same batch.
             if (false === array_key_exists($dateId, $extendedResponseByDateId)) {
                 $response = null;
                 try {
@@ -215,6 +222,8 @@ class TravelSnapshotService
                     ]);
                 }
 
+                // A Notification response signals a business-level "no data" answer
+                // from the API rather than an error; treat it the same as a null response.
                 if (null !== $response && false === $response instanceof Notification) {
                     $extendedResponseByDateId[$dateId] = $response;
                 } elseif (false === isset($extendedResponseByDateId[$dateId])) {
@@ -236,6 +245,8 @@ class TravelSnapshotService
                 $snapshot->setPayload($payload)->setPayloadHash($payloadHash);
                 $this->applyTravelMetadata($snapshot, $travel);
             }
+            // Always stamp the refresh timestamp even when the payload was unchanged,
+            // so the candidate query does not re-select this snapshot on the next run.
             $snapshot->setExtendedRefreshedAt(new \DateTimeImmutable())->touchUpdatedAt();
             $this->entityManager->flush();