@fleetbase/fleetops-engine 0.6.38 → 0.6.40

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

@@ -0,0 +1,192 @@
+<?php
+
+namespace Fleetbase\FleetOps\Orchestration\Engines;
+
+use Fleetbase\FleetOps\Orchestration\Contracts\OrchestrationEngineInterface;
+use Fleetbase\FleetOps\Orchestration\Support\OrchestrationPayloadBuilder;
+use Fleetbase\Models\Setting;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * VroomOrchestrationEngine.
+ *
+ * Self-contained VROOM integration for the FleetOps Orchestrator Workbench.
+ * This engine does NOT depend on the optional `fleetbase/vroom` extension —
+ * it communicates directly with the VROOM HTTP API using the same base URI
+ * and API-key convention that the extension uses, so the two are compatible
+ * when both are installed.
+ *
+ * Resolution order for configuration:
+ *
+ *   1. Company-level setting  — `Setting::lookupCompany('vroom', 'api_key')`
+ *      (written by the fleetbase/vroom extension settings page, if installed)
+ *   2. Environment variable   — `VROOM_API_KEY`
+ *   3. No key                 — requests are sent without an api_key parameter
+ *      (works for self-hosted VROOM instances that do not require auth)
+ *
+ *   Base URI: `config('vroom.base_uri')` → `VROOM_HOST` env → default production URL
+ *   Timeout:  `VROOM_TIMEOUT` env (default 30 s)
+ *
+ * The VROOM HTTP API endpoint used is `POST {base_uri}/solve`, matching the
+ * verso-optim.com hosted service and the fleetbase/vroom extension.
+ */
+class VroomOrchestrationEngine implements OrchestrationEngineInterface
+{
+    public function getName(): string
+    {
+        return 'VROOM';
+    }
+
+    public function getIdentifier(): string
+    {
+        return 'vroom';
+    }
+
+    /**
+     * Run the VROOM VRP solver.
+     *
+     * Constructs a VROOM-format payload from the normalized jobs/vehicles
+     * produced by OrchestrationPayloadBuilder, calls the VROOM HTTP API, and
+     * maps the response back to the standard OrchestrationEngineInterface result
+     * shape.
+     *
+     * @throws \RuntimeException if the VROOM API is unreachable or returns an error
+     */
+    public function allocate(Collection $orders, Collection $vehicles, array $options = []): array
+    {
+        $jobs          = OrchestrationPayloadBuilder::buildJobs($orders);
+        $vroomVehicles = OrchestrationPayloadBuilder::buildVehicles($vehicles);
+
+        if (empty($jobs)) {
+            return ['assignments' => [], 'unassigned' => [], 'summary' => []];
+        }
+
+        // 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) {
+                $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 (isset($v['time_window'])) {
+                    $vehicle['time_window'] = $v['time_window'];
+                }
+                if (isset($v['skills'])) {
+                    $vehicle['skills'] = $v['skills'];
+                }
+
+                return $vehicle;
+            }, $vroomVehicles),
+            'options' => [
+                'g' => $options['geometry'] ?? false,
+            ],
+        ];
+
+        // 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;
+        }
+        unset($job);
+
+        // ── Resolve connection config ─────────────────────────────────────────
+        // Base URI: prefer the vroom extension config, then VROOM_HOST env, then
+        // the production verso-optim.com hosted service.
+        $baseUri = config('vroom.base_uri', env('VROOM_HOST', 'https://api.verso-optim.com/vrp/v1'));
+        $timeout = (int) env('VROOM_TIMEOUT', 30);
+
+        // ── Resolve API key ───────────────────────────────────────────────────
+        // 1. Company-level setting (written by fleetbase/vroom extension UI)
+        // 2. VROOM_API_KEY env var
+        // 3. null — no key appended (for self-hosted instances)
+        $apiKey = null;
+        try {
+            $apiKey = Setting::lookupCompany('vroom', ['api_key' => null])['api_key'] ?? null;
+        } catch (\Throwable) {
+            // Setting table may not exist in minimal installs — ignore
+        }
+        if (!$apiKey) {
+            $apiKey = env('VROOM_API_KEY');
+        }
+
+        // Build the solve URL — append api_key as query param when present
+        $solveUrl = rtrim($baseUri, '/') . '/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());
+        }
+
+        $result = $response->json();
+
+        return $this->mapVroomResponse($result, $jobIdReverse);
+    }
+
+    /**
+     * Map a VROOM API response to the standard OrchestrationEngineInterface shape.
+     *
+     * @param array $jobIdReverse Map of VROOM integer job ID → order public_id
+     */
+    protected function mapVroomResponse(array $vroomResult, array $jobIdReverse): array
+    {
+        $assignments = [];
+
+        foreach ($vroomResult['routes'] ?? [] as $route) {
+            $vehicleDesc = json_decode($route['description'] ?? '{}', true);
+            $vehicleId   = $vehicleDesc['vehicle_id'] ?? null;
+            $driverId    = $vehicleDesc['driver_id'] ?? null;
+            $sequence    = 0;
+
+            foreach ($route['steps'] ?? [] as $step) {
+                if ($step['type'] !== 'job') {
+                    continue;
+                }
+                $orderId = $jobIdReverse[$step['id']] ?? null;
+                if (!$orderId) {
+                    continue;
+                }
+                $assignments[] = [
+                    'order_id'   => $orderId,
+                    'vehicle_id' => $vehicleId,
+                    'driver_id'  => $driverId,
+                    'sequence'   => ++$sequence,
+                    'arrival'    => $step['arrival'] ?? null,
+                    'duration'   => $step['duration'] ?? null,
+                    'distance'   => $step['distance'] ?? null,
+                ];
+            }
+        }
+
+        $unassigned = array_map(
+            fn ($u) => $jobIdReverse[$u['id']] ?? $u['id'],
+            $vroomResult['unassigned'] ?? []
+        );
+
+        return [
+            'assignments' => $assignments,
+            'unassigned'  => array_values($unassigned),
+            'summary'     => $vroomResult['summary'] ?? [],
+        ];
+    }
+}

