@fleetbase/fleetops-engine 0.6.47 → 0.6.49

package/server/src/Tracking/TrackingIntelligenceService.php

@@ -0,0 +1,180 @@
+<?php
+
+namespace Fleetbase\FleetOps\Tracking;
+
+use Fleetbase\FleetOps\Models\Order;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Facades\Cache;
+
+class TrackingIntelligenceService
+{
+    public function __construct(
+        protected TrackingContextBuilder $contextBuilder,
+        protected TrackingProviderManager $providerManager,
+    ) {
+    }
+
+    public function track(Order $order, array|TrackingOptions $options = []): array
+    {
+        $options  = $options instanceof TrackingOptions ? $options : TrackingOptions::fromArray($options);
+        $context  = $this->contextBuilder->build($order, $options);
+        $cacheKey = $this->cacheKey($context, $options);
+
+        return Cache::remember($cacheKey, $options->cacheTtlSeconds, function () use ($context, $options) {
+            return $this->buildResult($context, $this->providerManager->track($context, $options), $options);
+        });
+    }
+
+    public function eta(Order $order, array|TrackingOptions $options = []): array
+    {
+        $tracker = $this->track($order, $options);
+
+        return [
+            'active_stop_seconds' => data_get($tracker, 'eta.active_stop_seconds'),
+            'completion_seconds'  => data_get($tracker, 'eta.completion_seconds'),
+            'active_stop_at'      => data_get($tracker, 'eta.active_stop_at'),
+            'completion_at'       => data_get($tracker, 'eta.completion_at'),
+            'provider'            => data_get($tracker, 'provider'),
+            'confidence'          => data_get($tracker, 'confidence'),
+            'warnings'            => data_get($tracker, 'warnings', []),
+        ];
+    }
+
+    protected function buildResult(TrackingContext $context, TrackingProviderResult $providerResult, TrackingOptions $options): array
+    {
+        $now               = now();
+        $completionSeconds = $providerResult->durationInTrafficSeconds ?? $providerResult->durationSeconds;
+        $activeStopSeconds = data_get($providerResult->legs, '0.duration_in_traffic_s', data_get($providerResult->legs, '0.duration_s', $completionSeconds));
+        $progress          = $this->progress($context, $providerResult);
+        $warnings          = array_values(array_unique([...$context->warnings, ...$providerResult->warnings]));
+
+        if ($providerResult->confidence === 'low') {
+            $warnings[] = 'low_confidence_eta';
+        }
+
+        return [
+            'provider'          => $providerResult->provider,
+            'fallback_provider' => in_array('fallback_used', $warnings) ? $providerResult->provider : null,
+            'generated_at'      => $now->toISOString(),
+            'confidence'        => $providerResult->confidence,
+            'warnings'          => array_values(array_unique($warnings)),
+            'driver'            => [
+                'location'             => $this->pointToGeoJson($context->driverLocation),
+                'location_age_seconds' => $context->driverLocationAgeSeconds,
+                'online'               => (bool) data_get($context->driver, 'online', false),
+            ],
+            'progress'          => $progress,
+            'stops'             => $context->stops->map(fn (TrackingStop $stop) => $stop->toArray())->values()->all(),
+            'active_stop'       => $context->activeStop?->toArray(),
+            'next_stop'         => $context->nextStop?->toArray(),
+            'route'             => [
+                'distance_m'            => $providerResult->distanceMeters,
+                'duration_s'            => $providerResult->durationSeconds,
+                'duration_in_traffic_s' => $providerResult->durationInTrafficSeconds,
+                'polyline'              => $providerResult->polyline,
+                'coordinates'           => $providerResult->coordinates,
+                'legs'                  => $this->legs($context, $providerResult, $now),
+            ],
+            'eta'               => [
+                'active_stop_seconds' => $activeStopSeconds,
+                'completion_seconds'  => $completionSeconds,
+                'active_stop_at'      => $this->addSeconds($now, $activeStopSeconds),
+                'completion_at'       => $this->addSeconds($now, $completionSeconds),
+            ],
+            'insights'          => [
+                'is_delayed'          => false,
+                'delay_seconds'       => 0,
+                'is_location_stale'   => in_array('stale_driver_location', $warnings),
+                'is_off_route'        => in_array('off_route', $warnings),
+            ],
+            'capabilities'      => $this->capabilitiesFor($providerResult->provider),
+        ];
+    }
+
+    protected function progress(TrackingContext $context, TrackingProviderResult $providerResult): array
+    {
+        $totalStops     = max($context->stops->count(), 1);
+        $completedStops = $context->completedStops->count();
+        $percentage     = $context->order->status === 'completed' ? 100 : round(($completedStops / $totalStops) * 100, 2);
+
+        return [
+            'percentage'           => $percentage,
+            'completed_stops'      => $completedStops,
+            'remaining_stops'      => $context->remainingStops->count(),
+            'total_stops'          => $context->stops->count(),
+            'completed_distance_m' => null,
+            'remaining_distance_m' => $providerResult->distanceMeters,
+        ];
+    }
+
+    protected function legs(TrackingContext $context, TrackingProviderResult $providerResult, Carbon $now): array
+    {
+        $elapsedSeconds = 0;
+
+        return collect($providerResult->legs)->map(function ($leg, $index) use ($context, $now, &$elapsedSeconds) {
+            $stop        = $context->remainingStops->values()->get($index);
+            $legSeconds  = data_get($leg, 'duration_in_traffic_s', data_get($leg, 'duration_s'));
+            $etaSeconds  = null;
+            $etaAt       = null;
+
+            if ($legSeconds !== null) {
+                $elapsedSeconds += (float) $legSeconds;
+                $etaSeconds = $elapsedSeconds;
+                $etaAt      = $this->addSeconds($now, $etaSeconds);
+            }
+
+            return array_merge($leg, [
+                'stop'        => $stop instanceof TrackingStop ? $stop->toArray() : null,
+                'eta_seconds' => $etaSeconds,
+                'eta_at'      => $etaAt,
+            ]);
+        })->all();
+    }
+
+    protected function capabilitiesFor(string $provider): array
+    {
+        $registry   = app(TrackingProviderRegistry::class);
+        $registered = $registry->get($provider);
+
+        return $registered ? $registered->capabilities()->toArray() : (new TrackingProviderCapabilities())->toArray();
+    }
+
+    protected function cacheKey(TrackingContext $context, TrackingOptions $options): string
+    {
+        return 'order_tracking_intelligence:' . md5(json_encode([
+            'order'      => $context->order->uuid,
+            'order_ts'   => optional($context->order->updated_at)->timestamp,
+            'payload'    => optional($context->payload)->uuid,
+            'payload_ts' => optional($context->payload?->updated_at)->timestamp,
+            'driver'     => optional($context->driver)->uuid,
+            'driver_ts'  => optional($context->driver?->updated_at)->timestamp,
+            'stops'      => $context->stateSignature(),
+            'provider'   => $options->provider,
+            'fallbacks'  => $options->fallbacks,
+            'traffic'    => $options->trafficEnabled,
+            'settings'   => [
+                'summary_ttl'     => $options->cacheTtlSeconds,
+                'route_ttl'       => $options->routeCacheTtlSeconds,
+                'stale_threshold' => $options->staleLocationThresholdSeconds,
+                'fallback_speed'  => $options->defaultVehicleSpeedKph,
+            ],
+        ]));
+    }
+
+    protected function pointToGeoJson($point): ?array
+    {
+        if (!$point) {
+            return null;
+        }
+
+        return [
+            'type'        => 'Point',
+            'coordinates' => [$point->getLng(), $point->getLat()],
+        ];
+    }
+
+    protected function addSeconds(Carbon $now, ?float $seconds): ?string
+    {
+        return $seconds === null ? null : $now->copy()->addSeconds((int) round($seconds))->toISOString();
+    }
+}

