@fleetbase/fleetops-engine 0.6.57 → 0.6.59

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

@@ -0,0 +1,130 @@
+<?php
+
+use Fleetbase\FleetOps\Support\Analytics\OperationsPulse;
+use Fleetbase\Models\Company;
+use Illuminate\Database\ConnectionResolver;
+use Illuminate\Database\Eloquent\Model as EloquentModel;
+use Illuminate\Database\SQLiteConnection;
+use Illuminate\Support\Carbon;
+
+/**
+ * Covers the OperationsPulse analytics snapshot: the tile aggregation
+ * queries (active orders, drivers online, vehicles deployed, open issues,
+ * completed-today windows) and the delta percentage edge cases.
+ */
+function fleetopsOperationsPulseBoot(): SQLiteConnection
+{
+    $connection = new SQLiteConnection(new PDO('sqlite::memory:'));
+    $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');
+
+    $schema = $connection->getSchemaBuilder();
+    $tables = [
+        'orders'   => ['uuid', 'public_id', 'company_uuid', 'status'],
+        'drivers'  => ['uuid', 'public_id', 'company_uuid', 'user_uuid', 'vehicle_uuid', 'online', 'current_job_uuid', 'status'],
+        'users'    => ['uuid', 'public_id', 'company_uuid'],
+        'vehicles' => ['uuid', 'public_id', 'company_uuid', 'status'],
+        'issues'   => ['uuid', 'public_id', 'company_uuid', 'status'],
+    ];
+    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']);
+
+    return $connection;
+}
+
+function fleetopsOperationsPulseCompany(): Company
+{
+    $company = new Company();
+    $company->setRawAttributes(['uuid' => 'company-1', 'public_id' => 'company_test', 'name' => 'Acme'], true);
+    $company->exists = true;
+
+    return $company;
+}
+
+test('operations pulse aggregates tile metrics from company data', function () {
+    $connection = fleetopsOperationsPulseBoot();
+    $now        = Carbon::now()->toDateTimeString();
+
+    $connection->table('users')->insert(['uuid' => 'user-1', 'company_uuid' => 'company-1']);
+    $connection->table('orders')->insert([
+        ['uuid' => 'order-1', 'company_uuid' => 'company-1', 'status' => 'driver_enroute', 'updated_at' => $now],
+        ['uuid' => 'order-2', 'company_uuid' => 'company-1', 'status' => 'completed', 'updated_at' => $now],
+        ['uuid' => 'order-3', 'company_uuid' => 'company-1', 'status' => 'completed', 'updated_at' => Carbon::now()->subDays(3)->toDateTimeString()],
+    ]);
+    $connection->table('drivers')->insert([
+        ['uuid' => 'driver-1', 'company_uuid' => 'company-1', 'user_uuid' => 'user-1', 'online' => '1', 'current_job_uuid' => 'order-1', 'vehicle_uuid' => 'vehicle-1', 'updated_at' => $now],
+        ['uuid' => 'driver-2', 'company_uuid' => 'company-1', 'user_uuid' => 'user-1', 'online' => '0', 'current_job_uuid' => null, 'vehicle_uuid' => null, 'updated_at' => $now],
+    ]);
+    $connection->table('vehicles')->insert([
+        ['uuid' => 'vehicle-1', 'company_uuid' => 'company-1', 'updated_at' => $now],
+        ['uuid' => 'vehicle-2', 'company_uuid' => 'company-1', 'updated_at' => $now],
+    ]);
+    $connection->table('issues')->insert([
+        ['uuid' => 'issue-1', 'company_uuid' => 'company-1', 'status' => 'pending', 'updated_at' => $now],
+        ['uuid' => 'issue-2', 'company_uuid' => 'company-1', 'status' => 'resolved', 'updated_at' => $now],
+    ]);
+
+    $pulse = OperationsPulse::forCompany(fleetopsOperationsPulseCompany())->get();
+
+    expect($pulse['active_orders']['value'])->toBe(1)
+        ->and($pulse['completed_today']['value'])->toBe(1)
+        // No completions in yesterday's window: delta caps at +100
+        ->and($pulse['completed_today']['delta_pct'])->toBe(100.0)
+        ->and($pulse['drivers_online']['value'])->toBe(1)
+        ->and($pulse['drivers_online']['of'])->toBe(2)
+        ->and($pulse['drivers_online']['pct_of_max'])->toBe(50.0)
+        ->and($pulse['vehicles_deployed']['of'])->toBe(2)
+        ->and($pulse['issues_open']['value'])->toBe(1);
+});
+
+test('operations pulse handles empty companies with null deltas', function () {
+    fleetopsOperationsPulseBoot();
+
+    $pulse = OperationsPulse::forCompany(fleetopsOperationsPulseCompany())->get();
+
+    expect($pulse['active_orders']['value'])->toBe(0)
+        ->and($pulse['completed_today']['value'])->toBe(0)
+        ->and($pulse['completed_today']['delta_pct'])->toBeNull()
+        ->and($pulse['drivers_online']['pct_of_max'])->toBe(0.0)
+        ->and($pulse['vehicles_deployed']['pct_of_max'])->toBe(0.0);
+});
+
+test('delta percentage computes signed rounded changes', function () {
+    fleetopsOperationsPulseBoot();
+
+    $deltaPct = new ReflectionMethod(OperationsPulse::class, 'deltaPct');
+    $deltaPct->setAccessible(true);
+    $pulse = OperationsPulse::forCompany(fleetopsOperationsPulseCompany());
+
+    expect($deltaPct->invoke($pulse, 15, 10))->toBe(50.0)
+        ->and($deltaPct->invoke($pulse, 5, 10))->toBe(-50.0)
+        ->and($deltaPct->invoke($pulse, 0, 0))->toBeNull()
+        ->and($deltaPct->invoke($pulse, 3, 0))->toBe(100.0);
+});

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

