feat: add searches table, model, and factory for API search logging

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

app/Models/Search.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace App\Models;
+
+use Database\Factories\SearchFactory;
+use Illuminate\Database\Eloquent\Attributes\Fillable;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+
+#[Fillable(['lat_bucket', 'lng_bucket', 'fuel_type', 'results_count', 'lowest_pence', 'highest_pence', 'avg_pence', 'searched_at', 'ip_hash'])]
+class Search extends Model
+{
+    /** @use HasFactory<SearchFactory> */
+    use HasFactory;
+
+    public $timestamps = false;
+
+    protected function casts(): array
+    {
+        return [
+            'searched_at' => 'datetime',
+        ];
+    }
+}

database/factories/SearchFactory.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace Database\Factories;
+
+use App\Models\Search;
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+/** @extends Factory<Search> */
+class SearchFactory extends Factory
+{
+    public function definition(): array
+    {
+        $lowest = fake()->numberBetween(12000, 15000);
+        $highest = $lowest + fake()->numberBetween(100, 3000);
+
+        return [
+            'lat_bucket' => round(fake()->latitude(49.9, 60.9), 2),
+            'lng_bucket' => round(fake()->longitude(-8.2, 1.8), 2),
+            'fuel_type' => fake()->randomElement(['b7_standard', 'e10', 'e5']),
+            'results_count' => fake()->numberBetween(5, 100),
+            'lowest_pence' => $lowest,
+            'highest_pence' => $highest,
+            'avg_pence' => round(($lowest + $highest) / 2, 2),
+            'searched_at' => now(),
+            'ip_hash' => hash('sha256', fake()->ipv4()),
+        ];
+    }
+}

database/migrations/2026_04_04_180819_create_searches_table.php

@@ -0,0 +1,32 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('searches', function (Blueprint $table): void {
+            $table->bigIncrements('id');
+            $table->decimal('lat_bucket', 5, 2)->comment('Latitude rounded to 2dp (~1km precision) for privacy');
+            $table->decimal('lng_bucket', 5, 2)->comment('Longitude rounded to 2dp for privacy');
+            $table->string('fuel_type', 20);
+            $table->unsignedSmallInteger('results_count');
+            $table->unsignedSmallInteger('lowest_pence')->nullable()->comment('Cheapest price found in pence × 100');
+            $table->unsignedSmallInteger('highest_pence')->nullable()->comment('Most expensive price found in pence × 100');
+            $table->decimal('avg_pence', 8, 2)->nullable()->comment('Mean price across results in pence × 100');
+            $table->dateTime('searched_at');
+            $table->string('ip_hash', 64)->comment('SHA-256 of requester IP — non-reversible, for unique count only');
+
+            $table->index(['searched_at', 'fuel_type']);
+            $table->index('ip_hash');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('searches');
+    }
+};