package/server/src/Tracking/TrackingOptions.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace Fleetbase\FleetOps\Tracking;
+
+use Fleetbase\Models\Setting;
+use Illuminate\Support\Arr;
+
+class TrackingOptions
+{
+    public function __construct(
+        public ?string $provider = null,
+        public array $fallbacks = [],
+        public bool $trafficEnabled = true,
+        public int $cacheTtlSeconds = 60,
+        public int $routeCacheTtlSeconds = 600,
+        public int $staleLocationThresholdSeconds = 300,
+        public float $defaultVehicleSpeedKph = 35,
+        public array $raw = [],
+    ) {
+    }
+
+    public static function fromArray(array $options = []): self
+    {
+        $systemSettings  = Setting::lookup('fleet-ops.tracking-settings', []);
+        $config          = array_merge(config('fleetops.tracking', []), is_array($systemSettings) ? $systemSettings : []);
+        $companySettings = [];
+        try {
+            $companySettings = Setting::lookupCompany('tracking', []);
+        } catch (\Throwable) {
+            $companySettings = [];
+        }
+
+        $fallbacks = Arr::get($options, 'fallbacks', Arr::get($companySettings, 'fallbacks', Arr::get($config, 'fallbacks', [])));
+        if (is_string($fallbacks)) {
+            $fallbacks = array_values(array_filter(array_map('trim', explode(',', $fallbacks))));
+        }
+
+        return new self(
+            provider: Arr::get($options, 'provider', Arr::get($companySettings, 'provider', Arr::get($config, 'provider'))),
+            fallbacks: Arr::wrap($fallbacks),
+            trafficEnabled: (bool) Arr::get($options, 'traffic_enabled', Arr::get($companySettings, 'traffic_enabled', Arr::get($config, 'traffic_enabled', true))),
+            cacheTtlSeconds: (int) Arr::get($options, 'cache_ttl_seconds', Arr::get($companySettings, 'cache_ttl_seconds', Arr::get($config, 'cache_ttl_seconds', 60))),
+            routeCacheTtlSeconds: (int) Arr::get($options, 'route_cache_ttl_seconds', Arr::get($companySettings, 'route_cache_ttl_seconds', Arr::get($config, 'route_cache_ttl_seconds', 600))),
+            staleLocationThresholdSeconds: (int) Arr::get($options, 'stale_location_threshold_seconds', Arr::get($companySettings, 'stale_location_threshold_seconds', Arr::get($config, 'stale_location_threshold_seconds', 300))),
+            defaultVehicleSpeedKph: (float) Arr::get($options, 'default_vehicle_speed_kph', Arr::get($companySettings, 'default_vehicle_speed_kph', Arr::get($config, 'default_vehicle_speed_kph', 35))),
+            raw: $options
+        );
+    }
+}

