@fleetbase/fleetops-engine 0.6.46 → 0.6.48

package/server/src/Orchestration/Engines/VroomOrchestrationEngine.php

@@ -50,7 +50,7 @@ class VroomOrchestrationEngine implements OrchestrationEngineInterface
     /**
      * Run the VROOM VRP solver.
      *
-     * Constructs a VROOM-format payload from the normalized jobs/vehicles
+     * Constructs a VROOM-format payload from the normalized route tasks/vehicles
      * produced by OrchestrationPayloadBuilder, calls the VROOM HTTP API, and
      * maps the response back to the standard OrchestrationEngineInterface result
      * shape.
@@ -59,31 +59,57 @@ class VroomOrchestrationEngine implements OrchestrationEngineInterface
      */
     public function allocate(Collection $orders, Collection $vehicles, array $options = []): array
     {
-        $jobs          = OrchestrationPayloadBuilder::buildJobs($orders);
+        if (($options['allocation_strategy'] ?? null) === 'capacity_only') {
+            return $this->allocateCapacityOnly($orders, $vehicles, $options);
+        }
+
+        $tasks         = OrchestrationPayloadBuilder::buildRouteTasks($orders);
         $vroomVehicles = OrchestrationPayloadBuilder::buildVehicles($vehicles);
 
-        if (empty($jobs)) {
-            return ['assignments' => [], 'unassigned' => [], 'summary' => []];
+        [$routeTasks, $invalidTasks] = $this->partitionRouteTasks($tasks);
+
+        if (empty($routeTasks)) {
+            return $this->mergeInvalidTasks([
+                'assignments' => [],
+                'unassigned'  => [],
+                'summary'     => [],
+            ], $invalidTasks);
         }
 
+        $jobIdReverse = [];
+        $profile      = $options['profile'] ?? env('VROOM_PROFILE', 'driving');
+
         // Map normalized vehicle entries to VROOM vehicle objects.
         // The 'driver_id' key is not part of the VROOM spec — we carry it in
         // a description field and use it when mapping results back.
         $vroomPayload = [
-            'jobs'     => $jobs,
-            'vehicles' => array_map(function (array $v) {
+            'jobs'      => [],
+            'shipments' => [],
+            'vehicles' => array_map(function (array $v) use ($profile) {
                 $vehicle = [
                     'id'          => crc32($v['id']), // VROOM requires integer IDs
                     'description' => json_encode(['vehicle_id' => $v['id'], 'driver_id' => $v['driver_id']]),
                     'start'       => $v['start'],
                     'capacity'    => $v['capacity'],
                 ];
+                if ($profile) {
+                    $vehicle['profile'] = $profile;
+                }
+                if (isset($v['end'])) {
+                    $vehicle['end'] = $v['end'];
+                }
                 if (isset($v['time_window'])) {
                     $vehicle['time_window'] = $v['time_window'];
                 }
                 if (isset($v['skills'])) {
                     $vehicle['skills'] = $v['skills'];
                 }
+                if (isset($v['max_tasks'])) {
+                    $vehicle['max_tasks'] = $v['max_tasks'];
+                }
+                if (isset($v['max_travel_time'])) {
+                    $vehicle['max_travel_time'] = $v['max_travel_time'];
+                }
 
                 return $vehicle;
             }, $vroomVehicles),
@@ -92,48 +118,182 @@ class VroomOrchestrationEngine implements OrchestrationEngineInterface
             ],
         ];
 
-        // Map job IDs to integer IDs for VROOM, keeping a reverse lookup
-        $jobIdMap     = [];
-        $jobIdReverse = [];
-        foreach ($vroomPayload['jobs'] as &$job) {
-            $intId                = crc32($job['id']);
-            $jobIdReverse[$intId] = $job['id'];
-            $job['id']            = $intId;
-            $jobIdMap[$job['id']] = true;
+        foreach ($routeTasks as $task) {
+            if (count($task['stops']) > 1) {
+                $shipment = $this->mapTaskToShipment($task, $jobIdReverse);
+                if ($shipment) {
+                    $vroomPayload['shipments'][] = $shipment;
+                }
+
+                continue;
+            }
+
+            $job = $this->mapTaskToVroomJob($task, $jobIdReverse);
+            if ($job) {
+                $vroomPayload['jobs'][] = $job;
+            }
         }
-        unset($job);
 
-        // ── Resolve connection config ─────────────────────────────────────────
-        $baseUri = $this->resolveVroomBaseUri();
-        $endpointMode = $this->resolveVroomEndpointMode();
-        $timeout = (int) env('VROOM_TIMEOUT', 30);
+        if (empty($vroomPayload['jobs'])) {
+            unset($vroomPayload['jobs']);
+        }
+        if (empty($vroomPayload['shipments'])) {
+            unset($vroomPayload['shipments']);
+        }
 
-        $apiKey = $this->resolveVroomApiKey();
+        $result = $this->callVroom($vroomPayload);
 
-        // Build the solve URL — append api_key as query param when present.
-        $solveUrl = rtrim($baseUri, '/');
-        if ($endpointMode !== 'binary') {
-            $solveUrl .= '/solve';
+        return $this->mergeInvalidTasks(
+            $this->mapVroomResponse($result, $jobIdReverse),
+            $invalidTasks
+        );
+    }
+
+    protected function allocateCapacityOnly(Collection $orders, Collection $vehicles, array $options = []): array
+    {
+        $tasks         = OrchestrationPayloadBuilder::buildCapacityTasks($orders);
+        $vroomVehicles = OrchestrationPayloadBuilder::buildCapacityVehicles($vehicles);
+
+        [$capacityTasks, $invalidTasks] = $this->partitionRouteTasks($tasks);
+
+        if (empty($capacityTasks)) {
+            return $this->mergeInvalidTasks([
+                'assignments' => [],
+                'unassigned'  => [],
+                'summary'     => [
+                    'engine'              => 'vroom',
+                    'allocation_strategy' => 'capacity_only',
+                ],
+            ], $invalidTasks);
         }
-        if ($apiKey) {
-            $solveUrl .= '?api_key=' . urlencode($apiKey);
+
+        $jobIdReverse = [];
+        $vroomPayload = $this->buildCapacityOnlyPayload($capacityTasks, $vroomVehicles, $options, $jobIdReverse);
+
+        if (empty($vroomPayload['vehicles'])) {
+            return $this->mergeInvalidTasks([
+                'assignments' => [],
+                'unassigned'  => array_column($capacityTasks, 'id'),
+                'summary'     => [
+                    'engine'              => 'vroom',
+                    'allocation_strategy' => 'capacity_only',
+                    'assigned'            => 0,
+                    'unassigned'          => count($capacityTasks),
+                    'unassigned_reasons'  => array_map(fn (array $task) => [
+                        'order_id' => $task['id'],
+                        'reason'   => 'no_available_vehicle',
+                    ], $capacityTasks),
+                ],
+            ], $invalidTasks);
         }
 
-        // ── Call VROOM ────────────────────────────────────────────────────────
-        try {
-            $response = Http::timeout($timeout)->post($solveUrl, $vroomPayload);
-        } catch (\Exception $e) {
-            Log::error('[VroomOrchestrationEngine] HTTP request failed: ' . $e->getMessage());
-            throw new \RuntimeException('VROOM allocation engine is unavailable: ' . $e->getMessage() . ' — ensure VROOM_HOST is reachable or switch to the built-in greedy engine.', 0, $e);
+        $result = $this->mapVroomResponse($this->callVroom($vroomPayload), $jobIdReverse);
+
+        $result['summary'] = array_merge($result['summary'] ?? [], [
+            'engine'              => 'vroom',
+            'allocation_strategy' => 'capacity_only',
+        ]);
+
+        return $this->mergeInvalidTasks($result, $invalidTasks);
+    }
+
+    protected function buildCapacityOnlyPayload(array $capacityTasks, array $vroomVehicles, array $options, array &$jobIdReverse): array
+    {
+        $matrixSize      = count($capacityTasks) + 1;
+        $profile         = $options['profile'] ?? 'capacity_only';
+        $respectCapacity = (bool) ($options['respect_capacity'] ?? true);
+        $respectSkills   = (bool) ($options['respect_skills'] ?? true);
+
+        $vroomPayload = [
+            'jobs'     => [],
+            'vehicles' => array_map(function (array $v) use ($profile, $respectCapacity, $respectSkills) {
+                $vehicle = [
+                    'id'          => crc32($v['id']),
+                    'description' => json_encode(['vehicle_id' => $v['id'], 'driver_id' => $v['driver_id'] ?? null]),
+                    'profile'     => $profile,
+                    'start_index' => 0,
+                ];
+
+                if ($respectCapacity) {
+                    $vehicle['capacity'] = $v['capacity'];
+                }
+                if ($respectSkills && isset($v['skills'])) {
+                    $vehicle['skills'] = $v['skills'];
+                }
+
+                foreach (['time_window', 'max_tasks', 'max_travel_time'] as $key) {
+                    if (isset($v[$key])) {
+                        $vehicle[$key] = $v[$key];
+                    }
+                }
+
+                return $vehicle;
+            }, $vroomVehicles),
+            'matrices' => [
+                $profile => [
+                    'durations' => $this->buildUniformMatrix($matrixSize),
+                    'distances' => $this->buildUniformMatrix($matrixSize),
+                ],
+            ],
+            'options' => [
+                'g' => false,
+            ],
+        ];
+
+        foreach ($capacityTasks as $index => $task) {
+            $orderId              = $task['id'];
+            $intId                = crc32($orderId);
+            $jobIdReverse[$intId] = $orderId;
+
+            $job = [
+                'id'             => $intId,
+                'location_index' => $index + 1,
+                'description'    => $task['description'] ?? $orderId,
+            ];
+
+            if ($respectCapacity) {
+                $job['delivery'] = $task['amount'] ?? [0, 0, 0, 0];
+            }
+            if ($respectSkills && isset($task['skills'])) {
+                $job['skills'] = $task['skills'];
+            }
+
+            $this->copyTaskFields($task, $job, ['priority']);
+            $vroomPayload['jobs'][] = $job;
         }
 
-        if (!$response->successful()) {
-            throw new \RuntimeException('VROOM returned an error: HTTP ' . $response->status() . ' — ' . $response->body());
+        return $vroomPayload;
+    }
+
+    protected function buildUniformMatrix(int $size): array
+    {
+        $matrix = [];
+
+        for ($row = 0; $row < $size; $row++) {
+            $matrix[$row] = [];
+            for ($column = 0; $column < $size; $column++) {
+                $matrix[$row][$column] = $row === $column ? 0 : 1;
+            }
         }
 
-        $result = $response->json();
+        return $matrix;
+    }
+
+    protected function partitionRouteTasks(array $tasks): array
+    {
+        $routeTasks   = [];
+        $invalidTasks = [];
+
+        foreach ($tasks as $task) {
+            if (!empty($task['invalid'])) {
+                $invalidTasks[] = $task;
+                continue;
+            }
+
+            $routeTasks[] = $task;
+        }
 
-        return $this->mapVroomResponse($result, $jobIdReverse);
+        return [$routeTasks, $invalidTasks];
     }
 
     /**
@@ -152,7 +312,7 @@ class VroomOrchestrationEngine implements OrchestrationEngineInterface
             $sequence    = 0;
 
             foreach ($route['steps'] ?? [] as $step) {
-                if ($step['type'] !== 'job') {
+                if (!in_array($step['type'], ['job', 'delivery'], true)) {
                     continue;
                 }
                 $orderId = $jobIdReverse[$step['id']] ?? null;
@@ -178,11 +338,143 @@ class VroomOrchestrationEngine implements OrchestrationEngineInterface
 
         return [
             'assignments' => $assignments,
-            'unassigned'  => array_values($unassigned),
+            'unassigned'  => array_values(array_unique($unassigned)),
             'summary'     => $vroomResult['summary'] ?? [],
         ];
     }
 
+    protected function mapTaskToVroomJob(array $task, array &$jobIdReverse): ?array
+    {
+        $stop = $task['stops'][0] ?? null;
+        if (!$stop || empty($stop['location'])) {
+            return null;
+        }
+
+        $orderId              = $task['id'];
+        $intId                = crc32($orderId);
+        $jobIdReverse[$intId] = $orderId;
+
+        $vroomJob = [
+            'id'          => $intId,
+            'location'    => $stop['location'],
+            'description' => $task['description'] ?? $orderId,
+        ];
+
+        $this->copyTaskFields($task, $vroomJob, ['service', 'amount', 'time_windows', 'skills', 'priority']);
+
+        return $vroomJob;
+    }
+
+    protected function mapTaskToShipment(array $task, array &$jobIdReverse): ?array
+    {
+        $stops = $task['stops'] ?? [];
+        $first = $stops[0] ?? null;
+        $last  = $stops[count($stops) - 1] ?? null;
+
+        if (!$first || !$last || empty($first['location']) || empty($last['location'])) {
+            return null;
+        }
+
+        $orderId    = $task['id'];
+        $pickupId   = crc32($orderId . ':pickup');
+        $deliveryId = crc32($orderId . ':delivery');
+
+        // We only create one FleetOps assignment per order, so route pickup
+        // steps are ignored while delivery and unassigned entries still map
+        // back to the order public_id.
+        $jobIdReverse[$pickupId]   = $orderId;
+        $jobIdReverse[$deliveryId] = $orderId;
+
+        $shipment = [
+            'pickup' => [
+                'id'          => $pickupId,
+                'location'    => $first['location'],
+                'description' => ($task['description'] ?? $orderId) . ' pickup',
+            ],
+            'delivery' => [
+                'id'          => $deliveryId,
+                'location'    => $last['location'],
+                'description' => ($task['description'] ?? $orderId) . ' delivery',
+            ],
+        ];
+
+        if (array_key_exists('service', $task)) {
+            $shipment['delivery']['service'] = $task['service'];
+        }
+        if (array_key_exists('time_windows', $task)) {
+            $shipment['delivery']['time_windows'] = $task['time_windows'];
+        }
+
+        $this->copyTaskFields($task, $shipment, ['amount', 'skills', 'priority']);
+
+        return $shipment;
+    }
+
+    protected function copyTaskFields(array $task, array &$target, array $keys): void
+    {
+        foreach ($keys as $key) {
+            if (array_key_exists($key, $task)) {
+                $target[$key] = $task[$key];
+            }
+        }
+    }
+
+    protected function mergeInvalidTasks(array $result, array $invalidTasks): array
+    {
+        if (empty($invalidTasks)) {
+            return $result;
+        }
+
+        $invalid = array_map(fn (array $task) => [
+            'order_id' => $task['id'],
+            'reason'   => $task['reason'] ?? 'Order has invalid route coordinates.',
+        ], $invalidTasks);
+
+        $result['unassigned'] = array_values(array_unique(array_merge(
+            $result['unassigned'] ?? [],
+            array_column($invalid, 'order_id')
+        )));
+
+        $summary             = $result['summary'] ?? [];
+        $summary['invalid']  = array_values(array_merge($summary['invalid'] ?? [], $invalid));
+        $result['summary']   = $summary;
+
+        return $result;
+    }
+
+    protected function callVroom(array $vroomPayload): array
+    {
+        // ── Resolve connection config ─────────────────────────────────────────
+        $baseUri      = $this->resolveVroomBaseUri();
+        $endpointMode = $this->resolveVroomEndpointMode();
+        $timeout      = (int) env('VROOM_TIMEOUT', 30);
+
+        $apiKey = $this->resolveVroomApiKey();
+
+        // Build the solve URL — append api_key as query param when present.
+        $solveUrl = rtrim($baseUri, '/');
+        if ($endpointMode !== 'binary') {
+            $solveUrl .= '/solve';
+        }
+        if ($apiKey) {
+            $solveUrl .= '?api_key=' . urlencode($apiKey);
+        }
+
+        // ── Call VROOM ────────────────────────────────────────────────────────
+        try {
+            $response = Http::timeout($timeout)->post($solveUrl, $vroomPayload);
+        } catch (\Exception $e) {
+            Log::error('[VroomOrchestrationEngine] HTTP request failed: ' . $e->getMessage());
+            throw new \RuntimeException('VROOM allocation engine is unavailable: ' . $e->getMessage() . ' — ensure VROOM_HOST is reachable or switch to the built-in greedy engine.', 0, $e);
+        }
+
+        if (!$response->successful()) {
+            throw new \RuntimeException('VROOM returned an error: HTTP ' . $response->status() . ' — ' . $response->body());
+        }
+
+        return $response->json();
+    }
+
     protected function resolveVroomBaseUri(): string
     {
         return $this->resolveVroomSetting('api_host', config('vroom.base_uri', env('VROOM_HOST', 'https://api.verso-optim.com/vrp/v1')));