package/server/src/Orchestration/OrchestrationEngineRegistry.php

@@ -0,0 +1,83 @@
+<?php
+
+namespace Fleetbase\FleetOps\Orchestration;
+
+use Fleetbase\FleetOps\Orchestration\Contracts\OrchestrationEngineInterface;
+
+/**
+ * OrchestrationEngineRegistry.
+ *
+ * A simple service-locator for orchestration engines. Engines register
+ * themselves (typically from a service provider) and the
+ * OrchestrationController resolves the active engine at runtime from the
+ * FleetOps setting key 'fleetops.orchestrator_engine'.
+ *
+ * Third-party extensions can register their own engines by resolving this
+ * registry in their service provider:
+ *
+ *   $this->app->resolving(OrchestrationEngineRegistry::class, function ($registry) {
+ *       $registry->register(new MyCustomEngine());
+ *   });
+ */
+class OrchestrationEngineRegistry
+{
+    /**
+     * Registered engines keyed by their identifier.
+     *
+     * @var array<string, OrchestrationEngineInterface>
+     */
+    protected array $engines = [];
+
+    /**
+     * Register an orchestration engine.
+     *
+     * @throws \InvalidArgumentException if an engine with the same identifier is already registered
+     */
+    public function register(OrchestrationEngineInterface $engine): void
+    {
+        $id = $engine->getIdentifier();
+        if (isset($this->engines[$id])) {
+            throw new \InvalidArgumentException("An orchestration engine with identifier '{$id}' is already registered.");
+        }
+        $this->engines[$id] = $engine;
+    }
+
+    /**
+     * Resolve an engine by identifier.
+     *
+     * @throws \RuntimeException if no engine with the given identifier is registered
+     */
+    public function resolve(string $identifier): OrchestrationEngineInterface
+    {
+        if (!isset($this->engines[$identifier])) {
+            throw new \RuntimeException("No orchestration engine registered with identifier '{$identifier}'. " . 'Available engines: ' . implode(', ', array_keys($this->engines)));
+        }
+
+        return $this->engines[$identifier];
+    }
+
+    /**
+     * Return all registered engines as an array of {id, name} pairs.
+     * Used by the settings API to populate the engine selector dropdown.
+     *
+     * @return array<array{id: string, name: string}>
+     */
+    public function available(): array
+    {
+        return array_values(array_map(
+            fn (OrchestrationEngineInterface $engine) => [
+                'id'   => $engine->getIdentifier(),
+                'name' => $engine->getName(),
+            ],
+            $this->engines
+        ));
+    }
+
+    /**
+     * Check whether an engine with the given identifier is registered.
+     */
+    public function has(string $identifier): bool
+    {
+        return isset($this->engines[$identifier]);
+    }
+}

package/server/src/Orchestration/Support/OrchestrationPayloadBuilder.php