package/server/src/Tracking/TrackingProviderCapabilities.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Fleetbase\FleetOps\Tracking;
+
+class TrackingProviderCapabilities implements \JsonSerializable
+{
+    public function __construct(
+        public bool $traffic = false,
+        public bool $perLegEta = false,
+        public bool $mapMatching = false,
+        public bool $routeGeometry = false,
+        public array $extras = [],
+    ) {
+    }
+
+    public function toArray(): array
+    {
+        return array_merge([
+            'traffic'        => $this->traffic,
+            'per_leg_eta'    => $this->perLegEta,
+            'map_matching'   => $this->mapMatching,
+            'route_geometry' => $this->routeGeometry,
+        ], $this->extras);
+    }
+
+    public function jsonSerialize(): mixed
+    {
+        return $this->toArray();
+    }
+}

package/server/src/Tracking/TrackingProviderManager.php

@@ -0,0 +1,89 @@
+<?php
+
+namespace Fleetbase\FleetOps\Tracking;
+
+use Fleetbase\FleetOps\Tracking\Contracts\TrackingProviderInterface;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Str;
+
+class TrackingProviderManager
+{
+    public function __construct(protected TrackingProviderRegistry $registry)
+    {
+    }
+
+    public function track(TrackingContext $context, TrackingOptions $options): TrackingProviderResult
+    {
+        $warnings = [];
+        foreach ($this->providerOrder($options) as $providerKey) {
+            $provider = $this->registry->get($providerKey);
+            if (!$provider instanceof TrackingProviderInterface) {
+                $warnings[] = 'provider_not_registered:' . $providerKey;
+                continue;
+            }
+
+            if (!$provider->canTrack($context)) {
+                $warnings[] = 'provider_unavailable:' . $providerKey;
+                continue;
+            }
+
+            try {
+                $result           = $this->trackWithProviderCache($provider, $context, $options);
+                $result->warnings = array_values(array_unique([...$warnings, ...$result->warnings]));
+
+                if (Str::snake($result->provider) !== Str::snake((string) $options->provider)) {
+                    $result->warnings[] = 'fallback_used';
+                }
+
+                return $result;
+            } catch (\Throwable $e) {
+                $warnings[] = 'provider_failed:' . $providerKey;
+                Log::warning('Tracking provider failed.', [
+                    'provider' => $providerKey,
+                    'order'    => $context->order->public_id ?? $context->order->uuid,
+                    'error'    => $e->getMessage(),
+                ]);
+            }
+        }
+
+        return new TrackingProviderResult(
+            provider: 'none',
+            warnings: array_values(array_unique([...$warnings, 'no_tracking_provider_available'])),
+            confidence: 'none'
+        );
+    }
+
+    protected function providerOrder(TrackingOptions $options): array
+    {
+        $provider  = $options->provider ?: Arr::get(config('fleetops.tracking', []), 'provider', 'google_routes');
+        $fallbacks = $options->fallbacks ?: Arr::get(config('fleetops.tracking', []), 'fallbacks', ['osrm', 'calculated']);
+
+        return collect([$provider, ...$fallbacks])
+            ->filter()
+            ->map(fn ($key) => Str::snake($key))
+            ->unique()
+            ->values()
+            ->all();
+    }
+
+    protected function trackWithProviderCache(TrackingProviderInterface $provider, TrackingContext $context, TrackingOptions $options): TrackingProviderResult
+    {
+        return Cache::remember($this->providerCacheKey($provider, $context, $options), $options->routeCacheTtlSeconds, function () use ($provider, $context, $options) {
+            return $provider->track($context, $options);
+        });
+    }
+
+    protected function providerCacheKey(TrackingProviderInterface $provider, TrackingContext $context, TrackingOptions $options): string
+    {
+        return 'order_tracking_provider_route:' . md5(json_encode([
+            'provider' => $provider->key(),
+            'points'   => array_map(function ($point) {
+                return [$point->getLat(), $point->getLng()];
+            }, $context->routePoints()),
+            'traffic'  => $options->trafficEnabled,
+            'speed'    => $options->defaultVehicleSpeedKph,
+        ]));
+    }
+}

