@fleetbase/fleetops-engine 0.6.65 → 0.6.66

package/server/tests/Unit/Support/FuelProviderServiceMatchingTest.php

@@ -38,6 +38,8 @@ class FleetOpsFuelServiceMatchingProbe extends FuelProviderService
 
 function fleetopsFuelServiceMatchingBoot(): SQLiteConnection
 {
+    EloquentModel::setEventDispatcher(new Illuminate\Events\Dispatcher(app()));
+    EloquentModel::clearBootedModels();
     $pdo = new PDO('sqlite::memory:');
     // SQLite lacks the MySQL spatial functions used by the fuel report
     // location cast; a passthrough keeps the WKT string intact.
@@ -91,6 +93,13 @@ function fleetopsFuelServiceMatchingBoot(): SQLiteConnection
         });
     }
 
+    // Exercise real UUID assignment without unrelated HTTP-cache observers.
+    foreach ([FuelProviderTransaction::class, Fleetbase\FleetOps\Models\FuelReport::class, Fleetbase\FleetOps\Models\FuelProviderSyncRun::class] as $modelClass) {
+        new $modelClass();
+        $modelClass::flushEventListeners();
+        $modelClass::bootHasUuid();
+    }
+
     session(['company' => 'company-1']);
     FleetOpsFuelServiceMatchingRecorder::$events = [];
 
@@ -177,8 +186,12 @@ test('match vehicle and match order resolve string identifiers', function () {
     $matched = $service->matchVehicle($transaction, 'vehicle_test');
     expect($matched->vehicle_uuid)->toBe('vehicle-1')
         ->and($matched->sync_status)->toBe('matched')
+        ->and($matched->fuel_report_uuid)->not->toBeNull()
         ->and($connection->table('fuel_reports')->count())->toBe(1);
 
+    $service->matchVehicle($matched, 'vehicle_test');
+    expect($connection->table('fuel_reports')->count())->toBe(1);
+
     $withOrder = $service->matchOrder($matched, 'order_test');
     expect($withOrder->order_uuid)->toBe('order-1');
 });
@@ -278,3 +291,117 @@ test('ensure fuel report reuses existing reports and skips vehicleless transacti
     expect($report)->not->toBeNull()
         ->and($connection->table('fuel_reports')->where('uuid', $report->uuid)->value('location'))->toBe('POINT(103.85 1.29)');
 });
