feat: add fuel:archive command and monthly scheduler entry

Completes Tasks 12 + 13 from docs/superpowers/plans/2026-04-03-fuel-api-ingestion.md.

- ArchiveOldPricesCommand moves station_prices rows older than 12 months
  into station_prices_archive in chunks of 1000, wrapping each chunk's
  insert + delete in a DB::transaction so a partial failure can't
  duplicate rows.
- StationPriceArchive: add $table = 'station_prices_archive'; without it
  Eloquent infers 'station_price_archives' and the insert would fail.
- routes/console.php: register fuel:archive monthly on the 1st at 04:00
  UTC, alongside the other fuel/oil scheduler entries.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

app/Console/Commands/ArchiveOldPricesCommand.php

@@ -0,0 +1,52 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Models\StationPrice;
+use App\Models\StationPriceArchive;
+use Illuminate\Console\Command;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Facades\DB;
+
+class ArchiveOldPricesCommand extends Command
+{
+    protected $signature = 'fuel:archive';
+
+    protected $description = 'Move station price history older than 12 months to the archive table';
+
+    public function handle(): int
+    {
+        $cutoff = Carbon::now()->subMonths(12);
+
+        $count = StationPrice::where('price_effective_at', '<', $cutoff)->count();
+
+        if ($count === 0) {
+            $this->info('No prices to archive.');
+
+            return self::SUCCESS;
+        }
+
+        $this->info("Archiving {$count} price record(s) older than {$cutoff->toDateString()}...");
+
+        StationPrice::where('price_effective_at', '<', $cutoff)
+            ->chunkById(1000, function ($prices): void {
+                $rows = $prices->map(fn (StationPrice $price): array => [
+                    'station_id' => $price->station_id,
+                    'fuel_type' => $price->fuel_type->value,
+                    'price_pence' => $price->price_pence,
+                    'price_effective_at' => $price->price_effective_at,
+                    'price_reported_at' => $price->price_reported_at,
+                    'recorded_at' => $price->recorded_at,
+                ])->all();
+
+                DB::transaction(function () use ($rows, $prices): void {
+                    StationPriceArchive::insert($rows);
+                    StationPrice::whereIn('id', $prices->pluck('id'))->delete();
+                });
+            });
+
+        $this->info('Archive complete.');
+
+        return self::SUCCESS;
+    }
+}

app/Models/StationPriceArchive.php

@@ -10,15 +10,17 @@ use Illuminate\Database\Eloquent\Relations\BelongsTo;
 #[Fillable(['station_id', 'fuel_type', 'price_pence', 'price_effective_at', 'price_reported_at', 'recorded_at'])]
 class StationPriceArchive extends Model
 {
+    protected $table = 'station_prices_archive';
+
     public $timestamps = false;
 
     protected function casts(): array
     {
         return [
-            'fuel_type'          => FuelType::class,
+            'fuel_type' => FuelType::class,
             'price_effective_at' => 'datetime',
-            'price_reported_at'  => 'datetime',
+            'price_reported_at' => 'datetime',
-            'recorded_at'        => 'datetime',
+            'recorded_at' => 'datetime',
         ];
     }
 

routes/console.php

@@ -33,6 +33,14 @@ Schedule::command('oil:predict --fetch')
     ->onOneServer()
     ->runInBackground();
 
+// Move station_prices rows older than 12 months into station_prices_archive
+// once a month. Keeps the partitioned hot table bounded.
+Schedule::command('fuel:archive')
+    ->monthlyOn(1, '04:00')
+    ->withoutOverlapping()
+    ->onOneServer()
+    ->runInBackground();
+
 // Scheduled WhatsApp updates — morning and evening
 Schedule::job(new SendScheduledWhatsAppJob('morning'))->dailyAt('07:30')->onOneServer();
 Schedule::job(new SendScheduledWhatsAppJob('evening'))->dailyAt('18:00')->onOneServer();

tests/Feature/Commands/ArchiveOldPricesCommandTest.php

@@ -0,0 +1,69 @@
+<?php
+
+use App\Models\Station;
+use App\Models\StationPrice;
+use App\Models\StationPriceArchive;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+
+uses(RefreshDatabase::class);
+
+it('moves prices older than 12 months to archive', function (): void {
+    $station = Station::factory()->create();
+
+    StationPrice::factory()->create([
+        'station_id' => $station->node_id,
+        'price_effective_at' => now()->subMonths(13),
+        'price_reported_at' => now()->subMonths(13),
+        'recorded_at' => now()->subMonths(13),
+    ]);
+
+    StationPrice::factory()->create([
+        'station_id' => $station->node_id,
+        'price_effective_at' => now()->subMonths(6),
+        'price_reported_at' => now()->subMonths(6),
+        'recorded_at' => now()->subMonths(6),
+    ]);
+
+    $this->artisan('fuel:archive')->assertSuccessful();
+
+    expect(StationPrice::count())->toBe(1)
+        ->and(StationPriceArchive::count())->toBe(1);
+});
+
+it('outputs no-op message when nothing qualifies', function (): void {
+    $station = Station::factory()->create();
+
+    StationPrice::factory()->create([
+        'station_id' => $station->node_id,
+        'price_effective_at' => now()->subMonths(3),
+        'price_reported_at' => now()->subMonths(3),
+        'recorded_at' => now()->subMonths(3),
+    ]);
+
+    $this->artisan('fuel:archive')
+        ->expectsOutputToContain('No prices to archive.')
+        ->assertSuccessful();
+
+    expect(StationPrice::count())->toBe(1)
+        ->and(StationPriceArchive::count())->toBe(0);
+});
+
+it('preserves the row data when archiving', function (): void {
+    $station = Station::factory()->create();
+
+    $original = StationPrice::factory()->create([
+        'station_id' => $station->node_id,
+        'price_pence' => 14523,
+        'price_effective_at' => now()->subMonths(13),
+        'price_reported_at' => now()->subMonths(13),
+        'recorded_at' => now()->subMonths(13),
+    ]);
+
+    $this->artisan('fuel:archive')->assertSuccessful();
+
+    $archived = StationPriceArchive::first();
+
+    expect($archived)->not->toBeNull()
+        ->and($archived->station_id)->toBe($original->station_id)
+        ->and($archived->price_pence)->toBe(14523);
+});