package/server/src/Tracking/TrackingProviderRegistry.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace Fleetbase\FleetOps\Tracking;
+
+use Fleetbase\FleetOps\Tracking\Contracts\TrackingProviderInterface;
+use Illuminate\Support\Str;
+
+class TrackingProviderRegistry
+{
+    protected array $providers = [];
+
+    public function register(TrackingProviderInterface|string $provider, ?string $key = null): self
+    {
+        $instance                      = is_string($provider) ? app($provider) : $provider;
+        $providerKey                   = Str::snake($key ?? $instance->key());
+        $this->providers[$providerKey] = $instance;
+
+        return $this;
+    }
+
+    public function has(string $key): bool
+    {
+        return isset($this->providers[Str::snake($key)]);
+    }
+
+    public function get(string $key): ?TrackingProviderInterface
+    {
+        return $this->providers[Str::snake($key)] ?? null;
+    }
+
+    public function all(): array
+    {
+        return $this->providers;
+    }
+}

package/server/src/Tracking/TrackingProviderResult.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Fleetbase\FleetOps\Tracking;
+
+class TrackingProviderResult
+{
+    public function __construct(
+        public string $provider,
+        public ?float $distanceMeters = null,
+        public ?float $durationSeconds = null,
+        public ?float $durationInTrafficSeconds = null,
+        public ?string $polyline = null,
+        public array $coordinates = [],
+        public array $legs = [],
+        public array $warnings = [],
+        public string $confidence = 'medium',
+        public ?array $raw = null,
+    ) {
+    }
+}

