@fleetbase/fleetops-engine 0.6.46 → 0.6.48

package/server/tests/OrchestrationPayloadBuilderTest.php

@@ -0,0 +1,132 @@
+<?php
+
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Orchestration\Support\OrchestrationPayloadBuilder;
+use Illuminate\Support\Collection;
+
+function orchestrationTestPlace($lng, $lat)
+{
+    return new class($lng, $lat) {
+        public $location;
+
+        public function __construct($lng, $lat)
+        {
+            $this->location = new class($lng, $lat) {
+                public function __construct(private $lng, private $lat)
+                {
+                }
+
+                public function getLng()
+                {
+                    return $this->lng;
+                }
+
+                public function getLat()
+                {
+                    return $this->lat;
+                }
+            };
+        }
+    };
+}
+
+function orchestrationTestOrder($pickup = null, $dropoff = null, array $waypoints = []): Order
+{
+    $payload = new class($pickup, $dropoff, $waypoints) {
+        public Collection $entities;
+        public Collection $waypointMarkers;
+
+        public function __construct(public $pickup, public $dropoff, array $waypoints)
+        {
+            $this->entities         = collect();
+            $this->waypointMarkers = collect($waypoints)->map(function ($place, $index) {
+                return new class($place, $index) {
+                    public string $public_id;
+                    public string $uuid;
+                    public int $order;
+
+                    public function __construct(public $place, int $index)
+                    {
+                        $this->public_id = 'waypoint_' . $index;
+                        $this->uuid      = 'internal-waypoint-' . $index;
+                        $this->order     = $index;
+                    }
+                };
+            });
+        }
+
+        public function relationLoaded(string $relation): bool
+        {
+            return $relation === 'waypointMarkers';
+        }
+    };
+
+    $order = new Order();
+    $order->public_id = 'order_test';
+    $order->setRelation('payload', $payload);
+
+    return $order;
+}
+
+test('route stops use pickup waypoint dropoff order for mixed payloads', function () {
+    $order = orchestrationTestOrder(
+        orchestrationTestPlace(103.85, 1.28),
+        orchestrationTestPlace(103.90, 1.31),
+        [
+            orchestrationTestPlace(103.86, 1.29),
+            orchestrationTestPlace(103.87, 1.30),
+        ]
+    );
+
+    $stops = OrchestrationPayloadBuilder::buildRouteStops($order);
+
+    expect(array_column($stops, 'role'))->toBe(['pickup', 'waypoint', 'waypoint', 'dropoff']);
+    expect(array_column($stops, 'location'))->toBe([
+        [103.85, 1.28],
+        [103.86, 1.29],
+        [103.87, 1.30],
+        [103.90, 1.31],
+    ]);
+    expect($stops[1])->not->toHaveKey('waypoint_uuid');
+});
+
+test('route stops support endpoint only and waypoint only payloads', function () {
+    $endpointOnly = OrchestrationPayloadBuilder::buildRouteStops(orchestrationTestOrder(
+        orchestrationTestPlace(103.85, 1.28),
+        orchestrationTestPlace(103.90, 1.31)
+    ));
+    $waypointOnly = OrchestrationPayloadBuilder::buildRouteStops(orchestrationTestOrder(
+        null,
+        null,
+        [orchestrationTestPlace(103.86, 1.29)]
+    ));
+
+    expect(array_column($endpointOnly, 'role'))->toBe(['pickup', 'dropoff']);
+    expect(array_column($waypointOnly, 'role'))->toBe(['waypoint']);
+});
+
+test('route stops drop invalid coordinates before vroom payload mapping', function () {
+    $stops = OrchestrationPayloadBuilder::buildRouteStops(orchestrationTestOrder(
+        orchestrationTestPlace('and', 1.28),
+        orchestrationTestPlace(103.90, 1.31)
+    ));
+
+    expect(array_column($stops, 'role'))->toBe(['dropoff']);
+    expect($stops[0]['location'])->toBe([103.90, 1.31]);
+});
+
+test('route tasks mark declared invalid-coordinate stops unassigned', function () {
+    $tasks = OrchestrationPayloadBuilder::buildRouteTasks(collect([
+        orchestrationTestOrder(
+            orchestrationTestPlace('and', 1.28),
+            orchestrationTestPlace(103.90, 1.31)
+        ),
+    ]));
+
+    expect($tasks[0])->toMatchArray([
+        'id'      => 'order_test',
+        'invalid' => true,
+        'stops'   => [],
+    ]);
+    expect($tasks[0]['reason'])->toContain('pickup stop is missing valid coordinates');
+});