@@ -0,0 +1,147 @@
+<?php
+
+use Fleetbase\Ai\Models\AiTask;
+use Fleetbase\FleetOps\Support\Ai\Capabilities\OptimizeOrderRouteCapability;
+use Illuminate\Database\ConnectionResolver;
+use Illuminate\Database\Eloquent\Model as EloquentModel;
+use Illuminate\Database\SQLiteConnection;
+
+/**
+ * Covers the OptimizeOrderRouteCapability apply flow against SQLite as an
+ * admin session user: the not-ready and missing-order and
+ * insufficient-waypoint guards, the successful waypoint update transaction
+ * marking the order optimized, prompt matching, and order resolution from
+ * prompt search terms.
+ */
+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); }');
+}
+
+if (!function_exists('Fleetbase\Support\auth')) {
+    eval('namespace Fleetbase\Support; function auth() { return new class { public function user() { return null; } public function id() { return null; } }; }');
+}
+
+function fleetopsOptimizeRouteBoot(): SQLiteConnection
+{
+    $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');
+
+    $schema = $connection->getSchemaBuilder();
+    $tables = [
+        'users'            => ['uuid', 'public_id', 'company_uuid', 'name', 'type', 'status'],
+        'orders'           => ['uuid', 'public_id', 'internal_id', 'company_uuid', 'payload_uuid', 'status', 'is_route_optimized', 'meta'],
+        'payloads'         => ['uuid', 'public_id', 'company_uuid', 'pickup_uuid', 'dropoff_uuid', 'current_waypoint_uuid', 'meta'],
+        'places'           => ['uuid', 'public_id', 'company_uuid', 'name', 'location', 'type', '_import_id'],
+        'waypoints'        => ['uuid', 'public_id', 'company_uuid', 'payload_uuid', 'place_uuid', 'tracking_number_uuid', 'order', 'type', '_import_id', 'customer_uuid', 'customer_type'],
+        'entities'         => ['uuid', 'public_id', 'company_uuid', 'payload_uuid', 'destination_uuid', 'name', 'type', '_import_id'],
+        'tracking_numbers' => ['uuid', 'public_id', 'company_uuid', 'tracking_number', 'owner_uuid', 'owner_type', 'status_uuid', 'region', 'location', 'qr_code', 'barcode', '_key'],
+    ];
+    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();
+        });
+    }
+
+    // Preload the Contact class so the miscased 'fleetops:contact' default
+    // mutation type resolves case-insensitively in the harness autoloader
+    class_exists(Fleetbase\FleetOps\Models\Contact::class);
+
+    $connection->table('users')->insert(['uuid' => 'admin-1', 'company_uuid' => 'company-1', 'type' => 'admin']);
+    session(['company' => 'company-1', 'user' => 'admin-1']);
+
+    return $connection;
+}
+
+function fleetopsOptimizeRouteTask(string $prompt): AiTask
+{
+    // AiTask is a lightweight bootstrap stand-in hydrated via constructor
+    return new AiTask(['uuid' => 'task-1', 'prompt' => $prompt]);
+}
+
+test('apply guards not ready previews missing orders and waypoint counts', function () {
+    $connection = fleetopsOptimizeRouteBoot();
+    $capability = new OptimizeOrderRouteCapability();
+    $task       = fleetopsOptimizeRouteTask('optimize the route for order ORD-1');
+
+    expect(fn () => $capability->apply($task, ['ready' => false]))
+        ->toThrow(RuntimeException::class, 'not ready to apply');
+
+    expect(fn () => $capability->apply($task, ['ready' => true, 'draft' => ['order_uuid' => 'order-missing']]))
+        ->toThrow(RuntimeException::class, 'Unable to find');
+
+    $connection->table('payloads')->insert(['uuid' => 'payload-1', 'company_uuid' => 'company-1']);
+    $connection->table('orders')->insert(['uuid' => 'order-1', 'public_id' => 'order_route', 'company_uuid' => 'company-1', 'payload_uuid' => 'payload-1']);
+
+    expect(fn () => $capability->apply($task, ['ready' => true, 'draft' => ['order_uuid' => 'order-1', 'waypoints' => [['place_uuid' => 'place-1']]]]))
+        ->toThrow(RuntimeException::class, 'enough waypoints');
+});
+
+test('apply persists optimized waypoints and marks the order', function () {
+    $connection = fleetopsOptimizeRouteBoot();
+    $capability = new OptimizeOrderRouteCapability();
+    $task       = fleetopsOptimizeRouteTask('optimize the route for order ORD-1');
+
+    $connection->table('places')->insert([
+        ['uuid' => 'place-1', 'company_uuid' => 'company-1', 'name' => 'Stop One'],
+        ['uuid' => 'place-2', 'company_uuid' => 'company-1', 'name' => 'Stop Two'],
+    ]);
+    $connection->table('payloads')->insert(['uuid' => 'payload-1', 'company_uuid' => 'company-1']);
+    $connection->table('orders')->insert(['uuid' => 'order-1', 'public_id' => 'order_route', 'company_uuid' => 'company-1', 'payload_uuid' => 'payload-1']);
+
+    $result = $capability->apply($task, ['ready' => true, 'draft' => [
+        'order_uuid' => 'order-1',
+        'waypoints'  => [
+            ['place_uuid' => 'place-1', 'order' => 0],
+            ['place_uuid' => 'place-2', 'order' => 1],
+        ],
+    ]]);
+
+    expect($result['status'])->toBe('completed')
+        ->and($result['resource']['uuid'])->toBe('order-1')
+        ->and($connection->table('orders')->value('is_route_optimized'))->not->toBeNull();
+});
+
+test('prompt matching and order resolution use search terms', function () {
+    $connection = fleetopsOptimizeRouteBoot();
+    $capability = new OptimizeOrderRouteCapability();
+
+    $matches = new ReflectionMethod(OptimizeOrderRouteCapability::class, 'matchesPrompt');
+    $matches->setAccessible(true);
+    expect($matches->invoke($capability, 'optimize route for order ord-1'))->toBeTrue()
+        ->and($matches->invoke($capability, 'show me my orders'))->toBeFalse();
+
+    $connection->table('orders')->insert(['uuid' => 'order-1', 'public_id' => 'order_route77', 'internal_id' => 'ORD-77', 'company_uuid' => 'company-1']);
+
+    $resolve = new ReflectionMethod(OptimizeOrderRouteCapability::class, 'resolveOrders');
+    $resolve->setAccessible(true);
+    $orders = $resolve->invoke($capability, fleetopsOptimizeRouteTask('optimize route for ORD-77'));
+
+    expect($orders)->toHaveCount(1)
+        ->and($orders->first()->uuid)->toBe('order-1');
+});

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