+
+test('reimport updates a transaction without duplicating its report and preserves ignored review', function () {
+    $db         = fleetopsFuelServiceMatchingBoot();
+    $connection = fleetopsFuelServiceMatchingConnection($db);
+    $db->table('vehicles')->insert(['uuid' => 'vehicle-1', 'company_uuid' => 'company-1', 'plate_number' => 'SGX-1234']);
+    $service = fleetopsFuelServiceMatchingService();
+    $payload = ['provider_transaction_id' => 'repeat-1', 'plate_number' => 'SGX-1234', 'amount' => 1250, 'currency' => 'SAR', 'volume' => 5];
+    $first   = $service->ingestTransaction($connection, $payload);
+    $second  = $service->ingestTransaction($connection, $payload);
+    expect($first->wasRecentlyCreated)->toBeTrue()
+        ->and($second->wasRecentlyCreated)->toBeFalse()
+        ->and($db->table('fuel_provider_transactions')->count())->toBe(1)
+        ->and($db->table('fuel_reports')->count())->toBe(1)
+        ->and($second->fuel_report_uuid)->toBe($first->fuel_report_uuid);
+    $service->reviewTransaction($second, 'ignored');
+    expect($service->ingestTransaction($connection, $payload)->sync_status)->toBe('ignored');
+});
+
+test('sandbox and production connections cannot overwrite one another’s provider transactions', function () {
+    $db           = fleetopsFuelServiceMatchingBoot();
+    $first        = fleetopsFuelServiceMatchingConnection($db);
+    $second       = clone $first;
+    $second->uuid = 'production-connection';
+    $service      = fleetopsFuelServiceMatchingService();
+    $payload      = ['provider_transaction_id' => 'shared-bill-id', 'amount' => 1000, 'currency' => 'SAR'];
+    $sandbox      = $service->ingestTransaction($first, $payload);
+    $production   = $service->ingestTransaction($second, $payload);
+    expect($sandbox->uuid)->not->toBe($production->uuid)
+        ->and($db->table('fuel_provider_transactions')->count())->toBe(2)
+        ->and($sandbox->fuel_provider_connection_uuid)->toBe($first->uuid)
+        ->and($production->fuel_provider_connection_uuid)->toBe($second->uuid);
+});
+
+test('empty matching rules disable automatic matching', function () {
+    $db                        = fleetopsFuelServiceMatchingBoot();
+    $connection                = fleetopsFuelServiceMatchingConnection($db);
+    $connection->sync_settings = ['matching_order' => []];
+    $db->table('vehicles')->insert(['uuid' => 'vehicle-1', 'company_uuid' => 'company-1', 'plate_number' => 'SGX-1234']);
+    $transaction = fleetopsFuelServiceMatchingService()->ingestTransaction($connection, ['provider_transaction_id' => 'manual-only', 'plate_number' => 'SGX-1234']);
+    expect($transaction->sync_status)->toBe('unmatched')->and($transaction->vehicle_uuid)->toBeNull();
+});
+
+test('sync windows retain the configured lookback after empty runs and reject reversed dates', function () {
+    $db                         = fleetopsFuelServiceMatchingBoot();
+    $connection                 = fleetopsFuelServiceMatchingConnection($db);
+    $connection->sync_settings  = ['window_days' => 7];
+    $connection->last_synced_at = now();
+    $service                    = fleetopsFuelServiceMatchingService();
+    [$from, $to]                = $service->syncWindow($connection);
+    expect($from->toDateString())->toBe(now()->subDays(7)->toDateString())->and($to->toDateString())->toBe(now()->toDateString());
+    expect(fn () => $service->syncWindow($connection, now(), now()->subDay()))->toThrow(InvalidArgumentException::class);
+});
+
+test('ambiguous vehicle identifiers require manual matching', function () {
+    $db         = fleetopsFuelServiceMatchingBoot();
+    $connection = fleetopsFuelServiceMatchingConnection($db, ['sync_settings' => json_encode(['matching_order' => ['plate_number']])]);
+    $db->table('vehicles')->insert([
+        ['uuid' => 'vehicle-1', 'company_uuid' => 'company-1', 'plate_number' => 'ABC 1234'],
+        ['uuid' => 'vehicle-2', 'company_uuid' => 'company-1', 'plate_number' => 'ABC-1234'],
+    ]);
+    $transaction = fleetopsFuelServiceMatchingService()->ingestTransaction($connection, ['provider_transaction_id' => 'ambiguous', 'plate_number' => 'ABC 1234']);
+    expect($transaction->sync_status)->toBe('unmatched')
+        ->and($transaction->vehicle_uuid)->toBeNull()
+        ->and($db->table('fuel_reports')->count())->toBe(0);
+});
+
+test('activity reports persisted totals and isolates the company and connection', function () {
+    $db         = fleetopsFuelServiceMatchingBoot();
+    $connection = fleetopsFuelServiceMatchingConnection($db);
+    foreach ([['conn-1', 'company-1', 300], ['conn-2', 'company-1', 900], ['conn-3', 'company-2', 500]] as [$id, $company, $amount]) {
+        $db->table('fuel_provider_transactions')->insert(['uuid' => 'txn-' . $id, 'fuel_provider_connection_uuid' => $id, 'company_uuid' => $company, 'sync_status' => 'unmatched', 'amount' => $amount, 'currency' => 'SAR', 'volume' => 4]);
+    }
+    $controller = new Fleetbase\FleetOps\Http\Controllers\Internal\v1\FuelProviderConnectionController(fleetopsFuelServiceMatchingService());
+    $activity   = $controller->activity(new Illuminate\Http\Request(), 'conn-1')->getData(true);
+    expect($activity['totals'])->toMatchArray(['transactions' => 1, 'unmatched' => 1, 'liters' => 4, 'fuel_reports' => 0])
+        ->and($activity['totals']['spend'])->toBe([['currency' => 'SAR', 'amount' => 300]])
+        ->and($activity['connection'])->not->toHaveKey('credentials');
+    session(['company' => 'company-2']);
+    expect(fn () => $controller->activity(new Illuminate\Http\Request(), 'conn-1'))->toThrow(Illuminate\Database\Eloquent\ModelNotFoundException::class);
+});
+
+test('terminal worker failures mark a sync failed without destroying its last successful summary', function () {
+    $db = fleetopsFuelServiceMatchingBoot();
+    $db->getSchemaBuilder()->table('fuel_provider_connections', function ($table) {
+        $table->text('last_error')->nullable();
+        $table->text('last_sync_state')->nullable();
+    });
+    $db->getSchemaBuilder()->table('fuel_provider_sync_runs', function ($table) { $table->timestamp('finished_at')->nullable(); });
+    fleetopsFuelServiceMatchingConnection($db, ['last_sync_state' => json_encode(['summary' => ['imported' => 1]])]);
+    $db->table('fuel_provider_sync_runs')->insert(['uuid' => 'run-1', 'fuel_provider_connection_uuid' => 'conn-1', 'status' => 'running']);
+    $job = new Fleetbase\FleetOps\Jobs\SyncFuelProviderTransactionsJob('conn-1', syncRunUuid: 'run-1');
+    $job->failed(new RuntimeException('worker stopped'));
+    expect($db->table('fuel_provider_sync_runs')->value('status'))->toBe('error')
+        ->and($db->table('fuel_provider_sync_runs')->value('finished_at'))->not->toBeNull()
+        ->and(FuelProviderConnection::where('uuid', 'conn-1')->first()->last_sync_state)->toBe(['summary' => ['imported' => 1]]);
+});
+
+test('ingestion persists the report returned by a custom report resolution strategy', function () {
+    $db = fleetopsFuelServiceMatchingBoot();
+    $connection = fleetopsFuelServiceMatchingConnection($db);
+    $db->table('vehicles')->insert(['uuid' => 'vehicle-1', 'company_uuid' => 'company-1', 'plate_number' => 'SGX-1234']);
+    $db->table('fuel_reports')->insert(['uuid' => 'existing-report', 'company_uuid' => 'company-1', 'vehicle_uuid' => 'vehicle-1']);
+    $service = new class(new FuelProviderRegistry()) extends FleetOpsFuelServiceMatchingProbe {
+        protected function ensureFuelReport(FuelProviderTransaction $transaction): ?Fleetbase\FleetOps\Models\FuelReport
+        {
+            return Fleetbase\FleetOps\Models\FuelReport::where('company_uuid', $transaction->company_uuid)->where('vehicle_uuid', $transaction->vehicle_uuid)->firstOrFail();
+        }
+    };
+    $transaction = $service->ingestTransaction($connection, ['provider_transaction_id' => 'existing-report-transaction', 'plate_number' => 'SGX-1234']);
+    expect($transaction->sync_status)->toBe('matched');
+    expect($transaction->fuel_report_uuid)->toBe('existing-report');
+    expect($db->table('fuel_provider_transactions')->value('fuel_report_uuid'))->toBe('existing-report');
+    expect($db->table('fuel_reports')->count())->toBe(1);
+});

