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>

tests/Unit/Services/FuelPriceServiceTest.php

@@ -252,6 +252,51 @@ it('skips unknown fuel types without error', function (): void {
         ->and(StationPrice::count())->toBe(0);
 });
 
+it('skips prices outside valid range and logs a warning', function (): void {
+    Cache::put('fuel_finder_access_token', 'tok', 3540);
+
+    Station::factory()->create(['node_id' => 'sta1']);
+
+    Http::fake([
+        '*/pfs/fuel-prices*' => Http::sequence()
+            ->push([
+                [
+                    'node_id' => 'sta1',
+                    'fuel_prices' => [
+                        // Way too high — clearly bad data
+                        [
+                            'fuel_type' => 'E10',
+                            'price' => 900.0,
+                            'price_last_updated' => '2026-04-04T10:00:00.000Z',
+                            'price_change_effective_timestamp' => '2026-04-04T10:00:00.000Z',
+                        ],
+                        // Too low — below minimum
+                        [
+                            'fuel_type' => 'E5',
+                            'price' => 10.0,
+                            'price_last_updated' => '2026-04-04T10:00:00.000Z',
+                            'price_change_effective_timestamp' => '2026-04-04T10:00:00.000Z',
+                        ],
+                        // Valid — should be inserted
+                        [
+                            'fuel_type' => 'B7_STANDARD',
+                            'price' => 155.9,
+                            'price_last_updated' => '2026-04-04T10:00:00.000Z',
+                            'price_change_effective_timestamp' => '2026-04-04T10:00:00.000Z',
+                        ],
+                    ],
+                ],
+            ])
+            ->push([]),
+    ]);
+
+    $inserted = $this->service->pollPrices();
+
+    expect($inserted)->toBe(1)
+        ->and(StationPrice::count())->toBe(1)
+        ->and(StationPrice::first()->price_pence)->toBe(15590);
+});
+
 it('stops pagination when an empty batch is returned', function (): void {
     Cache::put('fuel_finder_access_token', 'tok', 3540);
 

tests/Unit/Services/PostcodeServiceTest.php

@@ -0,0 +1,173 @@
+<?php
+
+use App\Services\ApiLogger;
+use App\Services\LocationResult;
+use App\Services\PostcodeService;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\Http;
+
+uses(RefreshDatabase::class);
+
+beforeEach(function (): void {
+    $this->service = new PostcodeService(new ApiLogger);
+});
+
+// --- Full postcode ---
+
+it('resolves a full postcode to coordinates', function (): void {
+    Http::fake([
+        '*/postcodes/SW1A1AA' => Http::response([
+            'status' => 200,
+            'result' => [
+                'postcode' => 'SW1A 1AA',
+                'latitude' => 51.501009,
+                'longitude' => -0.141588,
+            ],
+        ]),
+    ]);
+
+    $result = $this->service->resolve('SW1A 1AA');
+
+    expect($result)->toBeInstanceOf(LocationResult::class)
+        ->and($result->displayName)->toBe('SW1A 1AA')
+        ->and($result->lat)->toBe(51.501009)
+        ->and($result->lng)->toBe(-0.141588);
+});
+
+it('normalises postcode spacing before lookup', function (): void {
+    Http::fake([
+        '*/postcodes/SW1A1AA' => Http::response([
+            'status' => 200,
+            'result' => [
+                'postcode' => 'SW1A 1AA',
+                'latitude' => 51.501009,
+                'longitude' => -0.141588,
+            ],
+        ]),
+    ]);
+
+    $result = $this->service->resolve('sw1a1aa');
+
+    expect($result)->not->toBeNull()
+        ->and($result->displayName)->toBe('SW1A 1AA');
+});
+
+// --- Outcode ---
+
+it('resolves an outcode to coordinates', function (): void {
+    Http::fake([
+        '*/outcodes/PE7' => Http::response([
+            'status' => 200,
+            'result' => [
+                'outcode' => 'PE7',
+                'latitude' => 52.536397,
+                'longitude' => -0.210181,
+            ],
+        ]),
+    ]);
+
+    $result = $this->service->resolve('PE7');
+
+    expect($result)->toBeInstanceOf(LocationResult::class)
+        ->and($result->displayName)->toBe('PE7')
+        ->and($result->lat)->toBe(52.536397)
+        ->and($result->lng)->toBe(-0.210181);
+});
+
+it('resolves a lowercase outcode', function (): void {
+    Http::fake([
+        '*/outcodes/M1' => Http::response([
+            'status' => 200,
+            'result' => [
+                'outcode' => 'M1',
+                'latitude' => 53.480957,
+                'longitude' => -2.237428,
+            ],
+        ]),
+    ]);
+
+    $result = $this->service->resolve('m1');
+
+    expect($result)->not->toBeNull()
+        ->and($result->displayName)->toBe('M1');
+});
+
+// --- Place name ---
+
+it('resolves a city name to coordinates', function (): void {
+    Http::fake([
+        '*/places*' => Http::response([
+            'status' => 200,
+            'result' => [
+                [
+                    'name_1' => 'Manchester',
+                    'latitude' => 53.480957,
+                    'longitude' => -2.237428,
+                ],
+            ],
+        ]),
+    ]);
+
+    $result = $this->service->resolve('Manchester');
+
+    expect($result)->toBeInstanceOf(LocationResult::class)
+        ->and($result->displayName)->toBe('Manchester')
+        ->and($result->lat)->toBe(53.480957)
+        ->and($result->lng)->toBe(-2.237428);
+});
+
+it('returns null when place name yields no results', function (): void {
+    Http::fake([
+        '*/places*' => Http::response([
+            'status' => 200,
+            'result' => [],
+        ]),
+    ]);
+
+    $result = $this->service->resolve('Narnia');
+
+    expect($result)->toBeNull();
+});
+
+// --- Caching ---
+
+it('caches a successful resolution for 30 days', function (): void {
+    Http::fake([
+        '*/outcodes/PE7' => Http::response([
+            'status' => 200,
+            'result' => [
+                'outcode' => 'PE7',
+                'latitude' => 52.536397,
+                'longitude' => -0.210181,
+            ],
+        ]),
+    ]);
+
+    $this->service->resolve('PE7');
+    $this->service->resolve('PE7');
+
+    Http::assertSentCount(1);
+    expect(Cache::get('postcode:pe7'))->toBeInstanceOf(LocationResult::class);
+});
+
+it('does not cache failed lookups', function (): void {
+    Http::fake([
+        '*/postcodes/ZZ99ZZ' => Http::response(['status' => 404], 404),
+    ]);
+
+    $result = $this->service->resolve('ZZ9 9ZZ');
+
+    expect($result)->toBeNull()
+        ->and(Cache::get('postcode:zz99zz'))->toBeNull();
+});
+
+it('returns null and does not throw on API failure', function (): void {
+    Http::fake([
+        '*/outcodes/PE7' => Http::response([], 500),
+    ]);
+
+    $result = $this->service->resolve('PE7');
+
+    expect($result)->toBeNull();
+});