@@ -0,0 +1,135 @@
+<?php
+
+use Fleetbase\FleetOps\Models\Entity;
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Payload;
+use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Orchestration\Support\OrchestrationPayloadBuilder;
+use Fleetbase\LaravelMysqlSpatial\Types\Point;
+use Illuminate\Database\ConnectionResolver;
+use Illuminate\Database\Eloquent\Model as EloquentModel;
+use Illuminate\Database\SQLiteConnection;
+
+/**
+ * Covers the OrchestrationPayloadBuilder computation helpers: payload
+ * demand aggregation with weight and dimension unit conversion plus the
+ * meta fallback, vehicle capacity arrays, vehicle-only VROOM entries with
+ * location/capacity/max-task/skill handling, safe meta access, and
+ * coordinate validation.
+ */
+function fleetopsPayloadBuilderBoot(): void
+{
+    $connection = new SQLiteConnection(new PDO('sqlite::memory:'));
+    $resolver   = new ConnectionResolver(['default' => $connection, 'mysql' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    EloquentModel::setConnectionResolver($resolver);
+}
+
+function fleetopsPayloadBuilderEntity(array $attributes): Entity
+{
+    $entity = new Entity();
+    $entity->setRawAttributes($attributes, true);
+
+    return $entity;
+}
+
+function fleetopsPayloadBuilderInvoke(string $method, ...$arguments): mixed
+{
+    $reflection = new ReflectionMethod(OrchestrationPayloadBuilder::class, $method);
+    $reflection->setAccessible(true);
+
+    return $reflection->invoke(null, ...$arguments);
+}
+
+test('payload demand aggregates entity weights and volumes with unit conversion', function () {
+    fleetopsPayloadBuilderBoot();
+
+    $payload = new Payload();
+    $payload->setRawAttributes(['uuid' => 'payload-1'], true);
+    $payload->setRelation('entities', collect([
+        fleetopsPayloadBuilderEntity(['uuid' => 'ent-1', 'weight' => '2000', 'weight_unit' => 'g', 'length' => '100', 'width' => '50', 'height' => '20', 'dimensions_unit' => 'cm']),
+        fleetopsPayloadBuilderEntity(['uuid' => 'ent-2', 'weight' => '10', 'weight_unit' => 'lb']),
+    ]));
+
+    $order = new Order();
+    $order->setRawAttributes(['uuid' => 'order-1'], true);
+    $order->setRelation('payload', $payload);
+
+    [$weightKg, $volumeLitres, $pallets, $parcels] = fleetopsPayloadBuilderInvoke('computePayloadDemand', $order);
+
+    // 2000g -> 2kg plus 10lb -> ~4.54kg rounds to 7kg
+    expect($weightKg)->toBe(7)
+        // 1m x 0.5m x 0.2m = 0.1m3 -> 100 litres
+        ->and($volumeLitres)->toBe(100)
+        ->and($pallets)->toBe(0)
+        ->and($parcels)->toBe(2);
+});
+
+test('payload demand falls back to order meta without entities', function () {
+    fleetopsPayloadBuilderBoot();
+
+    $order = new Order();
+    $order->setRawAttributes(['uuid' => 'order-1', 'meta' => json_encode(['weight_kg' => 12, 'volume_m3' => 0.5, 'pallets' => 2, 'parcels' => 3])], true);
+    $order->setRelation('payload', null);
+
+    [$weightKg, $volumeLitres, $pallets, $parcels] = fleetopsPayloadBuilderInvoke('computePayloadDemand', $order);
+
+    expect($weightKg)->toBe(12)
+        ->and($volumeLitres)->toBe(500)
+        ->and($pallets)->toBe(2)
+        ->and($parcels)->toBe(3);
+});
+
+test('vehicles only entries include location capacity and optional fields', function () {
+    fleetopsPayloadBuilderBoot();
+
+    $located = new Vehicle();
+    $located->setRawAttributes([
+        'uuid'             => 'vehicle-1',
+        'public_id'        => 'vehicle_vroom',
+        'payload_capacity' => '1200',
+        'max_tasks'        => '5',
+    ], true);
+    $located->setAttribute('location', new Point(1.3, 103.8));
+
+    $unlocated = new Vehicle();
+    $unlocated->setRawAttributes(['uuid' => 'vehicle-2', 'public_id' => 'vehicle_nowhere'], true);
+
+    $entries = OrchestrationPayloadBuilder::buildVehiclesOnly(collect([$located, $unlocated]));
+
+    expect($entries)->toHaveCount(1)
+        ->and($entries[0]['id'])->toBe('vehicle_vroom')
+        ->and($entries[0]['driver_id'])->toBeNull()
+        ->and($entries[0]['start'])->toBe([103.8, 1.3])
+        ->and($entries[0]['max_tasks'])->toBe(5)
+        ->and($entries[0]['capacity'])->toBeArray();
+});
+
+test('safe meta swallows accessor failures and validates coordinates', function () {
+    fleetopsPayloadBuilderBoot();
+
+    $order = new Order();
+    $order->setRawAttributes(['uuid' => 'order-1', 'meta' => json_encode(['priority' => 'high'])], true);
+
+    expect(fleetopsPayloadBuilderInvoke('safeMeta', $order, 'priority'))->toBe('high')
+        ->and(fleetopsPayloadBuilderInvoke('safeMeta', $order, 'missing', 'fallback'))->toBe('fallback');
+
+    // Objects without getMeta throw and fall back safely
+    $broken = new stdClass();
+    expect(fleetopsPayloadBuilderInvoke('safeMeta', $broken, 'anything', 'default'))->toBe('default');
+
+    expect(fleetopsPayloadBuilderInvoke('isValidCoordinate', 103.8, 1.3))->toBeTrue()
+        ->and(fleetopsPayloadBuilderInvoke('isValidCoordinate', 'not-a-number', 1.3))->toBeFalse()
+        ->and(fleetopsPayloadBuilderInvoke('isValidCoordinate', 999, 1.3))->toBeFalse();
+});
+
+test('coordinates resolve from located places and reject unlocated ones', function () {
+    fleetopsPayloadBuilderBoot();
+
+    $place = new Fleetbase\FleetOps\Models\Place();
+    $place->setRawAttributes(['uuid' => 'place-1'], true);
+    $place->setAttribute('location', new Point(1.3, 103.8));
+
+    expect(fleetopsPayloadBuilderInvoke('coordinatesFromPlace', $place))->toBe([103.8, 1.3])
+        ->and(fleetopsPayloadBuilderInvoke('coordinatesFromPlace', null))->toBeNull();
+});

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

@@ -0,0 +1,254 @@
+<?php
+
+use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Payload;
+use Fleetbase\FleetOps\Models\Place;
+use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Models\Waypoint;
+use Fleetbase\FleetOps\Orchestration\Support\OrchestrationPayloadBuilder;
+use Fleetbase\LaravelMysqlSpatial\Types\Point;
+use Illuminate\Database\ConnectionResolver;
+use Illuminate\Database\Eloquent\Model as EloquentModel;
+use Illuminate\Database\SQLiteConnection;
+use Illuminate\Support\Carbon;
+
+/**
+ * Covers OrchestrationPayloadBuilder route and vehicle task construction
+ * with in-memory models: route tasks with stops, invalid-coordinate and
+ * missing-payload reasons, scheduled and explicit time windows, skills and
+ * priority, deprecated job filtering, capacity tasks, route stop candidates
+ * from waypoint markers and plain waypoints, vehicle entries with driver
+ * fallbacks, depot returns, max-task, time-window and merged skill
+ * handling, and skill code resolution.
+ */
+function fleetopsOrchTasksBoot(): void
+{
+    $connection = new SQLiteConnection(new PDO('sqlite::memory:'));
+    $resolver   = new ConnectionResolver(['default' => $connection, 'mysql' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    EloquentModel::setConnectionResolver($resolver);
+}
+
+function fleetopsOrchTasksPlace(string $uuid, ?Point $location): Place
+{
+    $place = new Place();
+    $place->setRawAttributes(['uuid' => $uuid, 'name' => 'Stop ' . $uuid], true);
+    if ($location) {
+        $place->setAttribute('location', $location);
+    }
+
+    return $place;
+}
+
+function fleetopsOrchTasksOrder(array $attributes, ?Payload $payload = null): Order
+{
+    $order = new Order();
+    $order->setRawAttributes($attributes, true);
+    $order->setRelation('payload', $payload);
+
+    return $order;
+}
+
+function fleetopsOrchTasksPayload(?Place $pickup, ?Place $dropoff, $waypointMarkers = null): Payload
+{
+    $payload = new Payload();
+    $payload->setRawAttributes(['uuid' => 'payload-1'], true);
+    $payload->setRelation('pickup', $pickup);
+    $payload->setRelation('dropoff', $dropoff);
+    $payload->setRelation('entities', collect());
+    $payload->setRelation('waypoints', collect());
+    if ($waypointMarkers !== null) {
+        $payload->setRelation('waypointMarkers', $waypointMarkers);
+    }
+
+    return $payload;
+}
+
+test('route tasks build stops time windows skills and priorities', function () {
+    fleetopsOrchTasksBoot();
+
+    $payload = fleetopsOrchTasksPayload(
+        fleetopsOrchTasksPlace('p-1', new Point(1.30, 103.80)),
+        fleetopsOrchTasksPlace('p-2', new Point(1.35, 103.85))
+    );
+    $order = fleetopsOrchTasksOrder([
+        'uuid'                  => 'order-1',
+        'public_id'             => 'order_route1',
+        'scheduled_at'          => '2026-08-01 09:00:00',
+        'orchestrator_priority' => 7,
+        'meta'                  => json_encode(['service_time_seconds' => 120]),
+    ], $payload);
+    $order->setRelation('trackingStatuses', collect());
+
+    $tasks = OrchestrationPayloadBuilder::buildRouteTasks(collect([$order]));
+    expect($tasks)->toHaveCount(1)
+        ->and($tasks[0]['stops'])->toHaveCount(2)
+        ->and($tasks[0]['service'])->toBe(120)
+        ->and($tasks[0]['time_windows'][0][1] - $tasks[0]['time_windows'][0][0])->toBe(4 * 3600)
+        ->and($tasks[0]['priority'])->toBe(7);
+
+    // Explicit time windows outrank the scheduled fallback
+    $windowed = fleetopsOrchTasksOrder([
+        'uuid'              => 'order-2',
+        'public_id'         => 'order_route2',
+        'time_window_start' => '2026-08-01 08:00:00',
+        'time_window_end'   => '2026-08-01 12:00:00',
+    ], fleetopsOrchTasksPayload(
+        fleetopsOrchTasksPlace('p-3', new Point(1.31, 103.81)),
+        fleetopsOrchTasksPlace('p-4', new Point(1.36, 103.86))
+    ));
+    $windowedTask = OrchestrationPayloadBuilder::buildRouteTasks(collect([$windowed]))[0];
+    expect($windowedTask['time_windows'][0][1] - $windowedTask['time_windows'][0][0])->toBe(4 * 3600);
+
+    // A stop without coordinates marks the whole task invalid
+    $invalid = fleetopsOrchTasksOrder([
+        'uuid'      => 'order-3',
+        'public_id' => 'order_route3',
+    ], fleetopsOrchTasksPayload(
+        fleetopsOrchTasksPlace('p-5', null),
+        fleetopsOrchTasksPlace('p-6', new Point(1.37, 103.87))
+    ));
+    $invalidTask = OrchestrationPayloadBuilder::buildRouteTasks(collect([$invalid]))[0];
+    expect($invalidTask['invalid'] ?? false)->toBeTrue();
+
+    // No payload places at all yields the no-stops reason
+    $bare     = fleetopsOrchTasksOrder(['uuid' => 'order-4', 'public_id' => 'order_route4'], fleetopsOrchTasksPayload(null, null));
+    $bareTask = OrchestrationPayloadBuilder::buildRouteTasks(collect([$bare]))[0];
+    expect($bareTask['invalid'] ?? false)->toBeTrue()
+        ->and($bareTask['reason'])->toContain('no routable');
+
+    // The deprecated job builder filters invalid tasks out
+    $jobs = OrchestrationPayloadBuilder::buildJobs(collect([$order, $invalid]));
+    expect($jobs)->toHaveCount(1)
+        ->and($jobs[0]['id'])->toBe('order_route1');
+});
+
+test('capacity tasks flag missing payloads and carry demand vectors', function () {
+    fleetopsOrchTasksBoot();
+
+    $withPayload = fleetopsOrchTasksOrder([
+        'uuid'      => 'order-1',
+        'public_id' => 'order_cap1',
+    ], fleetopsOrchTasksPayload(null, null));
+
+    $withoutPayload = fleetopsOrchTasksOrder(['uuid' => 'order-2', 'public_id' => 'order_cap2'], null);
+
+    $tasks = OrchestrationPayloadBuilder::buildCapacityTasks(collect([$withPayload, $withoutPayload]));
+    expect($tasks)->toHaveCount(2)
+        ->and($tasks[0]['amount'])->toBeArray()
+        ->and($tasks[1]['invalid'])->toBeTrue()
+        ->and($tasks[1]['amount'])->toBe([0, 0, 0, 0]);
+});
+
+test('route stop candidates use waypoint markers then plain waypoints', function () {
+    fleetopsOrchTasksBoot();
+
+    $markerPlace = fleetopsOrchTasksPlace('p-1', new Point(1.32, 103.82));
+    $marker      = new Waypoint();
+    $marker->setRawAttributes(['uuid' => 'wp-1', 'public_id' => 'waypoint_orch1', 'order' => 0], true);
+    $marker->setRelation('place', $markerPlace);
+    $marker->setRelation('trackingNumber', null);
+
+    $payload = fleetopsOrchTasksPayload(
+        fleetopsOrchTasksPlace('p-0', new Point(1.30, 103.80)),
+        fleetopsOrchTasksPlace('p-9', new Point(1.39, 103.89)),
+        collect([$marker])
+    );
+    $order = fleetopsOrchTasksOrder(['uuid' => 'order-1', 'public_id' => 'order_stops1'], $payload);
+
+    $stops = OrchestrationPayloadBuilder::buildRouteStops($order);
+    expect($stops)->toHaveCount(3)
+        ->and($stops[1]['role'])->toBe('waypoint')
+        ->and($stops[1]['waypoint_id'])->toBe('waypoint_orch1')
+        ->and($stops[1]['location'])->toBeArray();
+
+    // Plain waypoint places are used when no markers are loaded
+    $plainPayload = fleetopsOrchTasksPayload(null, null);
+    $plainPayload->setRelation('waypoints', collect([fleetopsOrchTasksPlace('p-2', new Point(1.33, 103.83))]));
+    $plainOrder = fleetopsOrchTasksOrder(['uuid' => 'order-2', 'public_id' => 'order_stops2'], $plainPayload);
+
+    $plainStops = OrchestrationPayloadBuilder::buildRouteStops($plainOrder);
+    expect($plainStops)->toHaveCount(1)
+        ->and($plainStops[0]['role'])->toBe('waypoint');
+});
+
+test('vehicle entries resolve drivers depots windows and skills', function () {
+    fleetopsOrchTasksBoot();
+
+    $driver = new Driver();
+    $driver->setRawAttributes([
+        'uuid'              => 'driver-1',
+        'public_id'         => 'driver_orch1',
+        // Driver has no datetime cast for windows, so store Carbon values
+        'time_window_start' => Carbon::parse('2026-08-01 08:00:00'),
+        'time_window_end'   => Carbon::parse('2026-08-01 18:00:00'),
+        'skills'            => json_encode(['hazmat']),
+    ], true);
+    $driver->setAttribute('location', new Point(1.20, 103.70));
+
+    $vehicle = new Vehicle();
+    $vehicle->setRawAttributes([
+        'uuid'            => 'vehicle-1',
+        'public_id'       => 'vehicle_orch1',
+        'return_to_depot' => 1,
+        'max_tasks'       => 5,
+        'skills'          => json_encode(['cold_chain']),
+    ], true);
+    $vehicle->setAttribute('location', new Point(1.21, 103.71));
+    $vehicle->setRelation('driver', $driver);
+
+    $entries = OrchestrationPayloadBuilder::buildVehicles(collect([$vehicle]));
+    expect($entries)->toHaveCount(1)
+        ->and($entries[0]['driver_id'])->toBe('driver_orch1')
+        ->and($entries[0]['start'])->toBe([103.7, 1.2])
+        ->and($entries[0]['end'])->toBe([103.7, 1.2])
+        ->and($entries[0]['max_tasks'])->toBe(5)
+        ->and($entries[0]['time_window'][1] - $entries[0]['time_window'][0])->toBe(10 * 3600)
+        ->and($entries[0]['skills'])->toHaveCount(2);
+
+    // Vehicles without any start location are dropped
+    $bare = new Vehicle();
+    $bare->setRawAttributes(['uuid' => 'vehicle-2', 'public_id' => 'vehicle_orch2'], true);
+    $bare->setRelation('driver', null);
+    expect(OrchestrationPayloadBuilder::buildVehiclesOnly(collect([$bare])))->toBe([]);
+
+    // Vehicle-only entries carry their own window and depot return
+    $solo = new Vehicle();
+    $solo->setRawAttributes([
+        'uuid'              => 'vehicle-3',
+        'public_id'         => 'vehicle_orch3',
+        'return_to_depot'   => 1,
+        'max_tasks'         => 3,
+        'time_window_start' => Carbon::parse('2026-08-01 07:00:00'),
+        'time_window_end'   => Carbon::parse('2026-08-01 15:00:00'),
+        'skills'            => json_encode(['fragile']),
+    ], true);
+    $solo->setAttribute('location', new Point(1.25, 103.75));
+    $solo->setRelation('driver', null);
+
+    $soloEntries = OrchestrationPayloadBuilder::buildVehiclesOnly(collect([$solo]));
+    expect($soloEntries)->toHaveCount(1)
+        ->and($soloEntries[0]['end'])->toBe([103.75, 1.25])
+        ->and($soloEntries[0]['max_tasks'])->toBe(3)
+        ->and($soloEntries[0]['time_window'][1] - $soloEntries[0]['time_window'][0])->toBe(8 * 3600)
+        ->and($soloEntries[0]['skills'])->toHaveCount(1);
+
+    // Capacity vehicles honor driver windows first then vehicle windows
+    $capacityEntries = OrchestrationPayloadBuilder::buildCapacityVehicles(collect([$vehicle, $solo]));
+    expect($capacityEntries)->toHaveCount(2)
+        ->and($capacityEntries[0]['time_window'][1] - $capacityEntries[0]['time_window'][0])->toBe(10 * 3600)
+        ->and($capacityEntries[1]['time_window'][1] - $capacityEntries[1]['time_window'][0])->toBe(8 * 3600);
+});
+
+test('skill codes hash strings and boolean custom fields uniquely', function () {
+    fleetopsOrchTasksBoot();
+
+    $codes = OrchestrationPayloadBuilder::resolveSkills(['cold_chain', 'cold_chain', ''], ['certified' => true, 'insured' => '1', 'ignored' => false]);
+    expect($codes)->toHaveCount(3)
+        ->and(collect($codes)->every(fn ($code) => is_int($code) && $code > 0))->toBeTrue();
+
+    $legacy = new ReflectionMethod(OrchestrationPayloadBuilder::class, 'extractSkillsFromCustomFields');
+    $legacy->setAccessible(true);
+    expect($legacy->invoke(null, ['certified' => 'true']))->toHaveCount(1);
+});