fix: stop caching rejected voucher checks, document response codes

src/Service/VoucherValidator.php

@@ -13,6 +13,10 @@ use Psr\Log\LoggerInterface;
 use Symfony\Contracts\Cache\CacheInterface;
 use Symfony\Contracts\Cache\ItemInterface;
 
+/**
+ * Checks voucher codes with BusPro. Only accepted codes are cached: a rejection is asked again on
+ * the next attempt, so a code fixed in BusPro (or a passing outage) is picked up immediately.
+ */
 class VoucherValidator
 {
     private const CACHE_TTL = 900; // 15 minutes
@@ -30,13 +34,15 @@ class VoucherValidator
         $cacheKey = sprintf('voucher.purchase.%s', md5($redemptionCode));
 
         try {
-            return $this->cache->get($cacheKey, function (ItemInterface $item) use ($redemptionCode) {
+            return $this->cache->get($cacheKey, function (ItemInterface $item, bool &$save) use ($redemptionCode) {
                 $item->expiresAfter(self::CACHE_TTL);
 
                 try {
                     $result = $this->voucherClient->validatePurchaseVoucher($redemptionCode);
 
                     if ($result instanceof Notification) {
+                        $save = false;
+
                         return new PurchaseVoucherValidationResult(
                             isValid: false,
                             errorMessage: $result->message,
@@ -49,6 +55,7 @@ class VoucherValidator
                         voucher: $result
                     );
                 } catch (ApiClientException $e) {
+                    $save = false;
                     $this->logger->error('Purchase voucher validation failed', [
                         'redemptionCode' => $redemptionCode,
                         'error' => $e->getMessage(),
@@ -85,13 +92,15 @@ class VoucherValidator
         );
 
         try {
-            return $this->cache->get($cacheKey, function (ItemInterface $item) use ($promoCode, $travelId, $participantPrice) {
+            return $this->cache->get($cacheKey, function (ItemInterface $item, bool &$save) use ($promoCode, $travelId, $participantPrice) {
                 $item->expiresAfter(self::CACHE_TTL);
 
                 try {
                     $result = $this->voucherClient->validatePromoVoucher($promoCode, $travelId, $participantPrice);
 
                     if ($result instanceof Notification) {
+                        $save = false;
+
                         return new PromoVoucherValidationResult(
                             isValid: false,
                             errorMessage: $result->message,
@@ -104,6 +113,7 @@ class VoucherValidator
                         voucher: $result
                     );
                 } catch (ApiClientException $e) {
+                    $save = false;
                     $this->logger->error('Promo voucher validation failed', [
                         'promoCode' => $promoCode,
                         'travelId' => $travelId,