package/server/src/Tracking/TrackingStop.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace Fleetbase\FleetOps\Tracking;
+
+use Fleetbase\FleetOps\Models\Place;
+use Fleetbase\FleetOps\Models\Waypoint;
+use Fleetbase\FleetOps\Support\Utils;
+use Fleetbase\LaravelMysqlSpatial\Types\Point;
+
+class TrackingStop implements \JsonSerializable
+{
+    public function __construct(
+        public ?string $uuid,
+        public ?string $publicId,
+        public string $type,
+        public ?string $status,
+        public ?Place $place,
+        public ?Waypoint $waypoint = null,
+        public bool $completed = false,
+        public ?int $sequence = null,
+    ) {
+    }
+
+    public function point(): ?Point
+    {
+        try {
+            return Utils::getPointFromMixed($this->place);
+        } catch (\Throwable) {
+            return null;
+        }
+    }
+
+    public function toArray(): array
+    {
+        $point = $this->point();
+
+        return [
+            'uuid'       => $this->uuid,
+            'public_id'  => $this->publicId,
+            'type'       => $this->type,
+            'status'     => $this->status,
+            'completed'  => $this->completed,
+            'sequence'   => $this->sequence,
+            'address'    => data_get($this->place, 'address'),
+            'name'       => data_get($this->place, 'name'),
+            'location'   => $point ? [
+                'type'        => 'Point',
+                'coordinates' => [$point->getLng(), $point->getLat()],
+            ] : null,
+            'latitude'   => $point ? $point->getLat() : null,
+            'longitude'  => $point ? $point->getLng() : null,
+        ];
+    }
+
+    public function jsonSerialize(): mixed
+    {
+        return $this->toArray();
+    }
+}

package/server/src/routes.php

@@ -203,6 +203,12 @@ Route::prefix(config('fleetops.api.routing.prefix', null))->namespace('Fleetbase
                 $router->get('{id}', 'LabelController@getLabel');
             });
 