package/server/tests/OrchestratorConsumableApiTest.php

@@ -0,0 +1,74 @@
+<?php
+
+use Fleetbase\FleetOps\Http\Controllers\Api\v1\OrchestrationController;
+use Fleetbase\FleetOps\Orchestration\OrchestrationEngineRegistry;
+
+function sanitize_orchestrator_payload(array $payload): array
+{
+    $controller = new OrchestrationController(new OrchestrationEngineRegistry());
+    $method     = new ReflectionMethod($controller, 'sanitizePublicPayload');
+    $method->setAccessible(true);
+
+    return $method->invoke($controller, $payload);
+}
+
+function assert_no_internal_orchestrator_identifiers(array $payload): void
+{
+    foreach ($payload as $key => $value) {
+        expect($key)->not->toBe('uuid');
+        expect($key)->not->toBe('company_uuid');
+        expect($key)->not->toBe('internal_id');
+        expect(str_ends_with((string) $key, '_uuid'))->toBeFalse();
+
+        if (is_array($value)) {
+            assert_no_internal_orchestrator_identifiers($value);
+        }
+    }
+}
+
+test('consumable orchestrator responses remove internal identifiers recursively', function () {
+    $payload = [
+        'assignments' => [
+            [
+                'order_id'      => 'order_123',
+                'order_uuid'    => '6a76d5ef-9d08-4eb9-a235-62406d6a0ed2',
+                'vehicle_id'    => 'vehicle_123',
+                'vehicle_uuid'  => '9a05d9d1-9ff7-460f-a6ee-509a0ed9b345',
+                'driver_id'     => 'driver_123',
+                'internal_id'   => 123,
+                'nested'        => [
+                    'uuid'         => '793f2f9d-5225-49f7-ad22-d73a2c4ea2d1',
+                    'company_uuid' => 'company-internal',
+                    'public_id'    => 'safe_public_id',
+                ],
+            ],
+        ],
+        'unassigned' => ['order_456'],
+        'summary'    => [
+            'routes' => 1,
+            'meta'   => [
+                'request_uuid' => '524c5175-1df2-4e9a-a27b-3107f9e08545',
+            ],
+        ],
+    ];
+
+    $sanitized = sanitize_orchestrator_payload($payload);
+
+    expect($sanitized['assignments'][0])->toMatchArray([
+        'order_id'   => 'order_123',
+        'vehicle_id' => 'vehicle_123',
+        'driver_id'  => 'driver_123',
+    ]);
+    expect($sanitized['assignments'][0]['nested']['public_id'])->toBe('safe_public_id');
+    expect($sanitized['summary']['routes'])->toBe(1);
+
+    assert_no_internal_orchestrator_identifiers($sanitized);
+});
+
+test('consumable orchestrator routes are registered under the public api group', function () {
+    $routes = file_get_contents(__DIR__ . '/../src/routes.php');
+
+    expect($routes)->toContain("['prefix' => 'orchestrator']");
+    expect($routes)->toContain("\$router->post('run', 'OrchestrationController@run');");
+    expect($routes)->toContain("\$router->post('commit', 'OrchestrationController@commit');");
+});

package/server/tests/PingDriverEndpointTest.php