package/server/tests/Unit/Support/PetroAppFuelProviderTest.php

@@ -38,7 +38,7 @@ function fleetopsPetroAppConnection(array $credentials = []): FuelProviderConnec
 test('test connection reports success failure and exceptions', function () {
     fleetopsPetroAppFreshHttp();
     Http::fake([
-        'https://petroapp.test/webservice/vehicles*' => Http::response(['data' => ['total' => 12]], 200),
+        'https://petroapp.test/webservice/vehicles*' => Http::response(['data' => ['total' => 12, 'data' => []]], 200),
     ]);
 
     $provider = new PetroAppFuelProvider();
@@ -163,3 +163,128 @@ test('provider identity and header variants resolve correctly', function () {
 
     expect($probe->exposeBaseUrl(fleetopsPetroAppConnection()))->toBe('https://petroapp.test/webservice');
 });
+
+test('environment selects the endpoint for connection tests and imports', function (string $environment, string $baseUrl) {
+    fleetopsPetroAppFreshHttp();
+    Http::preventStrayRequests();
+    Http::fake([
+        $baseUrl . '/vehicles*' => Http::response(['success' => true, 'data' => ['data' => [], 'meta' => ['total' => 123]]]),
+        $baseUrl . '/bills*'    => Http::response(['success' => true, 'data' => ['data' => []]]),
+    ]);
+    $connection              = fleetopsPetroAppConnection(['base_url' => '  ', 'auth_type' => 'ws_sk_header']);
+    $connection->environment = $environment;
+    $provider                = new PetroAppFuelProvider();
+
+    expect($provider->testConnection($connection))
+        ->toMatchArray(['success' => true]);
+    expect($provider->testConnection($connection)['metadata'])->toMatchArray(['total_vehicles' => 123, 'environment' => $environment, 'auth_type' => 'ws_sk_header']);
+    expect($provider->listTransactions($connection, Carbon::parse('2026-09-08'), Carbon::parse('2026-09-15')))->toBeEmpty();
+    Http::assertSent(fn ($request) => $request->url() === $baseUrl . '/vehicles?page=1'
+        && $request->hasHeader('WS-SK', 'token-123') && !$request->hasHeader('Authorization'));
+    Http::assertSent(fn ($request) => str_starts_with($request->url(), $baseUrl . '/bills?')
+        && $request['from'] === '2026-09-08' && $request['to'] === '2026-09-15' && $request['lang'] === 'en');
+})->with([
+    ['sandbox', 'https://app-public.staging.petroapp.app/webservice'],
+    ['production', 'https://app.petroapp.com.sa/webservice'],
+]);
+
+test('HTTP 200 provider errors and malformed payloads fail tests and imports', function ($payload) {
+    fleetopsPetroAppFreshHttp();
+    Http::fake(['*' => Http::response($payload, 200)]);
+    $provider   = new PetroAppFuelProvider();
+    $connection = fleetopsPetroAppConnection();
+
+    expect($provider->testConnection($connection)['success'])->toBeFalse();
+    expect(fn () => $provider->listTransactions($connection, Carbon::now()->subDay(), Carbon::now()))->toThrow(RuntimeException::class);
+})->with([
+    'missing secret'  => [['status' => false, 'message' => 'Secret key is not found']],
+    'invalid bearer'  => [['success' => false, 'message' => 'Unauthenticated.', 'data' => null]],
+    'false with data' => [['success' => false, 'data' => ['data' => []]]],
+    'numeric status'  => [['status' => 0, 'data' => ['data' => []]]],
+    'HTML'            => ['<html>Login</html>'],
+    'missing data'    => [['message' => 'Secret key is not found']],
+]);
+
+test('vehicle resource pagination follows meta and links without following insecure URLs', function () {
+    fleetopsPetroAppFreshHttp();
+    Http::preventStrayRequests();
+    Http::fake([
+        'https://petroapp.test/webservice/vehicles?page=1' => Http::response([
+            'success' => true,
+            'data'    => ['data' => [['vehicle_id' => 1]], 'meta' => ['last_page' => 2], 'links' => ['next' => 'http://petroapp.test/webservice/vehicles?page=2']],
+        ]),
+        'https://petroapp.test/webservice/vehicles?page=2' => Http::response([
+            'success' => true,
+            'data'    => ['data' => [['vehicle_id' => 2]], 'meta' => ['last_page' => 2], 'links' => ['next' => null]],
+        ]),
+    ]);
+
+    expect((new PetroAppFuelProvider())->listVehicles(fleetopsPetroAppConnection())->pluck('vehicle_id')->all())->toBe([1, 2]);
+    Http::assertSentCount(2);
+});
+
+test('legacy token-only forms retry WS-SK only when PetroApp requests the missing secret key', function () {
+    fleetopsPetroAppFreshHttp();
+    Http::preventStrayRequests();
+    Http::fake(function ($request) {
+        if ($request->hasHeader('WS-SK', 'token-123')) {
+            expect($request->hasHeader('Authorization'))->toBeFalse();
+
+            return Http::response(['success' => true, 'data' => ['data' => [['id' => 1]], 'total' => 1]]);
+        }
+
+        expect($request->hasHeader('Authorization', 'Bearer token-123'))->toBeTrue();
+
+        return Http::response(['status' => false, 'message' => 'Secret key is not found']);
+    });
+    $connection = fleetopsPetroAppConnection(['api_token' => " token-123\n"]);
+    $provider   = new PetroAppFuelProvider();
+    $result     = $provider->testConnection($connection);
+    expect($result['success'])->toBeTrue()
+        ->and($result['metadata']['auth_type'])->toBe('ws_sk_header')
+        ->and(data_get($connection->credentials, 'auth_type'))->toBeNull();
+    expect($provider->listVehicles($connection))->toHaveCount(1);
+    Http::assertSentCount(4);
+});
+
+test('explicit authentication is never changed after a missing secret error', function (string $authType) {
+    fleetopsPetroAppFreshHttp();
+    Http::fake(['*' => Http::response(['status' => false, 'message' => 'Secret key is not found'])]);
+    $result = (new PetroAppFuelProvider())->testConnection(fleetopsPetroAppConnection(['auth_type' => $authType]));
+    expect($result['success'])->toBeFalse()->and($result['metadata']['auth_type'])->toBe($authType);
+    Http::assertSentCount(1);
+})->with(['bearer_token', 'ws_sk_header']);
+
+test('working legacy bearer tokens are not retried', function () {
+    fleetopsPetroAppFreshHttp();
+    Http::fake(['*' => Http::response(['success' => true, 'data' => ['data' => [], 'total' => 0]])]);
+    $result = (new PetroAppFuelProvider())->testConnection(fleetopsPetroAppConnection());
+    expect($result['success'])->toBeTrue()->and($result['metadata']['auth_type'])->toBe('bearer_token');
+    Http::assertSentCount(1);
+});
+
+test('PetroApp bill numbers remain stable when a bill is corrected and split plates are combined', function () {
+    $provider = new class extends PetroAppFuelProvider {
+        public function normalize(array $bill): array
+        {
+            return $this->normalizeBill($bill);
+        }
+    };
+    $bill      = ['bill_number' => 32549086, 'plate_letter' => 'ABC', 'plate_snum' => '1234', 'cost' => '3.00', 'num_of_liters' => '4'];
+    $original  = $provider->normalize($bill);
+    $corrected = $provider->normalize(array_merge($bill, ['cost' => '4.50']));
+    expect($original['provider_transaction_id'])->toBe('32549086')
+        ->and($corrected['provider_transaction_id'])->toBe($original['provider_transaction_id'])
+        ->and($original['plate_number'])->toBe('ABC 1234')
+        ->and($corrected['amount'])->toBe(450)
+        ->and($provider->normalize(array_merge($bill, ['plate_snum' => 'ABC 1234']))['plate_number'])->toBe('ABC 1234');
+});
+
+test('pagination limits fail visibly instead of returning a silently incomplete import', function () {
+    fleetopsPetroAppFreshHttp();
+    Http::preventStrayRequests();
+    Http::fake(['*' => Http::response(['success' => true, 'data' => ['data' => [['bill_number' => 1]], 'last_page' => 3]])]);
+    expect(fn () => (new PetroAppFuelProvider())->listTransactions(fleetopsPetroAppConnection(), Carbon::parse('2026-06-23'), Carbon::parse('2026-06-23'), ['max_pages' => 1]))
+        ->toThrow(RuntimeException::class, 'Choose a shorter date range');
+    Http::assertSentCount(1);
+});

package/server/tests/Unit/Support/RadarAgendaTest.php

@@ -0,0 +1,200 @@
+<?php
+
+use Fleetbase\FleetOps\Support\Radar\RadarAgenda;
+use Illuminate\Support\Carbon;
+
+function fleetOpsAgendaNow(): Carbon
+{
+    return Carbon::parse('2026-09-15 08:35:00', 'UTC');
+}
+
+function fleetOpsAgendaItem(string $key, array $extra = []): array
+{
+    [$rule] = explode(':', $key);
+
+    return array_merge([
+        'key'        => $key,
+        'rule'       => $rule,
+        'category'   => 'maintenance',
+        'lane'       => 'maintenance',
+        'chip'       => 'Maint',
+        'severity'   => 'warning',
+        'title'      => $key,
+        'subject'    => null,
+        'due_at'     => null,
+        'due_bucket' => 'none',
+        'window'     => null,
+        'state'      => ['status' => 'open'],
+        'actions'    => [],
+        'record'     => null,
+    ], $extra);
+}
+
+function fleetOpsAgendaDriver(string $name, array $extra = []): array
+{
+    $slug = strtolower(str_replace(' ', '', $name));
+
+    return array_merge(['type' => 'driver', 'uuid' => 'driver-' . $slug, 'public_id' => 'driver_' . $slug, 'label' => $name, 'photo_url' => null], $extra);
+}
+
+afterEach(fn () => Carbon::setTestNow());
+
+test('items land in the overdue band, a lane, the later rail or the anytime tray', function () {
+    $now   = fleetOpsAgendaNow();
+    $items = [
+        fleetOpsAgendaItem('maintenance_overdue:a', ['due_at' => '2026-09-12T08:00:00+00:00', 'due_bucket' => 'overdue']),
+        fleetOpsAgendaItem('maintenance_due_soon:b', ['due_at' => '2026-09-15T14:00:00+00:00', 'due_bucket' => 'today']),
+        fleetOpsAgendaItem('license_expiring:c', ['category' => 'compliance', 'lane' => 'expiries', 'due_at' => '2026-09-21T00:00:00+00:00', 'due_bucket' => 'week']),
+        fleetOpsAgendaItem('notice:d', ['category' => 'notices', 'lane' => 'notices', 'due_at' => '2026-09-16T06:00:00+00:00', 'due_bucket' => 'later']),
+        fleetOpsAgendaItem('issue_open:e', ['category' => 'issues', 'lane' => 'anytime']),
+        fleetOpsAgendaItem('part_low_stock:f', ['category' => 'parts', 'lane' => 'anytime', 'state' => ['status' => 'open', 'planned_at' => '2026-09-15T16:00:00+00:00']]),
+        fleetOpsAgendaItem('fuel_unmatched:g', ['category' => 'fuel', 'lane' => 'anytime', 'state' => ['status' => 'snoozed', 'snoozed_until' => '2026-09-18T08:00:00+00:00']]),
+    ];
+
+    $day = RadarAgenda::build($items, [], '24h', $now);
+
+    expect($day['window']['key'])->toBe('24h')
+        ->and($day['window']['start_at'])->toBe('2026-09-15T08:00:00+00:00')
+        ->and($day['window']['end_at'])->toBe('2026-09-16T08:00:00+00:00')
+        ->and($day['window']['now_pct'])->toBe(2.43)
+        ->and(array_column($day['window']['ticks'], 'label'))->toBe(['08', '10', '12', '14', '16', '18', '20', '22', '00', '02', '04', '06', '08'])
+        ->and(array_column($day['overdue'], 'key'))->toBe(['maintenance_overdue:a'])
+        ->and(array_column($day['lanes']['maintenance'], 'key'))->toBe(['maintenance_due_soon:b', 'part_low_stock:f'])
+        ->and($day['lanes']['maintenance'][0]['pct'])->toBe(25.0)
+        ->and($day['lanes']['maintenance'][0]['label'])->toBe('14:00')
+        ->and($day['lanes']['maintenance'][1]['planned'])->toBeTrue()
+        ->and(array_column($day['lanes']['notices'], 'key'))->toBe(['notice:d'])
+        ->and(array_column($day['later'], 'key'))->toBe(['license_expiring:c'])
+        ->and(array_column($day['anytime'], 'key'))->toBe(['issue_open:e'], 'snoozed items are not on the agenda')
+        ->and($day['counts'])->toBe(['overdue' => 1, 'later' => 1, 'anytime' => 1, 'shifts' => 0]);
+
+    $week = RadarAgenda::build($items, [], '7d', $now);
+    expect($week['window']['hours'])->toBe(168)
+        ->and(array_column($week['lanes']['expiries'], 'key'))->toBe(['license_expiring:c'], 'the 7-day window absorbs the later rail')
+        ->and($week['later'])->toBe([])
+        ->and($week['window']['ticks'][1]['label'])->toBe('Wed 16');
+
+    expect(RadarAgenda::build($items, [], 'bogus', $now)['window']['key'])->toBe('24h');
+});
+
+test('every live shift is a bar on the shifts lane carrying its gaps and handover', function () {
+    $now    = fleetOpsAgendaNow();
+    $ortega = fleetOpsAgendaDriver('Luis Ortega');
+    $diallo = fleetOpsAgendaDriver('Amara Diallo');
+    $items  = [
+        fleetOpsAgendaItem('shift_handover:driver_luisortega', ['category' => 'staffing', 'lane' => 'shifts', 'subject' => $ortega, 'window' => ['start_at' => '2026-09-15T01:15:00+00:00', 'end_at' => '2026-09-15T09:15:00+00:00'], 'due_at' => '2026-09-15T09:15:00+00:00', 'due_bucket' => 'today', 'source' => ['active_orders' => 2]]),
+        fleetOpsAgendaItem('shift_late_start:driver_amaradiallo', ['category' => 'staffing', 'lane' => 'shifts', 'severity' => 'critical', 'subject' => $diallo, 'window' => ['start_at' => '2026-09-15T08:00:00+00:00', 'end_at' => '2026-09-15T16:00:00+00:00']]),
+    ];
+    $shifts = [
+        ['uuid' => 'sh1', 'public_id' => 'shift_1', 'start_at' => '2026-09-15 01:15:00', 'end_at' => '2026-09-15 09:15:00', 'status' => 'in_progress', 'driver' => $ortega, 'driver_online' => true, 'active_orders' => 2],
+        ['uuid' => 'sh2', 'public_id' => 'shift_2', 'start_at' => '2026-09-15 08:00:00', 'end_at' => '2026-09-15 16:00:00', 'status' => 'scheduled', 'driver' => $diallo, 'driver_online' => false, 'active_orders' => 0],
+        ['uuid' => 'sh3', 'public_id' => 'shift_3', 'start_at' => '2026-09-15 14:00:00', 'end_at' => '2026-09-15 21:00:00', 'status' => 'scheduled', 'driver' => fleetOpsAgendaDriver('Tomas Alves'), 'driver_online' => false, 'active_orders' => 0],
+        ['uuid' => 'sh4', 'public_id' => 'shift_4', 'start_at' => '2026-09-17 06:00:00', 'end_at' => '2026-09-17 14:00:00', 'status' => 'scheduled', 'driver' => fleetOpsAgendaDriver('Far Away'), 'driver_online' => false, 'active_orders' => 0],
+        ['uuid' => 'sh5', 'public_id' => 'shift_5', 'start_at' => '2026-09-14 20:00:00', 'end_at' => '2026-09-15 04:00:00', 'status' => 'completed', 'driver' => fleetOpsAgendaDriver('Night Done'), 'driver_online' => false, 'active_orders' => 0],
+    ];
+
+    $day  = RadarAgenda::build($items, $shifts, '24h', $now);
+    $lane = collect($day['lanes']['shifts']);
+    $bars = $lane->where('kind', 'shift')->keyBy('key');
+
+    expect($bars->keys()->all())->toBe(['shift:shift_1', 'shift:shift_2', 'shift:shift_3'])
+        ->and($bars['shift:shift_1']['state'])->toBe('on_shift')
+        ->and($bars['shift:shift_1']['pct'])->toBe(0.0)
+        ->and($bars['shift:shift_1']['width_pct'])->toBe(5.21)
+        ->and($bars['shift:shift_1']['handover_key'])->toBe('shift_handover:driver_luisortega')
+        ->and($bars['shift:shift_1']['gap_keys'])->toBe(['shift_handover:driver_luisortega'])
+        ->and($bars['shift:shift_2']['state'])->toBe('not_online')
+        ->and($bars['shift:shift_2']['severity'])->toBe('critical')
+        ->and($bars['shift:shift_3']['state'])->toBe('upcoming')
+        ->and($bars['shift:shift_3']['pct'])->toBe(25.0)
+        ->and($bars['shift:shift_3']['label'])->toBe('14:00–21:00')
+        ->and($lane->where('kind', 'item')->pluck('key')->all())->toBe(['shift_late_start:driver_amaradiallo', 'shift_handover:driver_luisortega'], 'a live gap sits at the now line, ahead of the 09:15 handover')
+        ->and($day['counts']['shifts'])->toBe(5);
+});
+
+test('a handover card lists the orders and suggests the nearest on-shift driver with capacity', function () {
+    $now    = fleetOpsAgendaNow();
+    $ortega = fleetOpsAgendaDriver('Luis Ortega');
+    $alves  = fleetOpsAgendaDriver('Tomas Alves');
+    $kim    = fleetOpsAgendaDriver('Rin Kim');
+    $full   = fleetOpsAgendaDriver('Full Driver');
+    $early  = fleetOpsAgendaDriver('Ends Early');
+    $items  = [
+        fleetOpsAgendaItem('shift_handover:driver_luisortega', ['category' => 'staffing', 'lane' => 'shifts', 'subject' => $ortega, 'window' => ['start_at' => '2026-09-15T01:15:00+00:00', 'end_at' => '2026-09-15T09:15:00+00:00'], 'due_at' => '2026-09-15T09:15:00+00:00', 'due_bucket' => 'today', 'source' => ['active_orders' => 2], 'record' => ['route' => 'management.drivers.index.details', 'model' => 'driver_luisortega']]),
+    ];
+    $shifts = [
+        ['uuid' => 'sh1', 'start_at' => '2026-09-15 01:15:00', 'end_at' => '2026-09-15 09:15:00', 'status' => 'in_progress', 'driver' => $ortega, 'driver_online' => true],
+        ['uuid' => 'sh2', 'start_at' => '2026-09-15 06:00:00', 'end_at' => '2026-09-15 21:00:00', 'status' => 'in_progress', 'driver' => $alves, 'driver_online' => true],
+        ['uuid' => 'sh3', 'start_at' => '2026-09-15 06:00:00', 'end_at' => '2026-09-15 18:00:00', 'status' => 'in_progress', 'driver' => $kim, 'driver_online' => true],
+        ['uuid' => 'sh4', 'start_at' => '2026-09-15 06:00:00', 'end_at' => '2026-09-15 18:00:00', 'status' => 'in_progress', 'driver' => $full, 'driver_online' => true],
+        ['uuid' => 'sh5', 'start_at' => '2026-09-15 06:00:00', 'end_at' => '2026-09-15 10:00:00', 'status' => 'in_progress', 'driver' => $early, 'driver_online' => true],
+    ];
+    $drivers = [
+        ['uuid' => 'driver-luisortega', 'location' => ['lat' => 40.70, 'lng' => -73.99], 'active_orders' => 2],
+        ['uuid' => 'driver-tomasalves', 'location' => ['lat' => 40.71, 'lng' => -73.98], 'active_orders' => 2, 'max_daily_orders' => 6],
+        ['uuid' => 'driver-rinkim', 'location' => ['lat' => 40.80, 'lng' => -73.90], 'active_orders' => 0],
+        ['uuid' => 'driver-fulldriver', 'location' => ['lat' => 40.70, 'lng' => -73.99], 'active_orders' => 6],
+        ['uuid' => 'driver-endsearly', 'location' => ['lat' => 40.70, 'lng' => -73.99], 'active_orders' => 0],
+    ];
+    $orders = [
+        'driver-luisortega' => [
+            ['uuid' => 'o1', 'public_id' => 'order_88412', 'status' => 'dispatched', 'destination' => 'Bay Ridge', 'ends_at' => '2026-09-15T09:40:00+00:00'],
+            ['uuid' => 'o2', 'public_id' => 'order_88431', 'status' => 'dispatched', 'destination' => 'Sunset Park', 'ends_at' => '2026-09-15T08:50:00+00:00'],
+        ],
+    ];
+
+    $cards = RadarAgenda::handovers($items, $shifts, $drivers, $orders, $now);
+
+    expect($cards)->toHaveCount(1)
+        ->and($cards[0]['key'])->toBe('shift_handover:driver_luisortega')
+        ->and($cards[0]['shift']['minutes_left'])->toBe(40)
+        ->and($cards[0]['rule'])->toBe('shift_handover')
+        ->and(array_column($cards[0]['orders'], 'finishes_after_shift'))->toBe([true, false])
+        ->and($cards[0]['orders'][0]['destination'])->toBe('Bay Ridge')
+        ->and($cards[0]['suggested']['driver']['label'])->toBe('Tomas Alves')
+        ->and($cards[0]['suggested']['distance_km'])->toBe(1.4)
+        ->and($cards[0]['suggested']['capacity_label'])->toBe('2 of 6 orders')
+        ->and($cards[0]['suggested']['on_shift_until'])->toBe('2026-09-15T21:00:00+00:00');
+
+    // Without anyone on shift long enough, the card still exists but has no suggestion.
+    $none = RadarAgenda::handovers($items, [$shifts[0], $shifts[4]], $drivers, $orders, $now);
+    expect($none[0]['suggested'])->toBeNull();
+
+    expect(RadarAgenda::distanceKm(['lat' => 0, 'lng' => 0], ['lat' => 0, 'lng' => 1]))->toBe(111.2)
+        ->and(RadarAgenda::distanceKm(null, ['lat' => 0, 'lng' => 1]))->toBeNull();
+});
+
+test('cover suggestions prefer online drivers, then the nearest, then the least busy', function () {
+    $now      = fleetOpsAgendaNow();
+    $shiftEnd = Carbon::parse('2026-09-15 09:15:00', 'UTC');
+    $shift    = fn (string $name, bool $online) => ['uuid' => 'sh-' . $name, 'start_at' => '2026-09-15 06:00:00', 'end_at' => '2026-09-15 21:00:00', 'status' => 'in_progress', 'driver' => fleetOpsAgendaDriver($name), 'driver_online' => $online];
+
+    $offlineFirst = RadarAgenda::suggestCover('driver-leaving', null, $shiftEnd, [$shift('Offline Olga', false), $shift('Online Omar', true)], [], $now);
+    expect($offlineFirst['driver']['label'])->toBe('Online Omar');
+
+    // With no locations to compare, the driver carrying fewer orders wins.
+    $rows = [
+        'driver-busybea'  => ['uuid' => 'driver-busybea', 'active_orders' => 4],
+        'driver-freefred' => ['uuid' => 'driver-freefred', 'active_orders' => 1],
+    ];
+    $leastBusy = RadarAgenda::suggestCover('driver-leaving', null, $shiftEnd, [$shift('Busy Bea', true), $shift('Free Fred', true)], $rows, $now);
+    expect($leastBusy['driver']['label'])->toBe('Free Fred');
+});
+
+test('a driver with several gaps shows the worst one on their shift bar', function () {
+    $now    = fleetOpsAgendaNow();
+    $driver = fleetOpsAgendaDriver('Amara Diallo');
+    $window = ['start_at' => '2026-09-15T08:00:00+00:00', 'end_at' => '2026-09-15T09:30:00+00:00'];
+    $items  = [
+        fleetOpsAgendaItem('shift_handover:driver_amaradiallo', ['category' => 'staffing', 'lane' => 'shifts', 'severity' => 'warning', 'subject' => $driver, 'window' => $window]),
+        fleetOpsAgendaItem('shift_late_start:driver_amaradiallo', ['category' => 'staffing', 'lane' => 'shifts', 'severity' => 'critical', 'subject' => $driver, 'window' => $window]),
+        fleetOpsAgendaItem('driver_without_vehicle:driver_amaradiallo', ['category' => 'staffing', 'lane' => 'anytime', 'severity' => 'info', 'subject' => $driver]),
+    ];
+    $shifts = [['uuid' => 'sh', 'public_id' => 'shift_a', 'start_at' => '2026-09-15 08:00:00', 'end_at' => '2026-09-15 09:30:00', 'status' => 'scheduled', 'driver' => $driver, 'driver_online' => false]];
+
+    $bar = collect(RadarAgenda::build($items, $shifts, '24h', $now)['lanes']['shifts'])->firstWhere('kind', 'shift');
+
+    expect($bar['severity'])->toBe('critical')
+        ->and($bar['handover_key'])->toBe('shift_handover:driver_amaradiallo')
+        ->and($bar['gap_keys'])->toHaveCount(3);
+});