@fleetbase/fleetops-engine 0.6.70 → 0.6.72

package/server/src/Http/Controllers/Internal/v1/OrchestrationController.php

@@ -13,12 +13,15 @@ use Fleetbase\FleetOps\Models\Payload;
 use Fleetbase\FleetOps\Models\Place;
 use Fleetbase\FleetOps\Models\Vehicle;
 use Fleetbase\FleetOps\Models\Vendor;
+use Fleetbase\FleetOps\Models\Waypoint;
+use Fleetbase\FleetOps\Orchestration\Contracts\OrchestrationEngineInterface;
 use Fleetbase\FleetOps\Orchestration\Engines\DriverAssignmentEngine;
 use Fleetbase\FleetOps\Orchestration\Engines\RouteSequencingEngine;
 use Fleetbase\FleetOps\Orchestration\OrchestrationEngineRegistry;
+use Fleetbase\FleetOps\Orchestration\Support\OrchestratorSettings;
+use Fleetbase\FleetOps\Orchestration\Support\RouteMetrics;
 use Fleetbase\FleetOps\Traits\AuthorizesMethods;
 use Fleetbase\Http\Controllers\Controller;
-use Fleetbase\Models\Setting;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 use Illuminate\Support\Carbon;
@@ -42,6 +45,11 @@ class OrchestrationController extends Controller
 {
     use AuthorizesMethods;
 
+    /**
+     * Engines that assign orders to vehicles without producing a stop sequence.
+     */
+    protected const ASSIGNMENT_ONLY_ENGINES = ['greedy', 'capacity'];
+
     public function __construct(protected OrchestrationEngineRegistry $registry)
     {
         $this->authorizeMethods([
@@ -281,7 +289,7 @@ class OrchestrationController extends Controller
         // ── Run engine ────────────────────────────────────────────────────────
         $engineId = $mode === 'assign_drivers'
             ? 'driver_assignment'
-            : ($request->input('options.engine') ?? $this->orchestratorEngineSetting());
+            : ($request->input('options.engine') ?: $this->orchestratorEngineSetting());
 
         try {
             if ($mode === 'assign_drivers') {
@@ -308,14 +316,13 @@ class OrchestrationController extends Controller
                         }
                     }
                 }
-                $engine = $this->routeSequencingEngine();
-                $result = $engine->sequence($orders, $options);
+                $result = $this->optimizeRoutes($engineId, $orders, $options);
             } else {
-                $engine = $this->registry->resolve($engineId);
-                $result = $engine->allocate($orders, $vehicles, $options);
+                $result = $this->registry->allocateWithFallback($engineId, $orders, $vehicles, $options);
             }
         } catch (\RuntimeException $e) {
-            // Engine is unavailable (e.g. VROOM not reachable).
+            // Engine is unavailable (e.g. VROOM not reachable) and there is no
+            // built-in engine to fall back to.
             // Return a structured JSON 503 so the frontend can display a
             // user-friendly message instead of an unhandled exception page.
             return response()->json([
@@ -325,6 +332,10 @@ class OrchestrationController extends Controller
             ], 503);
         }
 
+        if ($mode !== 'assign_drivers') {
+            $result = RouteMetrics::annotate($result, $orders, $vehicles);
+        }
+
         return response()->json($result);
     }
 