@@ -0,0 +1,19 @@
+<?php
+
+test('ping driver is only exposed through the internal fleetops order route group', function () {
+    $routes = file_get_contents(dirname(__DIR__) . '/src/routes.php');
+
+    expect($routes)->not->toContain("\$router->post('{id}/ping-driver', 'OrderController@pingDriver');")
+        ->and($routes)->toContain("\$router->post('{id}/ping-driver', \$controller('pingDriver'));");
+});
+
+test('ping driver handler belongs to the internal order controller', function () {
+    $apiController      = file_get_contents(dirname(__DIR__) . '/src/Http/Controllers/Api/v1/OrderController.php');
+    $internalController = file_get_contents(dirname(__DIR__) . '/src/Http/Controllers/Internal/v1/OrderController.php');
+
+    expect($apiController)->not->toContain('function pingDriver')
+        ->and($apiController)->not->toContain('Notifications\OrderPing')
+        ->and($internalController)->toContain('function pingDriver')
+        ->and($internalController)->toContain('Notifications\OrderPing')
+        ->and($internalController)->toContain('fleet-ops update order');
+});

package/server/tests/TrackingIntelligenceTest.php

@@ -0,0 +1,176 @@
+<?php
+
+use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Payload;
+use Fleetbase\FleetOps\Models\Place;
+use Fleetbase\FleetOps\Tracking\Providers\CalculatedTrackingProvider;
+use Fleetbase\FleetOps\Tracking\Support\FakeTrackingProvider;
+use Fleetbase\FleetOps\Tracking\TrackingContextBuilder;
+use Fleetbase\FleetOps\Tracking\TrackingOptions;
+use Fleetbase\FleetOps\Tracking\TrackingProviderManager;
+use Fleetbase\FleetOps\Tracking\TrackingProviderRegistry;
+use Fleetbase\LaravelMysqlSpatial\Types\Point;
+use Illuminate\Support\Carbon;
+
+function trackingPlace(string $uuid, float $lat, float $lng): Place
+{
+    $place            = new Place();
+    $place->uuid      = $uuid;
+    $place->public_id = 'place_' . substr($uuid, 0, 8);
+    $place->address   = 'Test address ' . $uuid;
+    $place->location  = new Point($lat, $lng);
+
+    return $place;
+}
+
+function trackingOrderWithStops(): Order
+{
+    $pickup                         = trackingPlace('11111111-1111-1111-1111-111111111111', 1.30, 103.80);
+    $dropoff                        = trackingPlace('22222222-2222-2222-2222-222222222222', 1.35, 103.85);
+    $payload                        = new Payload();
+    $payload->uuid                  = '33333333-3333-3333-3333-333333333333';
+    $payload->current_waypoint_uuid = $pickup->uuid;
+    $payload->setRelation('pickup', $pickup);
+    $payload->setRelation('dropoff', $dropoff);
+    $payload->setRelation('waypoints', collect());
+    $payload->setRelation('waypointMarkers', collect());
+
+    $driver             = new Driver();
+    $driver->uuid       = '44444444-4444-4444-4444-444444444444';
+    $driver->location   = new Point(1.29, 103.79);
+    $driver->online     = true;
+    $driver->updated_at = Carbon::now();
+
+    $order             = new Order();
+    $order->uuid       = '55555555-5555-5555-5555-555555555555';
+    $order->public_id  = 'order_test';
+    $order->status     = 'started';
+    $order->updated_at = Carbon::now();
+    $order->setRelation('payload', $payload);
+    $order->setRelation('driverAssigned', $driver);
+
+    return $order;
+}
+
+test('tracking context builder normalizes order stops and driver telemetry', function () {
+    $context = (new TrackingContextBuilder())->build(trackingOrderWithStops(), TrackingOptions::fromArray([
+        'provider' => 'calculated',
+    ]));
+
+    expect($context->stops)->toHaveCount(2)
+        ->and($context->activeStop?->type)->toBe('dropoff')
+        ->and($context->nextStop)->toBeNull()
+        ->and($context->driverLocationAgeSeconds)->toBeInt()
+        ->and($context->warnings)->toBe([]);
+});
+
+test('tracking context ignores zero coordinate driver location and falls back to pickup origin', function () {
+    $order                           = trackingOrderWithStops();
+    $order->driverAssigned->location = new Point(0, 0);
+
+    $context = (new TrackingContextBuilder())->build($order, TrackingOptions::fromArray([
+        'provider' => 'calculated',
+    ]));
+
+    expect($context->driverLocation)->toBeNull()
+        ->and($context->origin?->getLat())->toBe(1.30)
+        ->and($context->origin?->getLng())->toBe(103.80)
+        ->and($context->routePoints()[0]->getLat())->toBe(1.30)
+        ->and($context->warnings)->toContain('missing_driver_location');
+});
+
+test('calculated provider returns normalized low confidence route data', function () {
+    $context = (new TrackingContextBuilder())->build(trackingOrderWithStops(), TrackingOptions::fromArray([
+        'provider' => 'calculated',
+    ]));
+
+    $result = (new CalculatedTrackingProvider())->track($context, TrackingOptions::fromArray([
+        'provider'                  => 'calculated',
+        'default_vehicle_speed_kph' => 36,
+    ]));
+
+    expect($result->provider)->toBe('calculated')
+        ->and($result->distanceMeters)->toBeGreaterThan(0)
+        ->and($result->durationSeconds)->toBeGreaterThan(0)
+        ->and($result->confidence)->toBe('low')
+        ->and($result->warnings)->toContain('calculated_route_used');
+});
+
+test('tracking route legs include cumulative stop eta values', function () {
+    $context = (new TrackingContextBuilder())->build(trackingOrderWithStops(), TrackingOptions::fromArray([
+        'provider' => 'calculated',
+    ]));
+
+    $result = (new CalculatedTrackingProvider())->track($context, TrackingOptions::fromArray([
+        'provider' => 'calculated',
+    ]));
+    $service = app(Fleetbase\FleetOps\Tracking\TrackingIntelligenceService::class);
+    $method  = new ReflectionMethod($service, 'legs');
+    $method->setAccessible(true);
+    $legs = $method->invoke($service, $context, $result, Carbon::parse('2026-05-12 00:00:00'));
+
+    expect($legs[0]['eta_seconds'])->toBeGreaterThan(0)
+        ->and($legs[0]['eta_at'])->not->toBeNull();
+});
+
+test('provider manager falls back to registered provider and records fallback warning', function () {
+    $registry = new TrackingProviderRegistry();
+    $registry->register(new FakeTrackingProvider('fake'));
+    $manager = new TrackingProviderManager($registry);
+    $context = (new TrackingContextBuilder())->build(trackingOrderWithStops(), TrackingOptions::fromArray([
+        'provider'  => 'missing',
+        'fallbacks' => ['fake'],
+    ]));
+
+    $result = $manager->track($context, TrackingOptions::fromArray([
+        'provider'  => 'missing',
+        'fallbacks' => ['fake'],
+    ]));
+
+    expect($result->provider)->toBe('fake')
+        ->and($result->warnings)->toContain('provider_not_registered:missing')
+        ->and($result->warnings)->toContain('fallback_used');
+});
+
+test('third party providers can be registered through the tracking provider contract', function () {
+    $registry = new TrackingProviderRegistry();
+    $registry->register(new FakeTrackingProvider('tomtom'));
+
+    expect($registry->has('tomtom'))->toBeTrue()
+        ->and($registry->get('tomtom')?->capabilities()->traffic)->toBeTrue();
+});
+
+test('tracking options include route cache ttl and fallback provider settings', function () {
+    $options = TrackingOptions::fromArray([
+        'provider'                => 'calculated',
+        'fallbacks'               => 'osrm,calculated',
+        'route_cache_ttl_seconds' => 900,
+    ]);
+
+    expect($options->provider)->toBe('calculated')
+        ->and($options->fallbacks)->toBe(['osrm', 'calculated'])
+        ->and($options->routeCacheTtlSeconds)->toBe(900);
+});
+
+test('provider cache key varies by route options', function () {
+    $registry = new TrackingProviderRegistry();
+    $manager  = new TrackingProviderManager($registry);
+    $provider = new FakeTrackingProvider('fake');
+    $context  = (new TrackingContextBuilder())->build(trackingOrderWithStops(), TrackingOptions::fromArray([
+        'provider' => 'fake',
+    ]));
+    $method = new ReflectionMethod($manager, 'providerCacheKey');
+    $method->setAccessible(true);
+
+    $trafficKey = $method->invoke($manager, $provider, $context, TrackingOptions::fromArray([
+        'provider'        => 'fake',
+        'traffic_enabled' => true,
+    ]));
+    $nonTrafficKey = $method->invoke($manager, $provider, $context, TrackingOptions::fromArray([
+        'provider'        => 'fake',
+        'traffic_enabled' => false,
+    ]));
+
+    expect($trafficKey)->not->toBe($nonTrafficKey);
+});