@@ -0,0 +1,380 @@
+<?php
+
+namespace Fleetbase\FleetOps\Orchestration\Support;
+
+use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Vehicle;
+use Illuminate\Support\Collection;
+
+/**
+ * OrchestrationPayloadBuilder.
+ *
+ * Transforms FleetOps Order and Vehicle/Driver records into a normalized
+ * intermediate representation that engine adapters can consume. This class
+ * is engine-agnostic — it does not produce VROOM JSON directly. Each engine
+ * adapter (e.g. VroomOrchestrationEngine) calls the builder and then maps the
+ * normalized output to its own wire format.
+ *
+ * Vehicle capacity is read from the existing first-class columns on the
+ * vehicles table (payload_capacity, payload_capacity_volume, etc.).
+ *
+ * Order/payload capacity demand is computed dynamically by aggregating the
+ * weight and dimensions of the payload's entities — no denormalised cache
+ * columns are needed or used on the payloads table.
+ */
+class OrchestrationPayloadBuilder
+{
+    /**
+     * Safely read a meta key from a model, returning $default on any error.
+     *
+     * Vehicle::getAllMeta() has a strict array return type but some rows store
+     * the meta column as a raw JSON string rather than a decoded array, causing
+     * a TypeError at runtime. This wrapper catches that and any other meta
+     * read failure so a single bad vehicle row does not abort the whole run.
+     *
+     * @param \Illuminate\Database\Eloquent\Model $model
+     */
+    protected static function safeMeta($model, string $key, $default = null)
+    {
+        try {
+            return $model->getMeta($key) ?? $default;
+        } catch (\Throwable $e) {
+            return $default;
+        }
+    }
+
+    /**
+     * Compute the multi-dimensional capacity demand for a payload by aggregating
+     * its entities' weight and volume values.
+     *
+     * Returns a 4-element integer array matching the vehicle capacity array:
+     *   [weight_kg, volume_litres, pallets, parcels]
+     *
+     * Weight is normalised to kg from entity.weight_unit.
+     * Volume is derived from entity length × width × height (dimensions_unit normalised to metres)
+     * and expressed in litres (×1000) so it can be stored as an integer for VROOM.
+     *
+     * Falls back to order meta keys (weight_kg, volume_m3, pallets, parcels) for
+     * backwards compatibility with orders that were created before entity-level
+     * dimension data was captured.
+     */
+    protected static function computePayloadDemand(Order $order): array
+    {
+        $payload = $order->payload;
+
+        if ($payload && $payload->entities && $payload->entities->isNotEmpty()) {
+            $totalWeightKg  = 0.0;
+            $totalVolumeLit = 0.0;
+            $totalParcels   = 0;
+
+            foreach ($payload->entities as $entity) {
+                // --- Weight ---
+                $rawWeight = (float) ($entity->weight ?? 0);
+                $weightUnit = strtolower($entity->weight_unit ?? 'kg');
+                $weightKg = match ($weightUnit) {
+                    'g', 'gram', 'grams'              => $rawWeight / 1000,
+                    'lb', 'lbs', 'pound', 'pounds'    => $rawWeight * 0.453592,
+                    'oz', 'ounce', 'ounces'            => $rawWeight * 0.0283495,
+                    't', 'ton', 'tonne', 'tonnes'      => $rawWeight * 1000,
+                    default                            => $rawWeight, // kg assumed
+                };
+                $totalWeightKg += $weightKg;
+
+                // --- Volume (L × W × H → m³ → litres) ---
+                $l    = (float) ($entity->length ?? 0);
+                $w    = (float) ($entity->width ?? 0);
+                $h    = (float) ($entity->height ?? 0);
+                $unit = strtolower($entity->dimensions_unit ?? 'm');
+
+                if ($l > 0 && $w > 0 && $h > 0) {
+                    // Normalise to metres
+                    $factor = match ($unit) {
+                        'cm', 'centimeter', 'centimetre'   => 0.01,
+                        'mm', 'millimeter', 'millimetre'   => 0.001,
+                        'in', 'inch', 'inches'             => 0.0254,
+                        'ft', 'foot', 'feet'               => 0.3048,
+                        default                            => 1.0, // metres assumed
+                    };
+                    $volumeM3    = ($l * $factor) * ($w * $factor) * ($h * $factor);
+                    $totalVolumeLit += $volumeM3 * 1000; // m³ → litres
+                }
+
+                $totalParcels++;
+            }
+
+            return [
+                (int) round($totalWeightKg),
+                (int) round($totalVolumeLit),
+                0, // pallet count not tracked at entity level
+                $totalParcels,
+            ];
+        }
+
+        // Fallback: order meta keys for backwards compatibility
+        return [
+            (int) round((float) ($order->getMeta('weight_kg') ?? 0)),
+            (int) round((float) ($order->getMeta('volume_m3') ?? 0) * 1000),
+            (int) ($order->getMeta('pallets') ?? 0),
+            (int) ($order->getMeta('parcels') ?? 1),
+        ];
+    }
+
+    /**
+     * Build the vehicle capacity array from the vehicle's first-class columns.
+     *
+     * Returns a 4-element integer array:
+     *   [weight_kg, volume_litres, pallets, parcels]
+     *
+     * payload_capacity        — existing column, weight in kg
+     * payload_capacity_volume — new column, volume in m³ (stored as litres for VROOM)
+     * payload_capacity_pallets / payload_capacity_parcels — new columns
+     */
+    protected static function buildVehicleCapacity(Vehicle $vehicle): array
+    {
+        return [
+            (int) round((float) ($vehicle->payload_capacity ?? static::safeMeta($vehicle, 'max_weight_kg', 0))),
+            (int) round((float) ($vehicle->payload_capacity_volume ?? static::safeMeta($vehicle, 'max_volume_m3', 0)) * 1000),
+            (int) ($vehicle->payload_capacity_pallets ?? static::safeMeta($vehicle, 'max_pallets', 0)),
+            (int) ($vehicle->payload_capacity_parcels ?? static::safeMeta($vehicle, 'max_parcels', 100)),
+        ];
+    }
+
+    /**
+     * Build the normalized job list from a collection of Orders.
+     *
+     * Each job contains:
+     *   - id:            order public_id
+     *   - location:      [longitude, latitude] of the delivery destination
+     *   - pickup:        [longitude, latitude] of the pickup (for PDPTW shipments)
+     *   - service:       service time in seconds (waypoint.service_time → order meta → default 300)
+     *   - time_windows:  [[earliest_unix, latest_unix]] from order.time_window_start/end or scheduled_at
+     *   - skills:        integer skill codes from order.required_skills or custom fields
+     *   - amount:        multi-dimensional capacity demand [weight_kg, volume_litres, pallets, parcels]
+     *   - priority:      orchestrator_priority (0–100, higher = more important)
+     *   - description:   human-readable label for debugging
+     */
+    public static function buildJobs(Collection $orders): array
+    {
+        return $orders->map(function (Order $order) {
+            $payload     = $order->payload;
+            $destination = $payload?->dropoff ?? $payload?->waypoints?->last();
+
+            if (!$destination || !$destination->location) {
+                return null;
+            }
+
+            // --- Location ---
+            $job = [
+                'id'          => $order->public_id,
+                'location'    => [$destination->location->getLng(), $destination->location->getLat()],
+                'description' => $order->public_id,
+            ];
+
+            // Pickup location (for pickup-and-delivery problems)
+            $pickup = $payload?->pickup;
+            if ($pickup && $pickup->location) {
+                $job['pickup'] = [$pickup->location->getLng(), $pickup->location->getLat()];
+            }
+
+            // --- Service time ---
+            // Prefer waypoint-level service_time, then order meta, then default 300s
+            $waypointMarker = $payload?->waypointMarkers?->last();
+            $job['service'] = (int) (
+                $waypointMarker?->service_time
+                ?? $order->getMeta('service_time_seconds')
+                ?? 300
+            );
+
+            // --- Capacity demand ---
+            // Aggregated dynamically from payload entities; falls back to order meta.
+            $job['amount'] = static::computePayloadDemand($order);
+
+            // --- Time windows ---
+            // Prefer explicit orchestrator time_window columns, fall back to scheduled_at
+            if ($order->time_window_start && $order->time_window_end) {
+                $job['time_windows'] = [[
+                    $order->time_window_start->timestamp,
+                    $order->time_window_end->timestamp,
+                ]];
+            } elseif ($order->scheduled_at) {
+                $start               = $order->scheduled_at->timestamp;
+                $end                 = $order->scheduled_at->copy()->addHours(4)->timestamp;
+                $job['time_windows'] = [[$start, $end]];
+            }
+
+            // --- Skills ---
+            // Prefer first-class required_skills JSON column, fall back to custom fields
+            $skills = static::resolveSkills(
+                $order->required_skills ?? [],
+                $order->custom_fields ?? []
+            );
+            if (!empty($skills)) {
+                $job['skills'] = $skills;
+            }
+
+            // --- Priority ---
+            if ($order->orchestrator_priority !== null && $order->orchestrator_priority > 0) {
+                $job['priority'] = (int) $order->orchestrator_priority;
+            }
+
+            return $job;
+        })->filter()->values()->toArray();
+    }
+
+    /**
+     * Build vehicles for vehicle-only allocation mode — no driver required.
+     *
+     * Uses vehicle.location as the start position. Skills and capacity are
+     * read from the vehicle only. Used by the 'assign_vehicles' mode.
+     */
+    public static function buildVehiclesOnly(Collection $vehicles): array
+    {
+        return $vehicles->map(function (Vehicle $vehicle) {
+            if (!$vehicle->location) {
+                return null;
+            }
+            $entry = [
+                'id'        => $vehicle->public_id,
+                'driver_id' => null,
+                'start'     => [$vehicle->location->getLng(), $vehicle->location->getLat()],
+            ];
+            if ($vehicle->return_to_depot && $vehicle->location) {
+                $entry['end'] = [$vehicle->location->getLng(), $vehicle->location->getLat()];
+            }
+            $entry['capacity'] = static::buildVehicleCapacity($vehicle);
+            if ($vehicle->max_tasks !== null && $vehicle->max_tasks > 0) {
+                $entry['max_tasks'] = (int) $vehicle->max_tasks;
+            }
+            if ($vehicle->time_window_start && $vehicle->time_window_end) {
+                $entry['time_window'] = [
+                    $vehicle->time_window_start->timestamp,
+                    $vehicle->time_window_end->timestamp,
+                ];
+            }
+            $skills = static::resolveSkills($vehicle->skills ?? [], $vehicle->custom_fields ?? []);
+            if (!empty($skills)) {
+                $entry['skills'] = $skills;
+            }
+
+            return $entry;
+        })->filter()->values()->toArray();
+    }
+
+    /**
+     * Build vehicles for driver+vehicle allocation mode.
+     *
+     * Uses driver.location as the start position, falling back to vehicle.location.
+     * Capacity is read from the vehicle. Time windows prefer the driver's explicit
+     * window, then the driver's active shift, then the vehicle's window.
+     */
+    public static function buildVehicles(Collection $vehicles): array
+    {
+        return $vehicles->map(function (Vehicle $vehicle) {
+            $driver = $vehicle->driver;
+            // For vehicle-only mode, fall back to vehicle.location when no driver
+            $startLocation = $driver?->location ?? $vehicle->location;
+            if (!$startLocation) {
+                return null;
+            }
+            // --- Start position ---
+            $entry = [
+                'id'        => $vehicle->public_id,
+                'driver_id' => $driver?->public_id,
+                'start'     => [$startLocation->getLng(), $startLocation->getLat()],
+            ];
+            // --- Return to depot ---
+            if ($vehicle->return_to_depot && $startLocation) {
+                $entry['end'] = [$startLocation->getLng(), $startLocation->getLat()];
+            }
+
+            // --- Multi-dimensional capacity ---
+            $entry['capacity'] = static::buildVehicleCapacity($vehicle);
+
+            // --- Max tasks ---
+            if ($vehicle->max_tasks !== null && $vehicle->max_tasks > 0) {
+                $entry['max_tasks'] = (int) $vehicle->max_tasks;
+            }
+
+            // --- Max travel time (seconds) ---
+            $maxTravel = $driver?->max_travel_time ?? static::safeMeta($vehicle, 'max_travel_time_seconds');
+            if ($maxTravel) {
+                $entry['max_travel_time'] = (int) $maxTravel;
+            }
+
+            // --- Time window ---
+            // Priority: driver.time_window_start/end columns → active shift → vehicle.time_window columns
+            if ($driver?->time_window_start && $driver?->time_window_end) {
+                $entry['time_window'] = [
+                    $driver->time_window_start->timestamp,
+                    $driver->time_window_end->timestamp,
+                ];
+            } else {
+                $activeShift = $driver?->activeShiftFor(now());
+                if ($activeShift) {
+                    $entry['time_window'] = [
+                        $activeShift->start_at->timestamp,
+                        $activeShift->end_at->timestamp,
+                    ];
+                } elseif ($vehicle->time_window_start && $vehicle->time_window_end) {
+                    $entry['time_window'] = [
+                        $vehicle->time_window_start->timestamp,
+                        $vehicle->time_window_end->timestamp,
+                    ];
+                }
+            }
+
+            // --- Skills ---
+            $skills = array_values(array_unique(array_merge(
+                static::resolveSkills($vehicle->skills ?? [], $vehicle->custom_fields ?? []),
+                static::resolveSkills($driver?->skills ?? [], $driver?->custom_fields ?? [])
+            )));
+            if (!empty($skills)) {
+                $entry['skills'] = $skills;
+            }
+
+            return $entry;
+        })->filter()->values()->toArray();
+    }
+
+    /**
+     * Resolve integer skill codes from a first-class skills array and/or custom fields.
+     *
+     * The skills array (from the new JSON column) contains string identifiers like
+     * "cold_chain", "hazmat", "fragile". These are hashed to stable positive integers.
+     * Custom fields that are boolean-true are also included for backwards compatibility.
+     *
+     * @param array $skills       String skill identifiers from the skills JSON column
+     * @param array $customFields Custom fields array from HasCustomFields trait
+     *
+     * @return array<int>
+     */
+    public static function resolveSkills(array $skills, array $customFields = []): array
+    {
+        $codes = [];
+
+        // First-class skills column: hash each string identifier to a stable integer
+        foreach ($skills as $skill) {
+            if (is_string($skill) && !empty($skill)) {
+                $codes[] = abs(crc32($skill)) % 2147483647 + 1;
+            }
+        }
+
+        // Backwards-compatible custom fields: boolean-true fields treated as skills
+        foreach ($customFields as $key => $value) {
+            if ($value === true || $value === 'true' || $value === '1' || $value === 1) {
+                $codes[] = abs(crc32($key)) % 2147483647 + 1;
+            }
+        }
+
+        return array_values(array_unique($codes));
+    }
+
+    /**
+     * @deprecated use resolveSkills() instead
+     */
+    protected static function extractSkillsFromCustomFields(array $customFields): array
+    {
+        return static::resolveSkills([], $customFields);
+    }
+}