+            // orchestrator routes
+            $router->group(['prefix' => 'orchestrator'], function () use ($router) {
+                $router->post('run', 'OrchestrationController@run');
+                $router->post('commit', 'OrchestrationController@commit');
+            });
+
             // navigator routes
             $router->group(['prefix' => 'onboard'], function () use ($router) {
                 $router->get('driver-onboard-settings/{companyId}', 'NavigatorController@getDriverOnboardSettings');
@@ -339,6 +345,7 @@ Route::prefix(config('fleetops.api.routing.prefix', null))->namespace('Fleetbase
                                 $router->get('next-activity/{id}', $controller('nextActivity'));
                                 $router->get('{id}/tracker', 'OrderController@trackerInfo');
                                 $router->get('{id}/eta', 'OrderController@waypointEtas');
+                                $router->post('{id}/ping-driver', $controller('pingDriver'));
                                 $router->post('process-imports', $controller('importFromFiles'));
                                 $router->patch('route/{id}', $controller('editOrderRoute'));
                                 $router->patch('update-activity/{id}', $controller('updateActivity'));
@@ -546,6 +553,10 @@ Route::prefix(config('fleetops.api.routing.prefix', null))->namespace('Fleetbase
                                         $router->post('notification-settings', 'SettingController@saveNotificationSettings');
                                         $router->get('routing-settings', 'SettingController@getRoutingSettings');
                                         $router->post('routing-settings', 'SettingController@saveRoutingSettings');
+                                        $router->get('tracking-settings', 'SettingController@getTrackingSettings');
+                                        $router->post('tracking-settings', 'SettingController@saveTrackingSettings');
+                                        $router->get('admin-tracking-settings', 'SettingController@getAdminTrackingSettings');
+                                        $router->post('admin-tracking-settings', 'SettingController@saveAdminTrackingSettings');
                                         $router->get('map', 'SettingController@getMapSettings');
                                         $router->post('map', 'SettingController@saveMapSettings');
                                         $router->get('admin-map', 'SettingController@getAdminMapSettings');
@@ -562,6 +573,22 @@ Route::prefix(config('fleetops.api.routing.prefix', null))->namespace('Fleetbase
                                     ['prefix' => 'metrics'],
                                     function ($router) {
                                         $router->get('/', 'MetricsController@all');
+                                        $router->get('{slug}', 'MetricsController@show');
+                                    }
+                                );
+                                $router->group(
+                                    ['prefix' => 'analytics'],
+                                    function ($router) {
+                                        $router->get('operations-pulse',     'AnalyticsController@operationsPulse');
+                                        $router->get('revenue-trend',        'AnalyticsController@revenueTrend');
+                                        $router->get('orders-by-status',     'AnalyticsController@ordersByStatus');
+                                        $router->get('on-time-delivery',     'AnalyticsController@onTimeDelivery');
+                                        $router->get('top-drivers',          'AnalyticsController@topDrivers');
+                                        $router->get('fuel-efficiency',      'AnalyticsController@fuelEfficiency');
+                                        $router->get('issues-insights',      'AnalyticsController@issuesInsights');
+                                        $router->get('maintenance-overview', 'AnalyticsController@maintenanceOverview');
+                                        $router->get('geofence-violations',  'AnalyticsController@geofenceViolations');
+                                        $router->get('live-fleet',           'AnalyticsController@liveFleet');
                                     }
                                 );
                                 $router->group(

package/server/tests/AnalyticsRoutesTest.php

@@ -0,0 +1,41 @@
+<?php
+
+test('analytics routes are registered alongside metrics routes', function () {
+    $routes = file_get_contents(dirname(__DIR__) . '/src/routes.php');
+
+    expect($routes)->toContain("['prefix' => 'analytics']");
+    expect($routes)->toContain("'AnalyticsController@operationsPulse'");
+    expect($routes)->toContain("'AnalyticsController@revenueTrend'");
+    expect($routes)->toContain("'AnalyticsController@ordersByStatus'");
+    expect($routes)->toContain("'AnalyticsController@onTimeDelivery'");
+    expect($routes)->toContain("'AnalyticsController@topDrivers'");
+    expect($routes)->toContain("'AnalyticsController@fuelEfficiency'");
+    expect($routes)->toContain("'AnalyticsController@issuesInsights'");
+    expect($routes)->toContain("'AnalyticsController@maintenanceOverview'");
+    expect($routes)->toContain("'AnalyticsController@geofenceViolations'");
+    expect($routes)->toContain("'AnalyticsController@liveFleet'");
+});
+
+test('per-slug metrics endpoint is registered', function () {
+    $routes = file_get_contents(dirname(__DIR__) . '/src/routes.php');
+
+    expect($routes)->toContain("\$router->get('{slug}', 'MetricsController@show');");
+});
+
+test('legacy metrics endpoint is preserved for backward compat', function () {
+    $routes = file_get_contents(dirname(__DIR__) . '/src/routes.php');
+
+    expect($routes)->toContain("\$router->get('/', 'MetricsController@all');");
+});
+
+test('analytics controller has one method per widget', function () {
+    $controller = file_get_contents(dirname(__DIR__) . '/src/Http/Controllers/Internal/v1/AnalyticsController.php');
+
+    foreach ([
+        'operationsPulse', 'revenueTrend', 'ordersByStatus', 'onTimeDelivery',
+        'topDrivers', 'fuelEfficiency', 'issuesInsights', 'maintenanceOverview',
+        'geofenceViolations', 'liveFleet',
+    ] as $method) {
+        expect($controller)->toContain("public function {$method}(");
+    }
+});

package/server/tests/CapacityAllocationEngineTest.php

@@ -0,0 +1,108 @@
+<?php
+
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Orchestration\Engines\CapacityAllocationEngine;
+
+function capacityTestOrder(string $publicId, float $weightKg, float $volumeLitres = 0, array $skills = []): Order
+{
+    $payload = new class($weightKg, $volumeLitres) {
+        public $entities;
+
+        public function __construct(float $weightKg, float $volumeLitres)
+        {
+            $this->entities = collect([
+                new class($weightKg, $volumeLitres) {
+                    public float $weight;
+                    public string $weight_unit = 'kg';
+                    public float $length;
+                    public float $width = 1;
+                    public float $height = 1;
+                    public string $dimensions_unit = 'm';
+
+                    public function __construct(float $weightKg, float $volumeLitres)
+                    {
+                        $this->weight = $weightKg;
+                        $this->length = $volumeLitres / 1000;
+                    }
+                },
+            ]);
+        }
+    };
+
+    $order = new Order();
+    $order->public_id = $publicId;
+    $order->required_skills = $skills;
+    $order->setRelation('payload', $payload);
+
+    return $order;
+}
+
+function capacityTestVehicle(string $publicId, float $weightKg, float $volumeM3 = 0, int $maxTasks = 0, array $skills = []): Vehicle
+{
+    $vehicle = new Vehicle();
+    $vehicle->public_id = $publicId;
+    $vehicle->payload_capacity = $weightKg;
+    $vehicle->payload_capacity_volume = $volumeM3;
+    $vehicle->payload_capacity_pallets = 0;
+    $vehicle->payload_capacity_parcels = 100;
+    $vehicle->max_tasks = $maxTasks;
+    $vehicle->skills = $skills;
+    $vehicle->setRelation('driver', null);
+
+    return $vehicle;
+}
+
+test('capacity engine assigns orders without vehicle locations', function () {
+    $engine = new CapacityAllocationEngine();
+
+    $result = $engine->allocate(collect([
+        capacityTestOrder('order_light', 10, 250),
+        capacityTestOrder('order_medium', 20, 500),
+    ]), collect([
+        capacityTestVehicle('vehicle_van', 100, 2),
+    ]), [
+        'balance_workload' => false,
+    ]);
+
+    expect($result['assignments'])->toHaveCount(2);
+    expect(array_column($result['assignments'], 'vehicle_id'))->toBe(['vehicle_van', 'vehicle_van']);
+    expect($result['unassigned'])->toBe([]);
+    expect($result['summary']['allocation_strategy'])->toBe('capacity_only');
+});
+
+test('capacity engine rejects over-capacity orders with useful reasons', function () {
+    $engine = new CapacityAllocationEngine();
+
+    $result = $engine->allocate(collect([
+        capacityTestOrder('order_heavy', 250),
+    ]), collect([
+        capacityTestVehicle('vehicle_small', 100),
+    ]));
+
+    expect($result['assignments'])->toBe([]);
+    expect($result['unassigned'])->toBe(['order_heavy']);
+    expect($result['summary']['unassigned_reasons'][0])->toMatchArray([
+        'order_id' => 'order_heavy',
+        'reason'   => 'capacity_exceeded',
+    ]);
+});
+
+test('capacity engine respects skills max tasks and balanced workload', function () {
+    $engine = new CapacityAllocationEngine();
+
+    $result = $engine->allocate(collect([
+        capacityTestOrder('order_cold_1', 10, 0, ['cold_chain']),
+        capacityTestOrder('order_cold_2', 10, 0, ['cold_chain']),
+        capacityTestOrder('order_fragile', 10, 0, ['fragile']),
+    ]), collect([
+        capacityTestVehicle('vehicle_cold_a', 100, 0, 1, ['cold_chain']),
+        capacityTestVehicle('vehicle_cold_b', 100, 0, 1, ['cold_chain']),
+    ]), [
+        'balance_workload' => true,
+    ]);
+
+    expect(array_column($result['assignments'], 'vehicle_id'))->toBe(['vehicle_cold_a', 'vehicle_cold_b']);
+    expect($result['unassigned'])->toBe(['order_fragile']);
+    expect($result['summary']['unassigned_reasons'][0]['reason'])->toBe('missing_required_skills');
+});