package/server/tests/VroomOrchestrationEngineTest.php

@@ -0,0 +1,159 @@
+<?php
+
+use Fleetbase\FleetOps\Orchestration\Engines\VroomOrchestrationEngine;
+
+test('vroom maps multi stop route tasks to shipments', function () {
+    $engine  = new VroomOrchestrationEngine();
+    $method  = new ReflectionMethod($engine, 'mapTaskToShipment');
+    $reverse = [];
+
+    $method->setAccessible(true);
+
+    $shipment = $method->invokeArgs($engine, [[
+        'id'          => 'order_gkATxX2U3P',
+        'stops'       => [
+            ['role' => 'pickup', 'location' => [103.85, 1.28]],
+            ['role' => 'waypoint', 'location' => [103.87, 1.30]],
+            ['role' => 'dropoff', 'location' => [103.90, 1.31]],
+        ],
+        'service'     => 300,
+        'amount'      => [1, 0, 0, 1],
+        'description' => 'order_gkATxX2U3P',
+    ], &$reverse]);
+
+    expect($shipment)->toHaveKeys(['pickup', 'delivery', 'amount']);
+    expect($shipment)->not->toHaveKey('location');
+    expect($shipment['pickup']['location'])->toBe([103.85, 1.28]);
+    expect($shipment['delivery']['location'])->toBe([103.90, 1.31]);
+    expect($shipment['delivery']['service'])->toBe(300);
+    expect(array_values($reverse))->toBe(['order_gkATxX2U3P', 'order_gkATxX2U3P']);
+});
+
+test('vroom maps single stop route tasks to jobs without pickup coordinates', function () {
+    $engine  = new VroomOrchestrationEngine();
+    $method  = new ReflectionMethod($engine, 'mapTaskToVroomJob');
+    $reverse = [];
+
+    $method->setAccessible(true);
+
+    $job = $method->invokeArgs($engine, [[
+        'id'          => 'order_waypointOnly',
+        'stops'       => [
+            ['role' => 'waypoint', 'location' => [103.86, 1.29]],
+        ],
+        'service'     => 300,
+        'amount'      => [1, 0, 0, 1],
+        'description' => 'order_waypointOnly',
+    ], &$reverse]);
+
+    expect($job)->toMatchArray([
+        'location'    => [103.86, 1.29],
+        'description' => 'order_waypointOnly',
+        'service'     => 300,
+        'amount'      => [1, 0, 0, 1],
+    ]);
+    expect($job)->not->toHaveKey('pickup');
+    expect(array_values($reverse))->toBe(['order_waypointOnly']);
+});
+
+test('vroom dedupes unassigned pickup and delivery task ids to one order id', function () {
+    $engine = new VroomOrchestrationEngine();
+    $method = new ReflectionMethod($engine, 'mapVroomResponse');
+
+    $method->setAccessible(true);
+
+    $result = $method->invoke($engine, [
+        'routes'     => [],
+        'unassigned' => [
+            ['id' => 1001],
+            ['id' => 1002],
+        ],
+        'summary' => ['routes' => 0],
+    ], [
+        1001 => 'order_gkATxX2U3P',
+        1002 => 'order_gkATxX2U3P',
+    ]);
+
+    expect($result['unassigned'])->toBe(['order_gkATxX2U3P']);
+});
+
+test('vroom maps shipment delivery steps back to fleetops assignments', function () {
+    $engine = new VroomOrchestrationEngine();
+    $method = new ReflectionMethod($engine, 'mapVroomResponse');
+
+    $method->setAccessible(true);
+
+    $result = $method->invoke($engine, [
+        'routes' => [
+            [
+                'description' => json_encode(['vehicle_id' => 'vehicle_w747Bat', 'driver_id' => null]),
+                'steps'       => [
+                    ['type' => 'start'],
+                    ['type' => 'pickup', 'id' => 1001],
+                    ['type' => 'delivery', 'id' => 1002, 'arrival' => 1778918400, 'duration' => 900, 'distance' => 4200],
+                    ['type' => 'end'],
+                ],
+            ],
+        ],
+        'unassigned' => [],
+        'summary'    => ['routes' => 1],
+    ], [
+        1001 => 'order_gkATxX2U3P',
+        1002 => 'order_gkATxX2U3P',
+    ]);
+
+    expect($result['assignments'])->toHaveCount(1);
+    expect($result['assignments'][0])->toMatchArray([
+        'order_id'   => 'order_gkATxX2U3P',
+        'vehicle_id' => 'vehicle_w747Bat',
+        'driver_id'  => null,
+        'sequence'   => 1,
+        'arrival'    => 1778918400,
+        'duration'   => 900,
+        'distance'   => 4200,
+    ]);
+    expect($result['summary'])->toBe(['routes' => 1]);
+});
+
+test('vroom capacity-only payload uses matrix indexes instead of coordinates', function () {
+    $engine  = new VroomOrchestrationEngine();
+    $method  = new ReflectionMethod($engine, 'buildCapacityOnlyPayload');
+    $reverse = [];
+
+    $method->setAccessible(true);
+
+    $payload = $method->invokeArgs($engine, [[
+        [
+            'id'          => 'order_capacity',
+            'description' => 'order_capacity',
+            'amount'      => [100, 250, 1, 2],
+            'skills'      => [123],
+        ],
+    ], [
+        [
+            'id'        => 'vehicle_capacity',
+            'driver_id' => null,
+            'capacity'  => [500, 1000, 4, 20],
+            'skills'    => [123],
+            'max_tasks' => 3,
+        ],
+    ], [], &$reverse]);
+
+    expect($payload['vehicles'][0])->toMatchArray([
+        'profile'     => 'capacity_only',
+        'start_index' => 0,
+        'capacity'    => [500, 1000, 4, 20],
+        'skills'      => [123],
+        'max_tasks'   => 3,
+    ]);
+    expect($payload['vehicles'][0])->not->toHaveKey('start');
+    expect($payload['jobs'][0])->toMatchArray([
+        'location_index' => 1,
+        'delivery'       => [100, 250, 1, 2],
+        'skills'         => [123],
+    ]);
+    expect($payload['jobs'][0])->not->toHaveKey('location');
+    expect($payload['jobs'][0])->not->toHaveKey('pickup');
+    expect($payload['matrices']['capacity_only']['durations'])->toHaveCount(2);
+    expect(array_values($reverse))->toBe(['order_capacity']);
+});

package/translations/en-us.yaml

@@ -1989,6 +1989,9 @@ orchestrator:
     mode-allocate: Allocate Orders
     mode-optimize: Optimize Routes
     engine: Engine
+    allocation-strategy: Allocation Strategy
+    allocation-strategy-route-aware: Route + Capacity
+    allocation-strategy-capacity-only: Capacity Only
     respect-skills: Respect Skills
     respect-capacity: Respect Capacity
     return-to-depot: Return to Depot
@@ -2029,6 +2032,7 @@ orchestrator:
     no-search-results: No results match your search.
     search-drivers: Search drivers...
     search-vehicles: Search vehicles...
+    no-position: No position
     filter-online: Online
     filter-offline: Offline
     filter-on-shift: On Job