package/server/src/Providers/EventServiceProvider.php

@@ -19,7 +19,7 @@ class EventServiceProvider extends ServiceProvider
         \Fleetbase\FleetOps\Events\OrderDispatched::class     => [\Fleetbase\FleetOps\Listeners\HandleOrderDispatched::class, \Fleetbase\Listeners\SendResourceLifecycleWebhook::class, \Fleetbase\FleetOps\Listeners\NotifyOrderEvent::class],
         \Fleetbase\FleetOps\Events\OrderDispatchFailed::class => [\Fleetbase\FleetOps\Listeners\HandleOrderDispatchFailed::class, \Fleetbase\Listeners\SendResourceLifecycleWebhook::class, \Fleetbase\FleetOps\Listeners\NotifyOrderEvent::class],
         \Fleetbase\FleetOps\Events\OrderDriverAssigned::class => [\Fleetbase\FleetOps\Listeners\HandleOrderDriverAssigned::class, \Fleetbase\Listeners\SendResourceLifecycleWebhook::class, \Fleetbase\FleetOps\Listeners\NotifyOrderEvent::class],
-        \Fleetbase\FleetOps\Events\OrderCompleted::class      => [\Fleetbase\Listeners\SendResourceLifecycleWebhook::class, \Fleetbase\FleetOps\Listeners\NotifyOrderEvent::class],
+        \Fleetbase\FleetOps\Events\OrderCompleted::class      => [\Fleetbase\Listeners\SendResourceLifecycleWebhook::class, \Fleetbase\FleetOps\Listeners\NotifyOrderEvent::class, \Fleetbase\FleetOps\Listeners\HandleDeliveryCompletion::class],
         \Fleetbase\FleetOps\Events\OrderFailed::class         => [\Fleetbase\Listeners\SendResourceLifecycleWebhook::class, \Fleetbase\FleetOps\Listeners\NotifyOrderEvent::class],
         \Fleetbase\FleetOps\Events\OrderReady::class          => [\Fleetbase\FleetOps\Listeners\HandleOrderReady::class],
 
@@ -27,5 +27,11 @@ class EventServiceProvider extends ServiceProvider
          * Core Events
          */
         \Fleetbase\Events\UserRemovedFromCompany::class => [\Fleetbase\FleetOps\Listeners\HandleUserRemovedFromCompany::class],
+
+        /*
+         * Scheduling Events
+         */
+        \Fleetbase\Events\ScheduleItemCreated::class => [\Fleetbase\FleetOps\Listeners\NotifyDriverOnShiftChange::class],
+        \Fleetbase\Events\ScheduleItemUpdated::class => [\Fleetbase\FleetOps\Listeners\NotifyDriverOnShiftChange::class],
     ];
 }