@fleetbase/fleetops-engine 0.6.58 → 0.6.59

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

@@ -0,0 +1,309 @@
+<?php
+
+use Illuminate\Database\ConnectionResolver;
+use Illuminate\Database\Eloquent\Model as EloquentModel;
+use Illuminate\Database\SQLiteConnection;
+
+/**
+ * Covers the small query and response seams scattered across controllers,
+ * commands and jobs. Each is a one-line delegation that behaviour tests
+ * override, so the delegation itself is asserted here against SQLite.
+ */
+if (!function_exists('Fleetbase\Events\logger')) {
+    eval('namespace Fleetbase\Events; function logger($message = null, array $context = []) { return new class { public function __call($m, $a) { return null; } }; }');
+}
+
+class FleetOpsQuerySeamEventRecorder
+{
+    public static array $fired = [];
+}
+
+if (!function_exists('Fleetbase\FleetOps\Jobs\event')) {
+    eval('namespace Fleetbase\FleetOps\Jobs; function event($event = null) { \FleetOpsQuerySeamEventRecorder::$fired[] = $event; return $event; }');
+}
+
+if (!function_exists('Fleetbase\Observers\event')) {
+    eval('namespace Fleetbase\Observers; function event($event = null, $payload = []) { return []; }');
+}
+
+if (!function_exists('Fleetbase\FleetOps\Observers\event')) {
+    eval('namespace Fleetbase\FleetOps\Observers; function event($event = null, $payload = []) { return []; }');
+}
+
+if (!function_exists('Fleetbase\Support\session')) {
+    eval('namespace Fleetbase\Support; function session($key = null, $default = null) { if ($key === null) { return new class { public function has($k) { return \session($k) !== null; } public function get($k, $d = null) { return \session($k, $d); } }; } return \session($key, $default); }');
+}
+
+function fleetopsQuerySeamBoot(): SQLiteConnection
+{
+    if (!Illuminate\Support\Str::hasMacro('humanize')) {
+        Illuminate\Support\Str::macro('humanize', fn ($value, $uppercase = true) => str_replace('_', ' ', Illuminate\Support\Str::snake((string) $value)));
+    }
+    $connection = new SQLiteConnection(new PDO('sqlite::memory:'));
+    $resolver   = new ConnectionResolver(['default' => $connection, 'mysql' => $connection, 'sandbox' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    EloquentModel::setConnectionResolver($resolver);
+    if (!EloquentModel::getEventDispatcher()) {
+        EloquentModel::setEventDispatcher(new Illuminate\Events\Dispatcher());
+    }
+    app()->instance('db', new class($connection) {
+        public function __construct(public SQLiteConnection $c)
+        {
+        }
+
+        public function connection($name = null): SQLiteConnection
+        {
+            return $this->c;
+        }
+
+        public function __call($method, $arguments)
+        {
+            return $this->c->{$method}(...$arguments);
+        }
+    });
+    Illuminate\Support\Facades\DB::clearResolvedInstance('db');
+    app()->instance('responsecache', new class {
+        public function __call($method, $arguments)
+        {
+            return null;
+        }
+    });
+    config()->set('activitylog.enabled', false);
+    config()->set('activitylog.default_auth_driver', 'web');
+    app()->bind(Illuminate\Contracts\Config\Repository::class, fn () => config());
+
+    $schema  = $connection->getSchemaBuilder();
+    $columns = ['uuid', 'public_id', 'company_uuid', 'user_uuid', 'name', 'type', 'status', 'provider', 'event', 'geofence_uuid', 'order_uuid', 'service_quote_uuid', 'expired_at', 'driver_assigned_uuid', 'current_job_uuid', 'tracking_number_uuid', 'code', 'details', 'transaction_at', 'connection_uuid', 'amount', 'region', '_key'];
+    foreach (['drivers', 'users', 'companies', 'company_users', 'integrated_vendors', 'geofence_events_log', 'orders', 'service_quotes', 'tracking_numbers', 'tracking_statuses', 'fuel_provider_transactions', 'fuel_provider_connections'] as $table) {
+        $schema->create($table, function ($blueprint) use ($columns) {
+            $blueprint->increments('id');
+            foreach ($columns as $column) {
+                $blueprint->string($column)->nullable();
+            }
+            $blueprint->timestamps();
+            $blueprint->timestamp('deleted_at')->nullable();
+        });
+    }
+
+    session(['company' => 'company-seam-1']);
+
+    return $connection;
+}
+
+function fleetopsQuerySeamInvoke(object $instance, string $class, string $method, array $arguments = []): mixed
+{
+    $reflection = new ReflectionMethod($class, $method);
+    $reflection->setAccessible(true);
+
+    return $reflection->invoke($instance, ...$arguments);
+}
+
+test('integrated vendor controller seams query vendors and shape responses', function () {
+    $connection = fleetopsQuerySeamBoot();
+    $connection->table('integrated_vendors')->insert([
+        ['uuid' => 'iv-seam-1', 'company_uuid' => 'company-seam-1', 'provider' => 'lalamove'],
+        ['uuid' => 'iv-seam-2', 'company_uuid' => 'company-seam-1', 'provider' => 'other'],
+    ]);
+
+    $controller = new Fleetbase\FleetOps\Http\Controllers\Internal\v1\IntegratedVendorController();
+    $class      = Fleetbase\FleetOps\Http\Controllers\Internal\v1\IntegratedVendorController::class;
+
+    // The vendor query narrows to the requested uuids
+    $query = fleetopsQuerySeamInvoke($controller, $class, 'integratedVendorQuery', [['iv-seam-1']]);
+    expect($query->get()->pluck('uuid')->all())->toBe(['iv-seam-1']);
+
+    // The supported-vendor catalogue is exposed as-is
+    expect(fleetopsQuerySeamInvoke($controller, $class, 'supportedIntegratedVendors'))->not->toBeNull();
+
+    // Response helpers wrap payloads and error strings
+    $ok = fleetopsQuerySeamInvoke($controller, $class, 'jsonResponse', [['status' => 'ok'], 200]);
+    expect($ok->getStatusCode())->toBe(200)
+        ->and($ok->getData(true))->toBe(['status' => 'ok']);
+
+    $error = fleetopsQuerySeamInvoke($controller, $class, 'errorResponse', ['nope']);
+    expect($error->getData(true)['error'] ?? null)->toBe('nope');
+});
+
+test('driver company repair seams find drivers memberships and companies', function () {
+    $connection = fleetopsQuerySeamBoot();
+    $connection->table('users')->insert(['uuid' => 'user-fix-1', 'company_uuid' => 'company-seam-1']);
+    $connection->table('drivers')->insert([
+        ['uuid' => 'driver-fix-1', 'company_uuid' => 'company-seam-1', 'user_uuid' => 'user-fix-1'],
+        // No surviving user, so the repair sweep skips it
+        ['uuid' => 'driver-fix-2', 'company_uuid' => 'company-seam-1', 'user_uuid' => 'user-missing'],
+    ]);
+    $connection->table('companies')->insert(['uuid' => 'company-seam-1', 'name' => 'Seam Co']);
+    $connection->table('company_users')->insert(['uuid' => 'cu-1', 'user_uuid' => 'user-fix-1', 'company_uuid' => 'company-seam-1']);
+
+    $command = (new ReflectionClass(Fleetbase\FleetOps\Console\Commands\FixDriverCompanies::class))->newInstanceWithoutConstructor();
+    $class   = Fleetbase\FleetOps\Console\Commands\FixDriverCompanies::class;
+
+    // Only drivers with a surviving user and a company are considered
+    expect(fleetopsQuerySeamInvoke($command, $class, 'drivers')->pluck('uuid')->all())->toBe(['driver-fix-1']);
+
+    // Membership detection distinguishes present from absent rows
+    expect(fleetopsQuerySeamInvoke($command, $class, 'missingCompanyUser', ['user-fix-1', 'company-seam-1']))->toBeFalse()
+        ->and(fleetopsQuerySeamInvoke($command, $class, 'missingCompanyUser', ['user-missing', 'company-seam-1']))->toBeTrue();
+
+    // Company lookups resolve by uuid
+    expect(fleetopsQuerySeamInvoke($command, $class, 'companyByUuid', ['company-seam-1'])?->uuid)->toBe('company-seam-1')
+        ->and(fleetopsQuerySeamInvoke($command, $class, 'companyByUuid', ['company-missing']))->toBeNull();
+});
+
+test('geofence event log seams expose the query builder and raw expressions', function () {
+    $connection = fleetopsQuerySeamBoot();
+    $connection->table('geofence_events_log')->insert([
+        ['uuid' => 'gel-1', 'company_uuid' => 'company-seam-1', 'event' => 'entered'],
+        ['uuid' => 'gel-2', 'company_uuid' => 'company-other', 'event' => 'exited'],
+    ]);
+
+    $controller = new Fleetbase\FleetOps\Http\Controllers\Api\v1\GeofenceController();
+    $class      = Fleetbase\FleetOps\Http\Controllers\Api\v1\GeofenceController::class;
+
+    // Event logs are scoped to the requested company
+    expect(fleetopsQuerySeamInvoke($controller, $class, 'geofenceEventLogQuery', ['company-seam-1'])->get()->pluck('uuid')->all())->toBe(['gel-1']);
+
+    // Table and raw helpers delegate to the database facade
+    expect(fleetopsQuerySeamInvoke($controller, $class, 'table', ['geofence_events_log'])->count())->toBe(2)
+        ->and(fleetopsQuerySeamInvoke($controller, $class, 'raw', ['count(*) as aggregate'])->getValue($connection->getQueryGrammar()))->toBe('count(*) as aggregate');
+});
+
+test('adhoc dispatch seams build order and driver queries', function () {
+    $connection = fleetopsQuerySeamBoot();
+    $connection->table('users')->insert(['uuid' => 'user-adhoc-1', 'company_uuid' => 'company-seam-1']);
+    $connection->table('orders')->insert(['uuid' => 'order-adhoc-1', 'company_uuid' => 'company-seam-1']);
+    $connection->table('drivers')->insert(['uuid' => 'driver-adhoc-1', 'company_uuid' => 'company-seam-1', 'user_uuid' => 'user-adhoc-1']);
+
+    $command = (new ReflectionClass(Fleetbase\FleetOps\Console\Commands\DispatchAdhocOrders::class))->newInstanceWithoutConstructor();
+    $class   = Fleetbase\FleetOps\Console\Commands\DispatchAdhocOrders::class;
+
+    // The order query is bound to the named connection
+    expect(fleetopsQuerySeamInvoke($command, $class, 'newOrderQuery', ['mysql'])->get()->pluck('uuid')->all())->toBe(['order-adhoc-1'])
+        ->and(fleetopsQuerySeamInvoke($command, $class, 'newDriverQuery')->get()->pluck('uuid')->all())->toBe(['driver-adhoc-1']);
+});
+
+test('order finalization job seams resolve records and fire the ready event', function () {
+    $connection = fleetopsQuerySeamBoot();
+    $connection->table('orders')->insert(['uuid' => 'order-final-1', 'company_uuid' => 'company-seam-1']);
+    $connection->table('service_quotes')->insert(['uuid' => 'sq-final-1', 'company_uuid' => 'company-seam-1']);
+
+    $class = Fleetbase\FleetOps\Jobs\FinalizeApiOrderCreation::class;
+    $job   = new $class('order-final-1', 'sq-final-1');
+
+    expect(fleetopsQuerySeamInvoke($job, $class, 'findOrder')?->uuid)->toBe('order-final-1')
+        ->and(fleetopsQuerySeamInvoke($job, $class, 'findServiceQuote')?->uuid)->toBe('sq-final-1');
+
+    // Jobs without a quote uuid short circuit before querying
+    $quoteless = new $class('order-final-1', null);
+    expect(fleetopsQuerySeamInvoke($quoteless, $class, 'findServiceQuote'))->toBeNull();
+});
+
+test('tracking number observer seams generate numbers barcodes and statuses', function () {
+    $connection = fleetopsQuerySeamBoot();
+    $barcode    = new class {
+        public function __call($method, $arguments)
+        {
+            return 'generated-barcode';
+        }
+    };
+    app()->instance('DNS2D', $barcode);
+    app()->instance('DNS1D', $barcode);
+
+    $observer = (new ReflectionClass(Fleetbase\FleetOps\Observers\TrackingNumberObserver::class))->newInstanceWithoutConstructor();
+    $class    = Fleetbase\FleetOps\Observers\TrackingNumberObserver::class;
+
+    $trackingNumber = new Fleetbase\FleetOps\Models\TrackingNumber();
+    $trackingNumber->setRawAttributes(['uuid' => 'tn-seam-1', 'region' => 'SG'], true);
+
+    // Numbers are generated for the record's region
+    expect(fleetopsQuerySeamInvoke($observer, $class, 'generateTrackingNumber', [$trackingNumber]))->toBeString()
+        ->and(fleetopsQuerySeamInvoke($observer, $class, 'generateBarcode', ['tn-seam-1', 'C39']))->toBe('generated-barcode');
+
+    // Statuses are persisted through the model
+    $status = fleetopsQuerySeamInvoke($observer, $class, 'createTrackingStatus', [[
+        'company_uuid'         => 'company-seam-1',
+        'tracking_number_uuid' => 'tn-seam-1',
+        'code'                 => 'CREATED',
+        'status'               => 'Created',
+    ]]);
+    expect($status)->toBeInstanceOf(Fleetbase\FleetOps\Models\TrackingStatus::class)
+        ->and($connection->table('tracking_statuses')->count())->toBe(1);
+});
+
+test('fuel provider summary seams scope transactions and connections', function () {
+    $connection = fleetopsQuerySeamBoot();
+    $connection->table('fuel_provider_transactions')->insert([
+        ['uuid' => 'fpt-1', 'company_uuid' => 'company-seam-1', 'transaction_at' => '2026-07-15 00:00:00'],
+        // Outside the window and another company: both excluded
+        ['uuid' => 'fpt-2', 'company_uuid' => 'company-seam-1', 'transaction_at' => '2026-01-01 00:00:00'],
+        ['uuid' => 'fpt-3', 'company_uuid' => 'company-other', 'transaction_at' => '2026-07-15 00:00:00'],
+    ]);
+    $connection->table('fuel_provider_connections')->insert([
+        ['uuid' => 'fpc-1', 'company_uuid' => 'company-seam-1'],
+        ['uuid' => 'fpc-2', 'company_uuid' => 'company-other'],
+    ]);
+
+    $class   = Fleetbase\FleetOps\Support\Analytics\FuelProviderSummary::class;
+    $summary = (new ReflectionClass($class))->newInstanceWithoutConstructor()
+        ->between(Illuminate\Support\Carbon::parse('2026-07-01')->toDateTime(), Illuminate\Support\Carbon::parse('2026-07-31')->toDateTime());
+
+    // Transactions are scoped to the company and the reporting window
+    expect(fleetopsQuerySeamInvoke($summary, $class, 'transactions', ['company-seam-1'])->pluck('uuid')->all())->toBe(['fpt-1'])
+        ->and(fleetopsQuerySeamInvoke($summary, $class, 'connections', ['company-seam-1'])->pluck('uuid')->all())->toBe(['fpc-1']);
+});
+
+test('shift change listener seams detect creation events and notify drivers', function () {
+    fleetopsQuerySeamBoot();
+
+    $listener = (new ReflectionClass(Fleetbase\FleetOps\Listeners\NotifyDriverOnShiftChange::class))->newInstanceWithoutConstructor();
+    $class    = Fleetbase\FleetOps\Listeners\NotifyDriverOnShiftChange::class;
+
+    // Only schedule-item creation events are treated as creations
+    expect(fleetopsQuerySeamInvoke($listener, $class, 'isCreatedEvent', [new stdClass()]))->toBeFalse();
+});
+
+test('order finalization fires the order ready event', function () {
+    fleetopsQuerySeamBoot();
+    FleetOpsQuerySeamEventRecorder::$fired = [];
+
+    $order = new Fleetbase\FleetOps\Models\Order();
+    $order->setRawAttributes(['uuid' => 'order-ready-1', 'public_id' => 'order_readyone'], true);
+
+    $class = Fleetbase\FleetOps\Jobs\FinalizeApiOrderCreation::class;
+    $job   = new $class('order-ready-1');
+    fleetopsQuerySeamInvoke($job, $class, 'fireOrderReady', [$order]);
+
+    expect(FleetOpsQuerySeamEventRecorder::$fired)->toHaveCount(1)
+        ->and(FleetOpsQuerySeamEventRecorder::$fired[0])->toBeInstanceOf(Fleetbase\FleetOps\Events\OrderReady::class);
+});
+
+test('adhoc dispatch finds online drivers for the orders company', function () {
+    $connection = fleetopsQuerySeamBoot();
+    $connection->table('users')->insert([
+        ['uuid' => 'user-adhoc-a', 'company_uuid' => 'company-seam-1'],
+        ['uuid' => 'user-adhoc-b', 'company_uuid' => 'company-other'],
+    ]);
+    $connection->getSchemaBuilder()->table('drivers', function ($blueprint) {
+        $blueprint->string('online')->nullable();
+    });
+    $connection->table('drivers')->insert([
+        // Online and in the order's company
+        ['uuid' => 'driver-near-1', 'company_uuid' => 'company-seam-1', 'user_uuid' => 'user-adhoc-a', 'online' => '1'],
+        // Online but another company
+        ['uuid' => 'driver-near-2', 'company_uuid' => 'company-other', 'user_uuid' => 'user-adhoc-b', 'online' => '1'],
+        // Right company but offline
+        ['uuid' => 'driver-near-3', 'company_uuid' => 'company-seam-1', 'user_uuid' => 'user-adhoc-a', 'online' => '0'],
+    ]);
+
+    $order = new Fleetbase\FleetOps\Models\Order();
+    $order->setRawAttributes(['uuid' => 'order-adhoc-near', 'company_uuid' => 'company-seam-1'], true);
+
+    $class   = Fleetbase\FleetOps\Console\Commands\DispatchAdhocOrders::class;
+    $command = (new ReflectionClass($class))->newInstanceWithoutConstructor();
+    $pickup  = new Fleetbase\LaravelMysqlSpatial\Types\Point(1.30, 103.80);
+
+    // In testing mode the spatial predicates are skipped so the company and
+    // online filters can be asserted on their own
+    $drivers = $command->getNearbyDriversForOrder($order, $pickup, 5000, true);
+    expect($drivers->pluck('uuid')->all())->toBe(['driver-near-1']);
+});

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

@@ -0,0 +1,303 @@
+<?php
+
+use Fleetbase\FleetOps\Flow\Activity;
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Payload;
+use Fleetbase\FleetOps\Models\Place;
+use Fleetbase\FleetOps\Models\Proof;
+use Fleetbase\FleetOps\Models\TrackingNumber;
+use Fleetbase\FleetOps\Models\Waypoint;
+use Fleetbase\FleetOps\Support\ResolvesOrderServiceStops;
+use Illuminate\Database\ConnectionResolver;
+use Illuminate\Database\Eloquent\Model as EloquentModel;
+use Illuminate\Database\SQLiteConnection;
+use Illuminate\Support\Str;
+
+/**
+ * Covers the database-backed ResolvesOrderServiceStops helpers that the
+ * fake-based trait test cannot reach: proof resolution, stop completion
+ * via stored tracking statuses, destination advancement, current-stop
+ * activity detection, endpoint tracking-number creation, endpoint activity
+ * insertion, and tracking-number status lookups.
+ */
+if (!function_exists('Fleetbase\FleetOps\Support\event')) {
+    eval('namespace Fleetbase\FleetOps\Support; function event($event = null) { \FleetOpsServiceStopsDbRecorder::$events[] = $event; return $event; }');
+}
+
+class FleetOpsServiceStopsDbRecorder
+{
+    public static array $events = [];
+}
+
+class FleetOpsServiceStopsDbProbe
+{
+    use ResolvesOrderServiceStops;
+
+    public function callHelper(string $method, ...$arguments): mixed
+    {
+        return $this->{$method}(...$arguments);
+    }
+}
+
+function fleetopsServiceStopsDbBoot(): SQLiteConnection
+{
+    if (!Str::hasMacro('humanize')) {
+        Str::macro('humanize', fn ($value, $uppercase = true) => str_replace('_', ' ', Str::snake((string) $value)));
+    }
+
+    $pdo = new PDO('sqlite::memory:');
+    $pdo->sqliteCreateFunction('ST_PointFromText', fn ($wkt, $srid = 0, $axisOrder = null) => $wkt);
+    $pdo->sqliteCreateFunction('ST_GeomFromText', fn ($wkt, $srid = 0, $axisOrder = null) => $wkt);
+    $connection = new SQLiteConnection($pdo);
+    $resolver   = new ConnectionResolver(['default' => $connection, 'mysql' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    EloquentModel::setConnectionResolver($resolver);
+    app()->instance('db', new class($connection) {
+        public function __construct(public SQLiteConnection $c)
+        {
+        }
+
+        public function connection($name = null): SQLiteConnection
+        {
+            return $this->c;
+        }
+
+        public function __call($method, $arguments)
+        {
+            return $this->c->{$method}(...$arguments);
+        }
+    });
+    Illuminate\Support\Facades\DB::clearResolvedInstance('db');
+
+    $barcodeFake = new class {
+        public function __call($method, $arguments)
+        {
+            return 'barcode';
+        }
+    };
+    app()->instance('DNS2D', $barcodeFake);
+    app()->instance('DNS1D', $barcodeFake);
+
+    $schema = $connection->getSchemaBuilder();
+    app()->instance('db.schema', $schema);
+    $tables = [
+        'orders'            => ['uuid', 'public_id', 'company_uuid', 'payload_uuid', 'order_config_uuid', 'status', 'type', 'meta'],
+        'payloads'          => ['uuid', 'public_id', 'company_uuid', 'pickup_uuid', 'dropoff_uuid', 'return_uuid', 'current_waypoint_uuid', 'pickup_tracking_number_uuid', 'dropoff_tracking_number_uuid', 'meta'],
+        'places'            => ['uuid', 'public_id', 'company_uuid', 'name', 'street1', 'city', 'country', 'province', 'location', 'meta'],
+        'waypoints'         => ['uuid', 'public_id', 'company_uuid', 'payload_uuid', 'place_uuid', 'tracking_number_uuid', 'order', 'type'],
+        'tracking_numbers'  => ['uuid', 'public_id', 'company_uuid', 'tracking_number', 'region', 'location', 'status_uuid', 'owner_uuid', 'owner_type', 'qr_code', 'barcode', '_key'],
+        'tracking_statuses' => ['uuid', 'public_id', 'company_uuid', 'tracking_number_uuid', 'proof_uuid', 'status', 'details', 'location', 'code', 'complete', '_key'],
+        'proofs'            => ['uuid', 'public_id', 'company_uuid', 'subject_uuid', 'subject_type', 'remarks', 'raw_data', 'data'],
+        'entities'          => ['uuid', 'public_id', 'company_uuid', 'payload_uuid', 'destination_uuid', 'name', 'type'],
+        'companies'         => ['uuid', 'public_id', 'name', 'country'],
+    ];
+    foreach ($tables as $table => $columns) {
+        $schema->create($table, function ($blueprint) use ($columns) {
+            $blueprint->increments('id');
+            foreach ($columns as $column) {
+                $blueprint->string($column)->nullable();
+            }
+            $blueprint->timestamps();
+            $blueprint->timestamp('deleted_at')->nullable();
+        });
+    }
+
+    session(['company' => 'company-1']);
+    $connection->table('companies')->insert(['uuid' => 'company-1', 'public_id' => 'company_test', 'name' => 'Acme', 'country' => 'SG']);
+    FleetOpsServiceStopsDbRecorder::$events = [];
+
+    return $connection;
+}
+
+function fleetopsServiceStopsDbPlace(string $uuid, string $name): Place
+{
+    $place = new Place();
+    $place->setRawAttributes(['uuid' => $uuid, 'public_id' => 'place_' . $uuid, 'company_uuid' => 'company-1', 'name' => $name, 'country' => 'SG'], true);
+    $place->exists = true;
+
+    return $place;
+}
+
+function fleetopsServiceStopsDbPayload(): Payload
+{
+    $payload = new Payload();
+    $payload->setRawAttributes(['uuid' => 'payload-1', 'public_id' => 'payload_test', 'company_uuid' => 'company-1'], true);
+    $payload->exists = true;
+
+    $payload->setRelation('pickup', fleetopsServiceStopsDbPlace('place-p', 'Pickup'));
+    $payload->setRelation('dropoff', fleetopsServiceStopsDbPlace('place-d', 'Dropoff'));
+    $payload->setRelation('waypoints', collect());
+    $payload->setRelation('waypointMarkers', collect());
+    $payload->setRelation('entities', collect());
+
+    return $payload;
+}
+
+function fleetopsServiceStopsDbOrder(Payload $payload, string $status = 'created'): Order
+{
+    $order = new Order();
+    $order->setRawAttributes(['uuid' => 'order-1', 'public_id' => 'order_test', 'company_uuid' => 'company-1', 'payload_uuid' => $payload->uuid, 'status' => $status], true);
+    $order->exists = true;
+    $order->setRelation('payload', $payload);
+
+    return $order;
+}
+
+test('proof resolution accepts instances public ids and rejects other input', function () {
+    $connection = fleetopsServiceStopsDbBoot();
+    $probe      = new FleetOpsServiceStopsDbProbe();
+
+    $proof = new Proof();
+    $proof->setRawAttributes(['uuid' => 'proof-1', 'public_id' => 'proof_test'], true);
+    expect($probe->callHelper('resolveProof', $proof))->toBe($proof);
+
+    $connection->table('proofs')->insert(['uuid' => 'proof-2', 'public_id' => 'proof_stored', 'company_uuid' => 'company-1']);
+    expect($probe->callHelper('resolveProof', 'proof_stored')?->uuid)->toBe('proof-2')
+        ->and($probe->callHelper('resolveProof', 42))->toBeNull();
+});
+
+test('endpoint stop completion reads stored tracking statuses', function () {
+    $connection = fleetopsServiceStopsDbBoot();
+    $probe      = new FleetOpsServiceStopsDbProbe();
+    $payload    = fleetopsServiceStopsDbPayload();
+    $order      = fleetopsServiceStopsDbOrder($payload);
+    $stops      = $probe->callHelper('payloadServiceStops', $payload);
+
+    // Completed tracking statuses complete the endpoint stop
+    $connection->table('tracking_numbers')->insert(['uuid' => 'tn-p', 'company_uuid' => 'company-1', 'status_uuid' => 'ts-p']);
+    $connection->table('tracking_statuses')->insert(['uuid' => 'ts-p', 'tracking_number_uuid' => 'tn-p', 'code' => 'COMPLETED', 'complete' => '1']);
+    $payload->pickup_tracking_number_uuid = 'tn-p';
+
+    expect($probe->callHelper('serviceStopIsComplete', $order, $payload, $stops->first()))->toBeTrue();
+});
+
+test('next incomplete stop resolution advances the payload destination', function () {
+    $connection = fleetopsServiceStopsDbBoot();
+    $probe      = new FleetOpsServiceStopsDbProbe();
+    $payload    = fleetopsServiceStopsDbPayload();
+    $order      = fleetopsServiceStopsDbOrder($payload);
+    $connection->table('payloads')->insert(['uuid' => 'payload-1', 'company_uuid' => 'company-1']);
+
+    // Current stop defaults to the first (pickup); next incomplete is dropoff
+    $next = $probe->callHelper('nextIncompleteServiceStop', $order, $payload);
+    expect($next['type'])->toBe('dropoff');
+
+    $advanced = $probe->callHelper('advanceCurrentServiceStopDestination', $order, $payload);
+    expect($advanced['type'])->toBe('dropoff')
+        ->and($payload->current_waypoint_uuid)->toBe('place-d');
+
+    // With the dropoff current there is nothing further to advance to
+    expect($probe->callHelper('advanceCurrentServiceStopDestination', $order, $payload))->toBeNull();
+});
+
+test('current stop activity detection checks tracking status codes', function () {
+    $connection = fleetopsServiceStopsDbBoot();
+    $probe      = new FleetOpsServiceStopsDbProbe();
+    $payload    = fleetopsServiceStopsDbPayload();
+    $activity   = new Activity(['code' => 'dispatched', 'status' => 'Dispatched', 'details' => 'Order dispatched']);
+
+    // No tracking number on the current endpoint stop
+    expect($probe->callHelper('payloadHasCurrentServiceStopActivity', $payload, $activity))->toBeFalse()
+        ->and($probe->callHelper('payloadHasCurrentServiceStopActivity', null, $activity))->toBeFalse();
+
+    // Matching tracking status code found for the endpoint stop
+    $connection->table('tracking_numbers')->insert(['uuid' => 'tn-p', 'company_uuid' => 'company-1']);
+    $connection->table('tracking_statuses')->insert(['uuid' => 'ts-1', 'tracking_number_uuid' => 'tn-p', 'code' => 'DISPATCHED']);
+    $payload->pickup_tracking_number_uuid = 'tn-p';
+    expect($probe->callHelper('payloadHasCurrentServiceStopActivity', $payload, $activity))->toBeTrue();
+
+    // Waypoint stops check their own tracking number
+    $waypoint = new Waypoint();
+    $waypoint->setRawAttributes(['uuid' => 'wp-1', 'payload_uuid' => 'payload-1', 'place_uuid' => 'place-w', 'tracking_number_uuid' => 'tn-p', 'order' => '1'], true);
+    $waypoint->exists = true;
+    $waypoint->setRelation('place', fleetopsServiceStopsDbPlace('place-w', 'Waypoint'));
+    $waypoint->setRelation('trackingNumber', null);
+    $payload->setRelation('waypointMarkers', collect([$waypoint]));
+    $payload->current_waypoint_uuid = 'wp-1';
+    expect($probe->callHelper('payloadHasCurrentServiceStopActivity', $payload, $activity))->toBeTrue();
+
+    $waypoint->tracking_number_uuid = null;
+    expect($probe->callHelper('payloadHasCurrentServiceStopActivity', $payload, $activity))->toBeFalse();
+});
+
+test('endpoint tracking numbers resolve existing rows and create new ones', function () {
+    $connection = fleetopsServiceStopsDbBoot();
+    $probe      = new FleetOpsServiceStopsDbProbe();
+    $payload    = fleetopsServiceStopsDbPayload();
+    $order      = fleetopsServiceStopsDbOrder($payload);
+    $stops      = $probe->callHelper('payloadServiceStops', $payload);
+
+    // Without create nothing is resolved
+    expect($probe->callHelper('endpointServiceStopTrackingNumber', $order, $payload, $stops->first(), false))->toBeNull();
+
+    // Creation persists a tracking number and links it on the payload
+    $connection->table('payloads')->insert(['uuid' => 'payload-1', 'company_uuid' => 'company-1']);
+    $created = $probe->callHelper('endpointServiceStopTrackingNumber', $order, $payload, $stops->first(), true);
+    expect($created)->toBeInstanceOf(TrackingNumber::class)
+        ->and($connection->table('tracking_numbers')->count())->toBe(1);
+
+    // Existing linked tracking numbers resolve directly
+    $existing = $probe->callHelper('endpointServiceStopTrackingNumber', $order, $payload, $stops->first(), false);
+    expect($existing)->toBeInstanceOf(TrackingNumber::class);
+});
+
+test('endpoint activity insertion writes tracking statuses and updates the number', function () {
+    $connection = fleetopsServiceStopsDbBoot();
+    $probe      = new FleetOpsServiceStopsDbProbe();
+    $payload    = fleetopsServiceStopsDbPayload();
+    $order      = fleetopsServiceStopsDbOrder($payload);
+    $stops      = $probe->callHelper('payloadServiceStops', $payload);
+    $activity   = new Activity(['code' => 'completed', 'status' => 'Completed', 'details' => 'Stop completed']);
+
+    $connection->table('payloads')->insert(['uuid' => 'payload-1', 'company_uuid' => 'company-1']);
+
+    $activityId = $probe->callHelper('insertEndpointServiceStopActivity', $order, $payload, $stops->first(), $activity, [1.3, 103.8]);
+
+    // Tracking-number creation writes an initial CREATED status; the
+    // endpoint activity adds the COMPLETED one and links it on the number.
+    expect($activityId)->not->toBeNull()
+        ->and($connection->table('tracking_statuses')->count())->toBe(2)
+        ->and($connection->table('tracking_statuses')->where('code', 'COMPLETED')->count())->toBe(1)
+        ->and($connection->table('tracking_numbers')->value('status_uuid'))->toBe($activityId);
+});
+
+test('tracking number status lookup prefers the linked status uuid', function () {
+    $connection = fleetopsServiceStopsDbBoot();
+    $probe      = new FleetOpsServiceStopsDbProbe();
+
+    expect($probe->callHelper('trackingNumberStatus', 'missing'))->toBeNull();
+
+    $connection->table('tracking_numbers')->insert(['uuid' => 'tn-1', 'company_uuid' => 'company-1', 'status_uuid' => 'ts-2']);
+    $connection->table('tracking_statuses')->insert([
+        ['uuid' => 'ts-1', 'tracking_number_uuid' => 'tn-1', 'code' => 'CREATED'],
+        ['uuid' => 'ts-2', 'tracking_number_uuid' => 'tn-1', 'code' => 'DISPATCHED'],
+    ]);
+    expect($probe->callHelper('trackingNumberStatus', 'tn-1')?->code)->toBe('DISPATCHED');
+
+    // Without a linked status the latest row wins
+    $connection->table('tracking_numbers')->where('uuid', 'tn-1')->update(['status_uuid' => null]);
+    expect($probe->callHelper('trackingNumberStatus', 'tn-1'))->not->toBeNull();
+});
+
+test('update current stop activity records endpoint activity or bails without location', function () {
+    $connection = fleetopsServiceStopsDbBoot();
+    $probe      = new FleetOpsServiceStopsDbProbe();
+    $payload    = fleetopsServiceStopsDbPayload();
+    $order      = fleetopsServiceStopsDbOrder($payload);
+    $activity   = new Activity(['code' => 'started', 'status' => 'Started', 'details' => 'Order started']);
+
+    $connection->table('payloads')->insert(['uuid' => 'payload-1', 'company_uuid' => 'company-1']);
+
+    // Without a location the stop is returned untouched
+    $probe->callHelper('updateCurrentServiceStopActivity', $order, $activity, null);
+    expect($connection->table('tracking_statuses')->count())->toBe(0);
+
+    // With a location the endpoint activity is inserted (plus the initial
+    // CREATED status written when the tracking number is generated)
+    $probe->callHelper('updateCurrentServiceStopActivity', $order, $activity, [1.3, 103.8]);
+    expect($connection->table('tracking_statuses')->where('code', 'STARTED')->count())->toBe(1);
+
+    // skipEndpointOrderActivity suppresses the insertion
+    $probe->callHelper('updateCurrentServiceStopActivity', $order, $activity, [1.3, 103.8], null, true);
+    expect($connection->table('tracking_statuses')->where('code', 'STARTED')->count())->toBe(1);
+});