@fleetbase/fleetops-engine 0.6.71 → 0.6.72

package/server/src/Observers/TrackingNumberObserver.php

@@ -6,7 +6,6 @@ use Fleetbase\FleetOps\Models\TrackingNumber;
 use Fleetbase\FleetOps\Models\TrackingStatus;
 use Fleetbase\LaravelMysqlSpatial\Types\Point;
 use Illuminate\Support\Str;
-use Milon\Barcode\Facades\DNS2DFacade as DNS2D;
 
 class TrackingNumberObserver
 {
@@ -17,10 +16,9 @@ class TrackingNumberObserver
      */
     public function creating(TrackingNumber $trackingNumber)
     {
-        // generate a barcode annd qr code
+        // generate the tracking number, then the qr code and barcode printed from it
         $trackingNumber->tracking_number = $this->generateTrackingNumber($trackingNumber);
-        $trackingNumber->qr_code         = $this->generateBarcode($trackingNumber->owner_uuid, 'QRCODE');
-        $trackingNumber->barcode         = $this->generateBarcode($trackingNumber->owner_uuid, 'PDF417');
+        $trackingNumber->fill($this->generateCodeImages($trackingNumber->tracking_number, $this->ownerPublicId($trackingNumber)));
     }
 
     /**
@@ -47,9 +45,23 @@ class TrackingNumberObserver
         return TrackingNumber::generateNumber($trackingNumber->region);
     }
 
-    protected function generateBarcode(string $ownerUuid, string $type): string
+    /**
+     * @return array{qr_code: string, barcode: string}
+     */
+    protected function generateCodeImages(string $trackingNumber, ?string $ownerPublicId): array
     {
-        return DNS2D::getBarcodePNG($ownerUuid, $type);
+        return TrackingNumber::codeImages($trackingNumber, $ownerPublicId);
+    }
+
+    protected function ownerPublicId(TrackingNumber $trackingNumber): ?string
+    {
+        if (empty($trackingNumber->owner_uuid)) {
+            return null;
+        }
+
+        $publicId = data_get($trackingNumber, 'owner.public_id');
+
+        return is_string($publicId) && $publicId !== '' ? $publicId : null;
     }
 
     protected function createTrackingStatus(array $attributes): TrackingStatus

package/server/src/Observers/UserObserver.php

@@ -20,6 +20,7 @@ class UserObserver
 
     protected function deleteDrivers(string $userUuid): void
     {
-        Driver::where('user_uuid', $userUuid)->delete();
+        // Delete each driver through the model so DriverObserver cleans up after it
+        Driver::where('user_uuid', $userUuid)->get()->each->delete();
     }
 }

package/server/src/Observers/VehicleObserver.php

@@ -66,7 +66,7 @@ class VehicleObserver
     public function deleted(Vehicle $vehicle)
     {
         // Unassign the deleted vehicle from matching driver/(s)
-        $this->deleteDriversAssignedTo($vehicle);
+        $this->unassignDriversFrom($vehicle);
 
         $this->invalidateLiveCache();
     }
@@ -81,9 +81,14 @@ class VehicleObserver
         return Driver::where('uuid', $identifier)->whereNull('deleted_at')->withoutGlobalScopes()->first();
     }
 
-    protected function deleteDriversAssignedTo(Vehicle $vehicle): mixed
+    protected function unassignDriversFrom(Vehicle $vehicle): int
     {
-        return Driver::where(['vehicle_uuid' => $vehicle->uuid])->delete();
+        $unassigned = Driver::where(['vehicle_uuid' => $vehicle->uuid])->update(['vehicle_uuid' => null]);
+        if ($unassigned) {
+            Driver::invalidateApiCacheManually($vehicle->company_uuid);
+        }
+
+        return $unassigned;
     }
 
     protected function invalidateLiveCache(): void

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

@@ -2,6 +2,7 @@
 
 namespace Fleetbase\FleetOps\Orchestration\Engines;
 
