feat: add PostcodeService and price validation with DB constraints

- Add PostcodeService to resolve UK postcodes, outcodes, and place names to coordinates via postcodes.io API with 30-day caching
- Add LocationResult value object for resolved location data
- Add per-fuel-type price validation (80p-1050p range) to FuelPriceService with warning logs for out-of-range prices
- Change price_pence column from unsignedSmallInteger to unsignedMediumInteger in station_prices tables
- Add CHECK constraints (5000-50000 range) on price_pence columns as database-level guard
- Improve error handling in PollFuelPrices command with file/line/trace output
- Add tests for PostcodeService covering full postcodes, outcodes, place names, caching, and error handling
- Add test for price validation range checks

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

app/Services/FuelPriceService.php

@@ -17,6 +17,22 @@ class FuelPriceService
 {
     private const string TOKEN_CACHE_KEY = 'fuel_finder_access_token';
 
+    /**
+     * Per-fuel-type valid price range in pence (as returned by the API).
+     * Based on UK all-time records + 30–75% headroom for future spikes.
+     * All-time records: petrol 191.6p, diesel 199.2p (Jul 2022).
+     *
+     * @var array<string, array{min: int, max: int}>
+     */
+    private const array PRICE_LIMITS_PENCE = [
+        'e10' => ['min' => 80, 'max' => 750],
+        'e5' => ['min' => 80, 'max' => 840],
+        'b7_standard' => ['min' => 80, 'max' => 840],
+        'b7_premium' => ['min' => 80, 'max' => 960],
+        'b10' => ['min' => 80, 'max' => 840],
+        'hvo' => ['min' => 80, 'max' => 1050],
+    ];
+
     public function __construct(
         private readonly StationTaggingService $taggingService,
         private readonly ApiLogger $apiLogger,
@@ -56,6 +72,18 @@ class FuelPriceService
                     ->withToken($token)
                     ->get($baseUrl, $params));
 
+                if ($response->notFound()) {
+                    break; // No more batches
+                }
+
+                if (! $response->successful()) {
+                    Log::error('FuelPriceService: price batch returned error', [
+                        'batch' => $batch,
+                        'status' => $response->status(),
+                    ]);
+                    break;
+                }
+
                 $stations = $response->json() ?? [];
             } catch (Throwable $e) {
                 Log::error('FuelPriceService: price batch fetch failed', [
@@ -94,6 +122,18 @@ class FuelPriceService
                     ->withToken($token)
                     ->get($baseUrl, $params));
 
+                if ($response->notFound()) {
+                    break; // No more batches
+                }
+
+                if (! $response->successful()) {
+                    Log::error('FuelPriceService: station batch returned error', [
+                        'batch' => $batch,
+                        'status' => $response->status(),
+                    ]);
+                    break;
+                }
+
                 $stations = $response->json() ?? [];
             } catch (Throwable $e) {
                 Log::error('FuelPriceService: station batch fetch failed', [
@@ -152,6 +192,17 @@ class FuelPriceService
         Station::upsert($rows, ['node_id'], array_keys($rows[0] ?? []));
     }
 
+    private function isValidPrice(FuelType $fuelType, float $pricePence): bool
+    {
+        $limits = self::PRICE_LIMITS_PENCE[$fuelType->value] ?? null;
+
+        if ($limits === null) {
+            return false;
+        }
+
+        return $pricePence >= $limits['min'] && $pricePence <= $limits['max'];
+    }
+
     /**
      * Process one batch of API price data.
      *
@@ -185,7 +236,20 @@ class FuelPriceService
                     continue; // Skip unknown fuel types
                 }
 
-                $pricePence = (int) round($priceData['price'] * 100);
+                $rawPrice = (float) $priceData['price'];
+
+                if (! $this->isValidPrice($fuelType, $rawPrice)) {
+                    Log::warning('FuelPriceService: price out of valid range — skipped', [
+                        'station_id' => $stationId,
+                        'fuel_type' => $fuelType->value,
+                        'price' => $rawPrice,
+                        'limits' => self::PRICE_LIMITS_PENCE[$fuelType->value],
+                    ]);
+
+                    continue;
+                }
+
+                $pricePence = (int) round($rawPrice * 100);
                 $effectiveAt = Carbon::parse($priceData['price_change_effective_timestamp']);
                 $reportedAt = Carbon::parse($priceData['price_last_updated']);
                 $currentPricePence = $currentPrices[$stationId][$fuelType->value]->price_pence ?? null;