@@ -384,7 +395,71 @@ class OrchestrationController extends Controller
 
     protected function orchestratorEngineSetting(): string
     {
-        return Setting::lookup('fleetops.orchestrator_engine', 'greedy');
+        return OrchestratorSettings::engineForCompany($this->companyUuid());
+    }
+
+    /**
+     * Re-sequence each vehicle's already-assigned orders.
+     *
+     * A solver engine (e.g. VROOM) is run once per vehicle, restricted to
+     * that vehicle and its orders, so the stop order, arrival times and
+     * distances come from the selected engine. Engines that only assign
+     * orders (greedy, capacity) cannot sequence stops, and a solver that is
+     * missing or unavailable is replaced; in both cases the built-in route
+     * sequencer runs and the result says which engine ran and why.
+     */
+    protected function optimizeRoutes(string $engineId, $orders, array $options): array
+    {
+        $warn = true;
+        if (in_array($engineId, self::ASSIGNMENT_ONLY_ENGINES, true)) {
+            $warn   = false;
+            $reason = sprintf('The "%s" engine assigns orders but does not sequence stops; stops were sequenced by the built-in route sequencer.', $engineId);
+        } elseif (!$this->registry->has($engineId)) {
+            $reason = sprintf('No orchestration engine is registered as "%s".', $engineId);
+        } else {
+            try {
+                return $this->sequenceWithEngine($this->registry->resolve($engineId), $orders, $options);
+            } catch (\RuntimeException $e) {
+                $reason = $e->getMessage();
+            }
+        }
+
+        $result = $this->routeSequencingEngine()->sequence($orders, $options);
+
+        return OrchestrationEngineRegistry::markFallback($result, $result['summary']['engine'] ?? 'route_sequencing', $engineId, $reason, $warn);
+    }
+
+    /**
+     * Run a solver engine once per vehicle group, keeping every order on its vehicle.
+     */
+    protected function sequenceWithEngine(OrchestrationEngineInterface $engine, $orders, array $options): array
+    {
+        $options     = array_merge($options, ['allocation_strategy' => 'route_aware']);
+        $assignments = [];
+        $unassigned  = [];
+
+        foreach ($orders->groupBy(fn ($order) => $order->vehicle_assigned_uuid ?? '') as $vehicleUuid => $vehicleOrders) {
+            $vehicle = $vehicleUuid !== '' && $vehicleOrders->first()->relationLoaded('vehicle') ? $vehicleOrders->first()->vehicle : null;
+            if (!$vehicle) {
+                // Without an assigned vehicle there is no route to sequence.
+                array_push($unassigned, ...$vehicleOrders->pluck('public_id')->all());
+                continue;
+            }
+
+            $result = $engine->allocate($vehicleOrders->values(), collect([$vehicle]), $options);
+            array_push($assignments, ...($result['assignments'] ?? []));
+            array_push($unassigned, ...($result['unassigned'] ?? []));
+        }
+
+        return [
+            'assignments' => $assignments,
+            'unassigned'  => array_values(array_unique($unassigned)),
+            'summary'     => [
+                'engine'     => $engine->getIdentifier(),
+                'assigned'   => count($assignments),
+                'unassigned' => count(array_unique($unassigned)),
+            ],
+        ];
     }
 
     protected function driverAssignmentEngine(): DriverAssignmentEngine
@@ -415,9 +490,10 @@ class OrchestrationController extends Controller
             return response()->json(['error' => 'No assignments provided.'], 422);
         }
 
-        $committed = [];
-        $failed    = [];
-        $manifests = [];
+        $committed   = [];
+        $failed      = [];
+        $manifests   = [];
+        $resequenced = false;
 
         $this->beginOrchestrationTransaction();
         try {
@@ -502,6 +578,7 @@ class OrchestrationController extends Controller
                     if (!empty($assignment['waypoint_sequence']) && $order->payload) {
                         foreach ($assignment['waypoint_sequence'] as $seq => $waypointId) {
                             $this->updateWaypointSequence($order->payload_uuid, $waypointId, $seq);
+                            $resequenced = true;
                         }
                     }
 
@@ -523,6 +600,11 @@ class OrchestrationController extends Controller
             return response()->json(['error' => 'Commit failed: ' . $e->getMessage()], 500);
         }
 
