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>
2026-04-04 12:40:43 +01:00
parent 097f1b0529
commit e532cc1208
8 changed files with 530 additions and 1 deletions
--- a/tests/Unit/Services/PostcodeServiceTest.php
+++ b/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();
+});