@fleetbase/fleetops-engine 0.6.47 → 0.6.49

package/server/tests/LiveOrderQueryTest.php

@@ -0,0 +1,34 @@
+<?php
+
+use Fleetbase\FleetOps\Support\LiveOrderQuery;
+
+test('active live order query uses the same active status rules as the map overlay', function () {
+    $query = LiveOrderQuery::make('company_test', [
+        'active'            => true,
+        'apply_permissions' => false,
+    ]);
+
+    $bindings = $query->getBindings();
+
+    expect($bindings)->toContain('company_test')
+        ->and($bindings)->toContain('created')
+        ->and($bindings)->toContain('pending')
+        ->and($bindings)->toContain('completed')
+        ->and($bindings)->toContain('canceled')
+        ->and($bindings)->toContain('expired')
+        ->and($bindings)->toContain('order_canceled');
+});
+
+test('live order query requires renderable payload and tracking data', function () {
+    $query = LiveOrderQuery::make('company_test', [
+        'active'            => true,
+        'apply_permissions' => false,
+    ]);
+
+    $sql = $query->toSql();
+
+    expect($sql)->toContain('exists')
+        ->and($sql)->toContain('payload')
+        ->and($sql)->toContain('tracking')
+        ->and($sql)->toContain('driver');
+});

package/server/tests/MetricsRegistryTest.php

@@ -0,0 +1,88 @@
+<?php
+
+use Fleetbase\FleetOps\Support\Metrics\AbstractMetric;
+use Fleetbase\FleetOps\Support\Metrics\AvgOrderValueMetric;
+use Fleetbase\FleetOps\Support\Metrics\EarningsMetric;
+use Fleetbase\FleetOps\Support\Metrics\OpenIssuesMetric;
+use Fleetbase\FleetOps\Support\Metrics\OrdersInProgressMetric;
+use Fleetbase\FleetOps\Support\Metrics\Registry;
+use Fleetbase\FleetOps\Support\Metrics\ResolvedIssuesMetric;
+use Fleetbase\FleetOps\Support\Metrics\TotalTimeTraveledMetric;
+
+test('registry exposes every known metric slug', function () {
+    $slugs = Registry::slugs();
+
+    expect($slugs)->toContain('earnings');
+    expect($slugs)->toContain('fuel_costs');
+    expect($slugs)->toContain('total_distance_traveled');
+    expect($slugs)->toContain('total_time_traveled');
+    expect($slugs)->toContain('orders_completed');
+    expect($slugs)->toContain('orders_canceled');
+    expect($slugs)->toContain('orders_in_progress');
+    expect($slugs)->toContain('orders_scheduled');
+    expect($slugs)->toContain('active_live_orders');
+    expect($slugs)->toContain('drivers_online');
+    expect($slugs)->toContain('total_drivers');
+    expect($slugs)->toContain('total_customers');
+    expect($slugs)->toContain('open_issues');
+    expect($slugs)->toContain('resolved_issues');
+    expect($slugs)->toContain('avg_order_value');
+});
+
+test('registry resolves unknown slugs to null', function () {
+    expect(Registry::resolve('does_not_exist'))->toBeNull();
+});
+
+test('every registered metric extends the abstract base', function () {
+    foreach (Registry::all() as $slug => $class) {
+        expect(is_subclass_of($class, AbstractMetric::class))
+            ->toBeTrue("Metric class for slug '{$slug}' must extend AbstractMetric");
+        expect($class::slug())->toBe($slug);
+    }
+});
+
+test('open and resolved issue metrics scope to the constructor company (not session)', function () {
+    $sourceOpen = file_get_contents(dirname(__DIR__) . '/src/Support/Metrics/OpenIssuesMetric.php');
+    $sourceResolved = file_get_contents(dirname(__DIR__) . '/src/Support/Metrics/ResolvedIssuesMetric.php');
+
+    expect($sourceOpen)->not->toContain("session('company')");
+    expect($sourceOpen)->toContain('$this->company->uuid');
+    expect($sourceResolved)->not->toContain("session('company')");
+    expect($sourceResolved)->toContain('$this->company->uuid');
+});
+
+test('total_time_traveled metric sums the time column, not distance', function () {
+    $source = file_get_contents(dirname(__DIR__) . '/src/Support/Metrics/TotalTimeTraveledMetric.php');
+
+    expect($source)->toContain("\$query->sum('time')");
+    expect($source)->not->toContain("\$query->sum('distance')");
+    expect(TotalTimeTraveledMetric::slug())->toBe('total_time_traveled');
+});
+
+test('money metrics return float values to preserve cents', function () {
+    $earnings = file_get_contents(dirname(__DIR__) . '/src/Support/Metrics/EarningsMetric.php');
+    $fuelCosts = file_get_contents(dirname(__DIR__) . '/src/Support/Metrics/FuelCostsMetric.php');
+
+    expect($earnings)->toContain('(float) $query->sum');
+    expect($earnings)->not->toMatch('/\(int\)\s*\$query->sum/');
+    expect($fuelCosts)->toContain('(float) $query->sum');
+    expect($fuelCosts)->not->toMatch('/\(int\)\s*\$query->sum/');
+});
+
+test('money metrics filter by currency to avoid mixed-currency sums', function () {
+    $earnings = file_get_contents(dirname(__DIR__) . '/src/Support/Metrics/EarningsMetric.php');
+    $fuelCosts = file_get_contents(dirname(__DIR__) . '/src/Support/Metrics/FuelCostsMetric.php');
+    $aov = file_get_contents(dirname(__DIR__) . '/src/Support/Metrics/AvgOrderValueMetric.php');
+
+    expect($earnings)->toContain("->where('currency'");
+    expect($fuelCosts)->toContain("->where('currency'");
+    expect($aov)->toContain("->where('currency'");
+});
+
+test('ordersInProgress uses an explicit allowlist rather than an exclusion list', function () {
+    $statuses = OrdersInProgressMetric::IN_PROGRESS_STATUSES;
+    expect($statuses)->toBeArray();
+    expect($statuses)->not->toBeEmpty();
+    expect($statuses)->toContain('dispatched');
+    expect($statuses)->toContain('started');
+});

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);
+});