+        // Waypoint sequences are written without model events
+        if ($resequenced) {
+            Waypoint::invalidateApiCacheManually($companyUuid);
+        }
+
         return response()->json([
             'committed' => $committed,
             'failed'    => $failed,

package/server/src/Http/Controllers/Internal/v1/OrderController.php

@@ -10,6 +10,7 @@ use Fleetbase\FleetOps\Events\OrderDispatchFailed;
 use Fleetbase\FleetOps\Events\OrderStarted;
 use Fleetbase\FleetOps\Events\WaypointActivityChanged;
 use Fleetbase\FleetOps\Events\WaypointCompleted;
+use Fleetbase\FleetOps\Exceptions\OrderEditLockedException;
 use Fleetbase\FleetOps\Exports\OrderExport;
 use Fleetbase\FleetOps\Flow\Activity;
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
@@ -19,6 +20,7 @@ use Fleetbase\FleetOps\Http\Requests\Internal\CreateOrderRequest;
 use Fleetbase\FleetOps\Http\Resources\v1\Index\Order as OrderIndexResource;
 use Fleetbase\FleetOps\Http\Resources\v1\Order as OrderResource;
 use Fleetbase\FleetOps\Http\Resources\v1\Proof as ProofResource;
+use Fleetbase\FleetOps\Http\Resources\v1\PublicOrderTracking;
 use Fleetbase\FleetOps\Imports\OrdersImport;
 use Fleetbase\FleetOps\Jobs\FinalizeInternalOrderCreation;
 use Fleetbase\FleetOps\Jobs\NotifyBulkAssignedDriver;
@@ -33,6 +35,7 @@ use Fleetbase\FleetOps\Models\ServiceQuote;
 use Fleetbase\FleetOps\Models\TrackingStatus;
 use Fleetbase\FleetOps\Models\Waypoint;
 use Fleetbase\FleetOps\Notifications\OrderPing;
+use Fleetbase\FleetOps\Support\OrderEdit;
 use Fleetbase\FleetOps\Support\ResolvesOrderServiceStops;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Http\Requests\ExportRequest;
@@ -54,6 +57,12 @@ use Maatwebsite\Excel\Facades\Excel;
 class OrderController extends FleetOpsController
 {
     use ResolvesOrderServiceStops;
+
+    /**
+     * The one answer the public tracking lookup gives for any number it cannot resolve.
+     */
+    public const TRACKING_LOOKUP_ERROR = 'No order found using tracking number provided.';
+
     /**
      * Permissions for methods AuthorizationGuard cannot map to a schema action (see FleetOpsController).
      *
@@ -163,8 +172,15 @@ class OrderController extends FleetOpsController
                         $input['type'] = 'transport';
                     }
 
+                    // a configured lifecycle always starts at its initial activity; otherwise
                     // if no status is set its default to `created`
-                    if (!isset($input['status'])) {
+                    if ($resolvedOrderConfig && $resolvedOrderConfig->hasConfiguredLifecycle()) {
+                        $input['status'] = $resolvedOrderConfig->getInitialStatusCode();
+                        if (!$resolvedOrderConfig->allowsDispatch()) {
+                            $input['dispatched'] = false;
+                            $input['adhoc']      = false;
+                        }
+                    } elseif (!isset($input['status'])) {
                         $input['status'] = 'created';
                     }
 
@@ -185,11 +201,13 @@ class OrderController extends FleetOpsController
                     $entities            = Utils::get($input, 'payload.entities');
                     $uploads             = Utils::get($input, 'files', []);
                     $customFieldValues   = Utils::get($input, 'custom_field_values', []);
+                    $orderConfig         = $order->config();
+                    $hasLifecycle        = $orderConfig && $orderConfig->hasConfiguredLifecycle();
 
                     // save order route & payload with request input
                     $order
                         ->setRoute($route)
-                        ->setStatus('created', false)
+                        ->setStatus($hasLifecycle ? $orderConfig->getInitialStatusCode() : 'created', false)
                         ->insertPayload($payload)
                         ->insertWaypoints($waypoints)
                         ->insertEntities($entities);
@@ -212,8 +230,12 @@ class OrderController extends FleetOpsController
                         );
                     }
 
-                    // Check dispatch flag with backward compatibility (default true)
+                    // Check dispatch flag with backward compatibility (default true).
+                    // Configs with a lifecycle that disables dispatch are never dispatched.
                     $shouldDispatch = isset($input['dispatched']) ? (bool) $input['dispatched'] : true;
+                    if ($hasLifecycle && !$orderConfig->allowsDispatch()) {
+                        $shouldDispatch = false;
+                    }
 
                     // dispatch if flagged true, otherwise ensure order stays in created state
                     if ($shouldDispatch) {
@@ -300,6 +322,19 @@ class OrderController extends FleetOpsController
             return $this->errorResponse('Unable to find order to update route for.');
         }
 
+        // Refuse a route edit the order's status locks (completed, canceled, expired)
+        $edit = $this->beginOrderEdit($order);
+        try {
+            $edit->guard($edit->requestedChanges(array_filter([
+                'pickup'    => $hasPickupInput ? true : null,
+                'dropoff'   => $hasDropoffInput ? true : null,
+                'return'    => $hasReturnInput ? true : null,
+                'waypoints' => ($hasWaypointsInput || $hasPickupInput || $hasDropoffInput || $hasReturnInput) ? true : null,
+            ])));
+        } catch (OrderEditLockedException $exception) {
+            return $this->errorResponse($exception->getMessage(), 422, $exception->toResponseData());
+        }
+
         if ($hasPickupInput) {
             if ($pickup) {
                 $order->payload->setPickup($pickup, ['save' => true]);
@@ -334,14 +369,9 @@ class OrderController extends FleetOpsController
             $order->payload->removeWaypoints();
         }
 
-        $startingDestination = $order->payload->getPickupOrFirstWaypoint();
-        if (!$startingDestination) {
-            $startingDestination = $order->payload->getDropoffOrLastWaypoint();
-        }
-
-        if ($startingDestination instanceof Place || $startingDestination instanceof Waypoint) {
-            $order->payload->setCurrentWaypoint($startingDestination);
-        }
+        // Only a changed route moves the current waypoint, and an order under way keeps
+        // the driver's stop; distance, time, tracking and `order.changed` follow the change
+        $this->commitOrderEdit($edit);
 
         $order->load(['payload.pickup', 'payload.dropoff', 'payload.return', 'payload.waypoints']);
 
@@ -483,7 +513,7 @@ class OrderController extends FleetOpsController
         $successful = [];
 
         foreach ($orders as $order) {
-            if ($order->status !== 'created') {
+            if ($order->status !== 'created' || $order->config()?->allowsDispatch() === false) {
                 $failed[] = $order->uuid;
                 continue;
             }
@@ -582,7 +612,12 @@ class OrderController extends FleetOpsController
             return $this->errorResponse('No order found to cancel.');
         }
 
-        $order->cancel();
+        $reason = $request->input('reason');
+        if (is_string($reason) && trim($reason) !== '') {
+            $order->cancelWithReason($reason);
+        } else {
+            $order->cancel();
+        }
 
         return $this->jsonResponse(
             [
@@ -615,6 +650,10 @@ class OrderController extends FleetOpsController
             return $this->errorResponse('No order config found for dispatch.');
         }
 
+        if (!$order->config()->allowsDispatch()) {
+            return $this->errorResponse('Orders of this type are not dispatched.');
+        }
+
         if (!$order->hasDriverAssigned && !$order->adhoc) {
             return $this->errorResponse('No driver assigned to dispatch!');
         }
@@ -748,10 +787,21 @@ class OrderController extends FleetOpsController
 
     protected function assignDriverToOrders($orderUuids, Driver $driver): void
     {
+        // Drivers being replaced are told once the assignment is written
+        $replaced = $this->scopedToCompany(Order::whereIn('uuid', $orderUuids))
+            ->whereNotNull('driver_assigned_uuid')
+            ->where('driver_assigned_uuid', '!=', $driver->uuid)
+            ->get();
+
         $this->scopedToCompany(Order::whereIn('uuid', $orderUuids))->update([
             'driver_assigned_uuid' => $driver->uuid,
             'updated_at'           => now(),
         ]);
+        Order::invalidateApiCacheManually(session('company'));
+
+        foreach ($replaced as $order) {
+            $order->notifyDriverUnassigned($order->driver_assigned_uuid);
+        }
     }
 
     protected function dispatchBulkAssignedDriverNotification(array $orderUuids, Driver $driver): void
@@ -769,9 +819,19 @@ class OrderController extends FleetOpsController
         return response()->json($payload);
     }
 
-    protected function errorResponse(string $message, int $status = 400)
+    protected function errorResponse(string $message, int $status = 400, array $data = [])
+    {
+        return response()->error($message, $status, $data);
+    }
+
+    protected function beginOrderEdit(Order $order): OrderEdit
     {
-        return response()->error($message, $status);
+        return OrderEdit::begin($order);
+    }
+
+    protected function commitOrderEdit(OrderEdit $edit): array
+    {
+        return $edit->commit();
     }
 
     /**
@@ -900,6 +960,19 @@ class OrderController extends FleetOpsController
         $activity    = $request->array('activity');
         $activity    = new Activity($activity, $order->getConfigFlow());
 
+        // Configs with strict transitions only accept a configured child of the current
+        // activity, and the server-side activity definition replaces the client payload.
+        $orderConfig = $order->config();
+        if ($orderConfig && $orderConfig->hasStrictTransitions()) {
+            $targetCode = $activity->get('code');
+            $configured = $targetCode ? $orderConfig->getActivityByCode($targetCode) : null;
+            if (!$configured || !$orderConfig->canTransition($order->status, $targetCode)) {
+                return response()->error('This activity is not a permitted next step for the order.', 422);
+            }
+
+            $activity = $configured;
+        }
+
         $requiresProof = Utils::isActivity($activity)
             && ($activity->get('require_pod') || ($activity->completesOrder() && $order->pod_required));
         if ($requiresProof && !$proof && !$bypassProof) {
@@ -1875,27 +1948,43 @@ class OrderController extends FleetOpsController
         return response()->json(OrderConfig::default());
     }
 
+    /**
+     * Look up an order for the public Track Order page.
+     *
+     * Answers with `PublicOrderTracking`, never the full order resource: the
+     * tracking number is the only credential here. A missing, malformed or
+     * unknown tracking number all get the same error, so a caller cannot tell
+     * which one they hit.
+     */
     public function lookup(Request $request)
     {
-        $trackingNumber = $request->input('tracking');
-        if (!$trackingNumber) {
-            return response()->error('No tracking number provided for lookup.');
-        }
-
-        $order = $this->findOrderByTrackingNumber($trackingNumber);
+        $trackingNumber = $this->normalizeTrackingLookup($request->input('tracking'));
+        $order          = $trackingNumber ? $this->findOrderByTrackingNumber($trackingNumber) : null;
 
         if (!$order) {
-            return response()->error('No order found using tracking number provided.');
+            return response()->error(static::TRACKING_LOOKUP_ERROR);
         }
 
-        // load required relations
-        $order->loadMissing(['trackingNumber', 'payload', 'trackingStatuses']);
-
-        // load tracker data
+        $order->loadMissing(['trackingNumber', 'trackingStatuses', 'payload.pickup', 'payload.dropoff', 'payload.waypoints', 'payload.entities']);
         $order->tracker_data = $order->tracker()->toArray();
-        $order->eta          = $order->tracker()->eta();
 
-        return new OrderResource($order);
+        return new PublicOrderTracking($order);
+    }
+
+    /**
+     * The tracking number to look up, or null when the input cannot be one:
+     * not a string, blank, too long, or outside the characters tracking
+     * numbers use.
+     */
+    protected function normalizeTrackingLookup($input): ?string
+    {
+        if (!is_string($input)) {
+            return null;
+        }
+
+        $input = trim($input);
+
+        return preg_match('/^[A-Za-z0-9][A-Za-z0-9._\-]{0,99}$/', $input) === 1 ? $input : null;
     }
 
     /**
@@ -1952,6 +2041,7 @@ class OrderController extends FleetOpsController
         }
 
         $order->saveQuietly();
+        $order->invalidateApiCache();
 
         return response()->json([
             'status'       => 'OK',

package/server/src/Http/Controllers/Internal/v1/PositionController.php

@@ -6,6 +6,10 @@ use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
 use Fleetbase\FleetOps\Jobs\ReplayPositions;
 use Fleetbase\FleetOps\Models\Position;
 use Fleetbase\FleetOps\Support\Utils;
+use Fleetbase\Models\User;
+use Fleetbase\Support\SocketCluster\ChannelAuthorizer;
+use Fleetbase\Support\SocketCluster\SocketPrincipal;
+use Fleetbase\Support\SocketCluster\SocketToken;
 use Illuminate\Http\Request;
 
 class PositionController extends FleetOpsController
@@ -37,6 +41,11 @@ class PositionController extends FleetOpsController
             return response()->error('Position IDs are required');
         }
 
+        // With socket authentication on, the replay may only publish to a channel the user could subscribe to.
+        if (SocketToken::enabled() && !$this->canReplayTo($request, $channelId)) {
+            return response()->error('You are not allowed to replay positions to this channel.', 403);
+        }
+
         $positions = Position::whereIn('uuid', $positionIds)
             ->where('company_uuid', session('company'))
             ->orderBy('created_at')
@@ -57,6 +66,19 @@ class PositionController extends FleetOpsController
         ]);
     }
 
+    /**
+     * Whether the requesting user may subscribe to, and so receive a replay on, the channel.
+     */
+    protected function canReplayTo(Request $request, mixed $channelId): bool
+    {
+        $user = $request->user();
+        if (!$user instanceof User || !is_string($channelId) || $channelId === '' || strlen($channelId) > 255 || preg_match('/\s/', $channelId)) {
+            return false;
+        }
+
+        return app(ChannelAuthorizer::class)->authorize(SocketPrincipal::forUser($user, session('company')), $channelId)->allow;
+    }
+
     /**
      * Get position statistics/metrics.
      *

package/server/src/Http/Controllers/Internal/v1/ProofController.php

@@ -21,6 +21,53 @@ class ProofController extends FleetOpsController
      */
     public $resource = 'proof';
 
+    /**
+     * The most a dashboard can ask for in one request.
+     */
+    public const RECENT_LIMIT_MAX = 24;
+
+    /**
+     * The latest photo proofs captured for the company's orders, newest first,
+     * for the dashboard's proof-of-delivery tile.
+     */
+    public function recent(Request $request)
+    {
+        $limit  = max(1, min(static::RECENT_LIMIT_MAX, (int) $request->input('limit', 12)));
+        $proofs = Proof::where('company_uuid', session('company'))
+            ->whereNotNull('order_uuid')
+            ->whereHas('file', fn ($query) => $query->where('type', 'photo'))
+            ->with(['file', 'order.customer'])
+            ->orderByDesc('created_at')
+            ->limit($limit)
+            ->get();
+
+        return $this->jsonResponse([
+            'proofs' => $proofs->map(fn (Proof $proof) => $this->recentProofPayload($proof))->values()->all(),
+        ]);
+    }
+
+    protected function recentProofPayload(Proof $proof): array
+    {
+        $order = $proof->order;
+
+        return [
+            'id'            => $proof->public_id,
+            'order_id'      => $order?->public_id,
+            'customer_name' => data_get($order, 'customer.name'),
+            'remarks'       => $proof->remarks,
+            'url'           => $this->photoUrl($proof->file),
+            'captured_at'   => $proof->created_at?->toIso8601String(),
+        ];
+    }
+
+    /**
+     * File::url signs the object on s3/gcs, so a private bucket still serves the photo.
+     */
+    protected function photoUrl(File $file): ?string
+    {
+        return $file->url;
+    }
+
     /**
      * Verify a QR code.
      *
@@ -83,8 +130,8 @@ class ProofController extends FleetOpsController
         // set the signature storage path
         $path = $this->signatureStoragePath($proof);
 
-        // upload signature
-        $this->storeSignature($path, base64_decode($signature), 'public');
+        // upload signature (private object; File::url serves it through a signed URL)
+        $this->storeSignature($path, base64_decode($signature));
 
         // create file record for upload
         $file = $this->createSignatureFile($path, $signature, $proof);
@@ -121,9 +168,13 @@ class ProofController extends FleetOpsController
         return Proof::create($attributes);
     }
 
-    protected function storeSignature(string $path, string|false $contents, string $visibility): void
+    /**
+     * Writes without an ACL: the media bucket enforces bucket-owner object ownership, so a
+     * 'public' visibility (public-read ACL) makes S3 reject the PUT and put() return false.
+     */
+    protected function storeSignature(string $path, string|false $contents): void
     {
-        Storage::disk('s3')->put($path, $contents, $visibility);
+        Storage::disk('s3')->put($path, $contents);
     }
 
     /**