+use Fleetbase\FleetOps\Orchestration\Support\RouteMetrics;
 use Illuminate\Support\Collection;
 
 /**
@@ -18,6 +19,8 @@ use Illuminate\Support\Collection;
  *      using a nearest-neighbour TSP heuristic.
  *   3. Returns one assignment entry per order, preserving the existing
  *      vehicle_id / driver_id and updating only the sequence number.
+ *   4. Estimates arrival times and route distance/duration along the
+ *      sequenced stops (see RouteMetrics).
  *
  * This ensures that running "Assign Vehicles" followed by "Optimize Routes"
  * produces one properly-sequenced route per vehicle rather than re-running
@@ -37,6 +40,9 @@ class RouteSequencingEngine
     {
         $assignments = [];
         $unassigned  = [];
+        $startTime   = now()->timestamp;
+        $distance    = 0;
+        $duration    = 0;
 
         // Group orders by their currently assigned vehicle UUID
         $byVehicle = [];
@@ -73,6 +79,13 @@ class RouteSequencingEngine
             // (or waypoints for multi-drop orders). We keep pickup before its own
             // dropoff as a hard constraint.
             $sequenced = $this->_sequenceOrdersForVehicle($vehicleOrders, $startLat, $startLng);
+            $metrics   = RouteMetrics::measure(
+                $startLat !== null && $startLng !== null ? [$startLat, $startLng] : null,
+                array_map(fn ($stop) => ['order_id' => $stop['order_public_id'], 'lat' => $stop['lat'], 'lng' => $stop['lng']], $sequenced),
+                $startTime
+            );
+            $distance += $metrics['distance'];
+            $duration += $metrics['duration'];
 
             // Build assignment entries — one per order, with the sequence number
             // being the position of the order's FIRST stop in the sequenced list.
@@ -92,9 +105,11 @@ class RouteSequencingEngine
                     'driver_id'         => $driverPublicId,
                     'sequence'          => $orderSequences[$order->public_id] ?? 1,
                     'waypoint_sequence' => null,
-                    'arrival'           => null,
-                    'duration'          => null,
-                    'distance'          => null,
+                    'arrival'           => $metrics['orders'][$order->public_id]['arrival'] ?? null,
+                    'duration'          => $metrics['orders'][$order->public_id]['duration'] ?? null,
+                    'distance'          => $metrics['orders'][$order->public_id]['distance'] ?? null,
+                    'route_distance'    => $metrics['distance'],
+                    'route_duration'    => $metrics['duration'],
                 ];
             }
         }
@@ -106,6 +121,9 @@ class RouteSequencingEngine
                 'engine'     => 'route_sequencing',
                 'assigned'   => count($assignments),
                 'unassigned' => count($unassigned),
+                'distance'   => $distance,
+                'duration'   => $duration,
+                'metrics'    => 'estimated',
             ],
         ];
     }

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

@@ -37,6 +37,11 @@ use Illuminate\Support\Facades\Log;
  */
 class VroomOrchestrationEngine implements OrchestrationEngineInterface
 {
+    /**
+     * Arrivals below this (2001-09-09) are offsets from the route start, not unix timestamps.
+     */
+    protected const ABSOLUTE_TIMESTAMP_THRESHOLD = 1000000000;
+
     /**
      * The company whose VROOM settings apply to the current allocation run.
      * Resolved from the orders so queued runs work without a company session.
@@ -202,6 +207,14 @@ class VroomOrchestrationEngine implements OrchestrationEngineInterface
 
         $result = $this->mapVroomResponse($this->callVroom($vroomPayload), $jobIdReverse);
 
+        // Capacity-only solves run on a uniform placeholder matrix, so VROOM's
+        // timings are meaningless here; clear them so real estimates replace them.
+        $result['assignments'] = array_map(
+            fn (array $assignment) => array_merge($assignment, array_fill_keys(['arrival', 'duration', 'distance', 'route_distance', 'route_duration'], null)),
+            $result['assignments']
+        );
+        unset($result['summary']['distance'], $result['summary']['duration']);
+
         $result['summary'] = array_merge($result['summary'] ?? [], [
             'engine'              => 'vroom',
             'allocation_strategy' => 'capacity_only',
@@ -339,6 +352,7 @@ class VroomOrchestrationEngine implements OrchestrationEngineInterface
     protected function mapVroomResponse(array $vroomResult, array $jobIdReverse): array
     {
         $assignments = [];
+        $startTime   = now()->timestamp;
 
         foreach ($vroomResult['routes'] ?? [] as $route) {
             $vehicleDesc = json_decode($route['description'] ?? '{}', true);
@@ -355,13 +369,15 @@ class VroomOrchestrationEngine implements OrchestrationEngineInterface
                     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,
+                    'order_id'       => $orderId,
+                    'vehicle_id'     => $vehicleId,
+                    'driver_id'      => $driverId,
+                    'sequence'       => ++$sequence,
+                    'arrival'        => $this->absoluteArrival($step['arrival'] ?? null, $startTime),
+                    'duration'       => $step['duration'] ?? null,
+                    'distance'       => $step['distance'] ?? null,
+                    'route_distance' => $route['distance'] ?? null,
+                    'route_duration' => $route['duration'] ?? null,
                 ];
             }
         }
@@ -374,10 +390,24 @@ class VroomOrchestrationEngine implements OrchestrationEngineInterface
         return [
             'assignments' => $assignments,
             'unassigned'  => array_values(array_unique($unassigned)),
-            'summary'     => $vroomResult['summary'] ?? [],
+            'summary'     => array_merge(['engine' => 'vroom'], $vroomResult['summary'] ?? []),
         ];
     }
 
+    /**
+     * VROOM reports arrivals on the timeline of the time windows it was given.
+     * Without absolute windows that timeline starts at 0, so small values are
+     * offsets from the start of the run rather than unix timestamps.
+     */
+    protected function absoluteArrival($arrival, int $startTime): ?int
+    {
+        if ($arrival === null) {
+            return null;
+        }
+
+        return $arrival < self::ABSOLUTE_TIMESTAMP_THRESHOLD ? $startTime + (int) $arrival : (int) $arrival;
+    }
+
     protected function mapTaskToVroomJob(array $task, array &$jobIdReverse): ?array
     {
         $stop = $task['stops'][0] ?? null;

package/server/src/Orchestration/OrchestrationEngineRegistry.php

@@ -3,6 +3,7 @@
 namespace Fleetbase\FleetOps\Orchestration;
 
 use Fleetbase\FleetOps\Orchestration\Contracts\OrchestrationEngineInterface;
+use Illuminate\Support\Collection;
 
 /**
  * OrchestrationEngineRegistry.
@@ -10,7 +11,7 @@ use Fleetbase\FleetOps\Orchestration\Contracts\OrchestrationEngineInterface;
  * 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'.
+ * organization's Orchestrator settings (see OrchestratorSettings).
  *
  * Third-party extensions can register their own engines by resolving this
  * registry in their service provider:
@@ -21,6 +22,11 @@ use Fleetbase\FleetOps\Orchestration\Contracts\OrchestrationEngineInterface;
  */
 class OrchestrationEngineRegistry
 {
+    /**
+     * Built-in engine that runs when the selected engine is missing or unavailable.
+     */
+    public const FALLBACK_ENGINE = 'greedy';
+
     /**
      * Registered engines keyed by their identifier.
      *
@@ -80,4 +86,58 @@ class OrchestrationEngineRegistry
     {
         return isset($this->engines[$identifier]);
     }
+
+    /**
+     * Run the selected engine, falling back to the built-in greedy engine when
+     * the selected engine is not registered or reports itself unavailable
+     * (a RuntimeException, e.g. VROOM unreachable or misconfigured).
+     *
+     * The result's summary always names the engine that produced it. A
+     * fallback result also carries `requested_engine` and `fallback_reason`
+     * so callers can tell the user the plan did not come from their engine.
+     *
+     * @throws \RuntimeException when the selected engine fails and there is no fallback to run
+     */
+    public function allocateWithFallback(string $identifier, Collection $orders, Collection $vehicles, array $options = []): array
+    {
+        try {
+            $engine            = $this->resolve($identifier);
+            $result            = $engine->allocate($orders, $vehicles, $options);
+            $result['summary'] = array_merge(['engine' => $engine->getIdentifier()], $result['summary'] ?? []);
+
+            return $result;
+        } catch (\RuntimeException $e) {
+            if ($identifier === static::FALLBACK_ENGINE || !$this->has(static::FALLBACK_ENGINE)) {
+                throw $e;
+            }
+
+            // The selected solvers build multi-stop routes, so the fallback
+            // must too or orders would be dropped when vehicles are scarce.
+            $result = $this->resolve(static::FALLBACK_ENGINE)->allocate($orders, $vehicles, array_merge(['allow_multi_order' => true], $options));
+
+            return static::markFallback($result, static::FALLBACK_ENGINE, $identifier, $e->getMessage());
+        }
+    }
+
+    /**
+     * Record on a result that it came from a different engine than requested, and why.
+     *
+     * @param bool $warn whether the substitution is a failure the user should be warned about,
+     *                   rather than the expected behaviour for the requested engine
+     */
+    public static function markFallback(array $result, string $engine, string $requestedEngine, string $reason, bool $warn = true): array
+    {
+        $result['summary'] = array_merge($result['summary'] ?? [], [
+            'engine'           => $engine,
+            'requested_engine' => $requestedEngine,
+            'fallback_reason'  => $reason,
+        ]);
+        if (!$warn) {
+            return $result;
+        }
+
+        $result['warning'] = sprintf('The "%s" engine was used instead of "%s": %s', $engine, $requestedEngine, $reason);
+
+        return $result;
+    }
 }

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

@@ -0,0 +1,61 @@
+<?php
+
+namespace Fleetbase\FleetOps\Orchestration\Support;
+
+use Fleetbase\Models\Setting;
+
+/**
+ * OrchestratorSettings.
+ *
+ * Single reader for the organization's Orchestrator settings. The settings
+ * page saves them as one company setting (`fleet-ops.allocation-settings`);
+ * every runtime consumer (workbench runs, the public API, auto-allocation)
+ * reads them through here so they all see what the organization selected.
+ */
+class OrchestratorSettings
+{
+    public const KEY = 'fleet-ops.allocation-settings';
+
+    /**
+     * System-level engine key read before the company setting existed.
+     * Still honoured as the default for organizations that never saved.
+     */
+    public const LEGACY_ENGINE_KEY = 'fleetops.orchestrator_engine';
+
+    public const DEFAULT_ENGINE = 'greedy';
+
+    public static function defaults(): array
+    {
+        return [
+            'allocation_engine'           => static::DEFAULT_ENGINE,
+            'auto_allocate_on_create'     => false,
+            'auto_reallocate_on_complete' => false,
+            'max_travel_time_seconds'     => 3600,
+            'balance_workload'            => false,
+        ];
+    }
+
+    /**
+     * Resolve the organization's settings merged over the defaults.
+     */
+    public static function forCompany(?string $companyUuid): array
+    {
+        $saved    = Setting::lookupForCompany($companyUuid, static::KEY, []);
+        $saved    = array_filter(is_array($saved) ? $saved : [], fn ($value) => $value !== null && $value !== '');
+        $defaults = static::defaults();
+
+        if (!isset($saved['allocation_engine'])) {
+            $defaults['allocation_engine'] = Setting::lookup(static::LEGACY_ENGINE_KEY) ?: static::DEFAULT_ENGINE;
+        }
+
+        return array_merge($defaults, $saved);
+    }
+
+    /**
+     * Identifier of the orchestration engine the organization selected.
+     */
+    public static function engineForCompany(?string $companyUuid): string
+    {
+        return (string) static::forCompany($companyUuid)['allocation_engine'];
+    }
+}

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

@@ -0,0 +1,165 @@
+<?php
+
+namespace Fleetbase\FleetOps\Orchestration\Support;
+
+use Fleetbase\FleetOps\Support\Utils;
+use Fleetbase\LaravelMysqlSpatial\Types\Point;
+use Illuminate\Support\Collection;
+
+/**
+ * RouteMetrics.
+ *
+ * Estimates per-stop arrival times and route distance/duration for engines
+ * that only decide a sequence (greedy, the built-in route sequencer) or for
+ * solver routes that came back without some of those figures.
+ *
+ * Legs are measured with FleetOps' local distance-matrix calculation
+ * (Utils::calculateDrivingDistanceAndTime), which needs no routing provider,
+ * so estimates are always available and are flagged as such in the summary.
+ *
+ * Assignment fields follow the VROOM step convention so every engine
+ * produces the same shape:
+ *   - arrival:        unix timestamp the vehicle reaches the order's last stop
+ *   - distance:       cumulative route distance (m) at that stop
+ *   - duration:       cumulative travel time (s) at that stop
+ *   - route_distance: total distance (m) of the vehicle's route
+ *   - route_duration: total travel time (s) of the vehicle's route
+ */
+class RouteMetrics
+{
+    /**
+     * Measure an ordered stop list.
+     *
+     * @param array|null $start     [lat, lng] the vehicle starts from, or null to start at the first stop
+     * @param array      $stops     ordered list of ['order_id' => string, 'lat' => float, 'lng' => float]
+     * @param int        $startTime unix timestamp the route starts
+     *
+     * @return array{orders: array<string, array{arrival: int, distance: int, duration: int}>, distance: int, duration: int}
+     */
+    public static function measure(?array $start, array $stops, int $startTime): array
+    {
+        $distance = 0.0;
+        $duration = 0.0;
+        $previous = $start;
+        $orders   = [];
+
+        foreach ($stops as $stop) {
+            $current = [(float) $stop['lat'], (float) $stop['lng']];
+
+            if ($previous !== null) {
+                $leg = Utils::calculateDrivingDistanceAndTime(new Point($previous[0], $previous[1]), new Point($current[0], $current[1]));
+                $distance += (float) $leg->distance;
+                $duration += (float) $leg->time;
+            }
+
+            // The order's figures are those of its last stop in the route.
+            $orders[$stop['order_id']] = [
+                'arrival'  => $startTime + (int) round($duration),
+                'distance' => (int) round($distance),
+                'duration' => (int) round($duration),
+            ];
+            $previous = $current;
+        }
+
+        return [
+            'orders'   => $orders,
+            'distance' => (int) round($distance),
+            'duration' => (int) round($duration),
+        ];
+    }
+
+    /**
+     * Fill in arrival, distance and duration figures the engine did not supply.
+     *
+     * A route without any engine timing is estimated in full; a route with
+     * engine timing keeps the engine's figures and only has gaps filled.
+     *
+     * @param array      $result   standard orchestration result
+     * @param Collection $orders   orders that were orchestrated, keyed or not
+     * @param Collection $vehicles vehicles that were available to the run
+     */
+    public static function annotate(array $result, Collection $orders, Collection $vehicles, ?int $startTime = null): array
+    {
+        $assignments = $result['assignments'] ?? [];
+        if (empty($assignments)) {
+            return $result;
+        }
+
+        $startTime     = $startTime ?? now()->timestamp;
+        $ordersById    = $orders->keyBy('public_id');
+        $vehiclesById  = $vehicles->keyBy('public_id');
+        $routes        = [];
+        $estimated     = false;
+
+        foreach ($assignments as $index => $assignment) {
+            $routes[$assignment['vehicle_id'] ?? ''][] = $index;
+        }
+
+        foreach ($routes as $vehicleId => $indexes) {
+            usort($indexes, fn ($a, $b) => ($assignments[$a]['sequence'] ?? 0) <=> ($assignments[$b]['sequence'] ?? 0));
+
+            $hasEngineTiming = collect($indexes)->contains(fn ($i) => ($assignments[$i]['arrival'] ?? null) !== null
+                || ($assignments[$i]['route_duration'] ?? null) !== null
+                || ($assignments[$i]['route_distance'] ?? null) !== null);
+
+            $stops = [];
+            foreach ($indexes as $i) {
+                $order = $ordersById->get($assignments[$i]['order_id'] ?? null);
+                if (!$order) {
+                    continue;
+                }
+                foreach (OrchestrationPayloadBuilder::buildRouteStops($order) as $stop) {
+                    $stops[] = ['order_id' => $order->public_id, 'lng' => $stop['location'][0], 'lat' => $stop['location'][1]];
+                }
+            }
+
+            $metrics = static::measure(static::vehicleStart($vehiclesById->get($vehicleId), $ordersById, $assignments, $indexes), $stops, $startTime);
+
+            foreach ($indexes as $i) {
+                $orderMetrics = $metrics['orders'][$assignments[$i]['order_id'] ?? ''] ?? null;
+                $estimate     = [
+                    'arrival'        => $orderMetrics['arrival'] ?? null,
+                    'distance'       => $orderMetrics['distance'] ?? null,
+                    'duration'       => $orderMetrics['duration'] ?? null,
+                    'route_distance' => $metrics['distance'],
+                    'route_duration' => $metrics['duration'],
+                ];
+
+                foreach ($estimate as $key => $value) {
+                    if (!$hasEngineTiming || ($assignments[$i][$key] ?? null) === null) {
+                        $assignments[$i][$key] = $value;
+                        $estimated             = true;
+                    }
+                }
+            }
+        }
+
+        $result['assignments'] = $assignments;
+
+        $summary            = $result['summary'] ?? [];
+        $routeTotals        = collect($routes)->map(fn ($indexes) => $assignments[$indexes[0]]);
+        $summary['distance'] ??= (int) $routeTotals->sum('route_distance');
+        $summary['duration'] ??= (int) $routeTotals->sum('route_duration');
+        $summary['metrics'] = $estimated ? 'estimated' : ($summary['metrics'] ?? 'engine');
+        $result['summary']  = $summary;
+
+        return $result;
+    }
+
+    /**
+     * Resolve the [lat, lng] a vehicle starts from: the run's vehicle list
+     * first, then the vehicle relation of one of its orders.
+     */
+    protected static function vehicleStart($vehicle, Collection $ordersById, array $assignments, array $indexes): ?array
+    {
+        if (!$vehicle) {
+            $order   = $ordersById->get($assignments[$indexes[0]]['order_id'] ?? null);
+            $vehicle = $order?->relationLoaded('vehicle') ? $order->vehicle : null;
+        }
+
+        $driver   = $vehicle?->relationLoaded('driver') ? $vehicle->driver : null;
+        $location = $driver?->location ?? $vehicle?->location;
+
+        return $location ? [(float) $location->getLat(), (float) $location->getLng()] : null;
+    }
+}

package/server/src/Providers/EventServiceProvider.php

@@ -23,6 +23,17 @@ class EventServiceProvider extends ServiceProvider
         \Fleetbase\FleetOps\Events\OrderFailed::class         => [\Fleetbase\Listeners\SendResourceLifecycleWebhook::class, \Fleetbase\FleetOps\Listeners\NotifyOrderEvent::class],
         \Fleetbase\FleetOps\Events\OrderReady::class          => [\Fleetbase\FleetOps\Listeners\HandleOrderReady::class],
 
+        /*
+         * Stop Events
+         *
+         * Public tracking channels follow waypoint and entity activity. Order status, assignment
+         * and ETA changes are published from the order observer; positions from the tracking endpoints.
+         */
+        \Fleetbase\FleetOps\Events\WaypointActivityChanged::class => [\Fleetbase\FleetOps\Listeners\PublishTrackingUpdates::class],
+        \Fleetbase\FleetOps\Events\WaypointCompleted::class       => [\Fleetbase\FleetOps\Listeners\PublishTrackingUpdates::class],
+        \Fleetbase\FleetOps\Events\EntityActivityChanged::class   => [\Fleetbase\FleetOps\Listeners\PublishTrackingUpdates::class],
+        \Fleetbase\FleetOps\Events\EntityCompleted::class         => [\Fleetbase\FleetOps\Listeners\PublishTrackingUpdates::class],
+
         /*
          * Geofence Events
          *

package/server/src/Providers/FleetOpsServiceProvider.php

@@ -159,6 +159,7 @@ class FleetOpsServiceProvider extends CoreServiceProvider
         });
         $this->registerNotifications();
         $this->registerAiCapabilities();
+        $this->registerSocketChannels();
         $this->registerExpansionsFrom(__DIR__ . '/../Expansions');
 
         // Register built-in orchestration engines.
@@ -251,6 +252,8 @@ class FleetOpsServiceProvider extends CoreServiceProvider
             \Fleetbase\FleetOps\Notifications\LateDeparture::class,
             \Fleetbase\FleetOps\Notifications\RouteDeviation::class,
             \Fleetbase\FleetOps\Notifications\ProlongedStoppage::class,
+            \Fleetbase\FleetOps\Notifications\OrderChanged::class,
+            \Fleetbase\FleetOps\Notifications\OrderUnassigned::class,
         ]);
 
         // Register Notifiables
@@ -265,6 +268,16 @@ class FleetOpsServiceProvider extends CoreServiceProvider
         ]);
     }
 
+    /**
+     * Register who may subscribe to FleetOps realtime channels, and the driver socket principal.
+     */
+    protected function registerSocketChannels(): void
+    {
+        $this->callAfterResolving(\Fleetbase\Support\SocketCluster\SocketChannelRegistry::class, function (\Fleetbase\Support\SocketCluster\SocketChannelRegistry $registry) {
+            \Fleetbase\FleetOps\Support\SocketChannels::register($registry);
+        });
+    }
+
     protected function registerAiCapabilities(): void
     {
         if (!Utils::classExists(\Fleetbase\Ai\Support\AiCapabilityRegistry::class)) {

package/server/src/Support/ApiCacheThrottle.php

@@ -0,0 +1,76 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support;
+
+use Fleetbase\Support\ApiModelCache;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Support\Facades\Cache;
+
+/**
+ * Invalidates API caches at most once per window for writes too frequent to
+ * invalidate on every call.
+ *
+ * Location pings write drivers and vehicles every few seconds per device, and
+ * order lists embed both, so invalidating on each ping would keep those lists
+ * from ever being served from cache. Throttled, a ping costs one Cache::add,
+ * and cached lists show a location at most a window old.
+ */
+class ApiCacheThrottle
+{
+    /**
+     * Seconds between invalidations for location writes.
+     */
+    public const LOCATION_WINDOW = 60;
+
+    /**
+     * Run a frequent write (a telemetry save) with its model events, but invalidate
+     * the model's cached lists at most once per window instead of on every write.
+     *
+     * Order and food truck lists embed vehicles, so invalidating them on every
+     * telemetry event would keep them from ever being served from cache for any
+     * company with streaming devices. Needs ApiModelCache::withoutInvalidating()
+     * (fleetbase/core-api#301); with an older core the write invalidates as before.
+     *
+     * @template T
+     *
+     * @param \Closure(): T $write
+     *
+     * @return T
+     */
+    public static function telemetryWrite(Model $model, \Closure $write, int $seconds = self::LOCATION_WINDOW): mixed
+    {
+        // @codeCoverageIgnoreStart
+        // fleetbase/core-api ^1.6.69, which this package requires, always has it; the
+        // branch only serves an install that pinned an older core by hand.
+        if (!method_exists(ApiModelCache::class, 'withoutInvalidating')) {
+            return $write();
+        }
+        // @codeCoverageIgnoreEnd
+
+        $result = ApiModelCache::withoutInvalidating($write);
+        static::invalidate($model, $model->company_uuid, $seconds);
+
+        return $result;
+    }
+
+    /**
+     * Invalidate the model's table for the company unless that was done within the window.
+     */
+    public static function invalidate(Model $model, ?string $companyUuid, int $seconds = self::LOCATION_WINDOW): void
+    {
+        if (!ApiModelCache::isCachingEnabled()) {
+            return;
+        }
+
+        $key = 'fleetops:api_cache_throttle:' . $model->getTable() . ':' . ($companyUuid ?? 'all');
+
+        try {
+            if (Cache::add($key, true, $seconds)) {
+                ApiModelCache::invalidateModelCache($model, $companyUuid);
+            }
+        } catch (\Throwable $e) {
+            // A location ping must never fail on cache bookkeeping; cached lists then
+            // show the location until their TTL. Core versions before #301 can throw here.
+        }
+    }
+}