@fleetbase/fleetops-engine 0.6.15 → 0.6.17

package/addon/components/order-config-manager/activity-flow.js

@@ -435,7 +435,7 @@ export default class OrderConfigManagerActivityFlowComponent extends Component {
      * Initializes the activity flow by either loading from configuration or creating a default flow.
      */
     initializeActivityFlow() {
-        const hasFlow = Object.keys(this.config.flow).length > 0;
+        const hasFlow = this.config && Object.keys(this.config.flow).length > 0;
         if (hasFlow) {
             this.deserializeFlow(this.config.flow);
             this.initializeContext();

package/addon/components/order-config-manager/details.js

@@ -29,9 +29,13 @@ export default class OrderConfigManagerDetailsComponent extends Component {
      * @param {Object} owner - The owner of the component.
      * @param {Object} args - The arguments passed to the component, including the configuration.
      */
-    constructor(owner, { config }) {
+    constructor(owner, { config, configManagerContext }) {
         super(...arguments);
         this.config = config;
+
+        configManagerContext.on('onConfigChanged', (newConfig) => {
+            this.changeConfig(newConfig);
+        });
     }
 
     /**
@@ -87,11 +91,23 @@ export default class OrderConfigManagerDetailsComponent extends Component {
     @task *deleteConfig() {
         try {
             yield this.config.destroyRecord();
+            this.notifications.success(`Order config ${this.config.name} was deleted.`);
+
             if (typeof this.args.onConfigDeleted === 'function') {
-                this.args.onConfigDeleted(this.config);
+                this.args.onConfigDeleted();
             }
         } catch (error) {
             this.notifications.serverError(error);
         }
     }
+
+    /**
+     * Handle change of config.
+     *
+     * @param {OrderConfigModel} newConfig
+     * @memberof OrderConfigManagerDetailsComponent
+     */
+    changeConfig(newConfig) {
+        this.config = newConfig;
+    }
 }

package/addon/components/order-config-manager.hbs

@@ -20,6 +20,7 @@
             this.tab.component
             configManagerContext=this.configManagerContext
             config=this.currentConfig
+            allConfigs=this.configs
             context=this.context
             contextModel=this.contextModel
             tabOptions=this.tab
@@ -31,5 +32,7 @@
         )
         onTabChanged=this.onTabChanged
         onClickCreateOrderConfig=this.createNewOrderConfig
+        childTaskRunning=this.childTaskRunning
+        configManagerContext=this.configManagerContext
     )
 }}

package/addon/components/order-config-manager.js

@@ -31,6 +31,7 @@ export default class OrderConfigManagerComponent extends Component {
     @tracked context;
     @tracked contextModel;
     @tracked ready = false;
+    @tracked childTaskRunning = false;
 
     /**
      * Returns the array of tabs available for the panel.
@@ -62,11 +63,36 @@ export default class OrderConfigManagerComponent extends Component {
 
         this.context = context;
         this.contextModel = contextModel;
-        this.configManagerContext = configManagerContext.create();
+        this.configManagerContext = this.#createManagerContext();
         this.tab = findActiveTab(this.tabs, tab);
         this.loadOrderConfigs.perform();
     }
 
+    /**
+     * Creates a contextual object for the order config manager.
+     */
+    #createManagerContext() {
+        const component = this;
+        const ctxmc = configManagerContext.create();
+        ctxmc.loadOrderConfigs = component.loadOrderConfigs;
+        ctxmc.createNewOrderConfig = component.createNewOrderConfig;
+        ctxmc.selectConfig = component.selectConfig;
+        ctxmc.unready = function () {
+            component.ready = false;
+        };
+        ctxmc.ready = function () {
+            component.ready = true;
+        };
+        ctxmc.childTaskStarted = function () {
+            component.childTaskRunning = true;
+        };
+        ctxmc.childTaskEnded = function () {
+            component.childTaskRunning = false;
+        };
+
+        return ctxmc;
+    }
+
     /**
      * Loads all available order configs asynchronously.
      *
@@ -81,20 +107,8 @@ export default class OrderConfigManagerComponent extends Component {
         this.configs = yield this.store.findAll('order-config').then(Array.from);
 
         let currentConfig;
-        let initialOrderConfig = this.args.orderConfig;
         if (isArray(this.configs) && this.configs.length > 0) {
-            if (initialOrderConfig) {
-                currentConfig = this.configs.find((config) => {
-                    if (isModel(initialOrderConfig)) {
-                        return config.id === initialOrderConfig.id;
-                    }
-
-                    if (typeof initialOrderConfig === 'string') {
-                        return config.id === initialOrderConfig;
-                    }
-                });
-            }
-
+            currentConfig = this.configs.find((_) => _.key === 'transport');
             if (!currentConfig) {
                 currentConfig = this.configs[0];
             }
@@ -208,7 +222,6 @@ export default class OrderConfigManagerComponent extends Component {
      * in 'contextComponentCallback'.
      */
     @action onConfigDeleting() {
-        this.selectConfig(null);
         this.configManagerContext.trigger('onConfigDeleting');
         contextComponentCallback(this, 'onConfigDeleting', ...arguments);
     }

package/addon/templates/operations/order-config.hbs

@@ -82,10 +82,11 @@
                     <div class="flex flex-col items-center justify-center h-40">
                         <h4 class="text-lg text-gray-400 mb-4">{{t "fleet-ops.component.order-config-manager.select-order-config-to-start"}}</h4>
                         <Button
-                            @type="link"
+                            @type="primary"
                             @text={{t "fleet-ops.component.order-config-manager.new-order-config"}}
                             @onClick={{Context.onClickCreateOrderConfig}}
                             @permission="fleet-ops create order-config"
+                            @icon="plus"
                             class="text-blue-400"
                         />
                     </div>

package/composer.json

@@ -1,6 +1,6 @@
 {
     "name": "fleetbase/fleetops-api",
-    "version": "0.6.15",
+    "version": "0.6.17",
     "description": "Fleet & Transport Management Extension for Fleetbase",
     "keywords": [
         "fleetbase-extension",

package/extension.json

@@ -1,6 +1,6 @@
 {
     "name": "Fleet-Ops",
-    "version": "0.6.15",
+    "version": "0.6.17",
     "description": "Fleet & Transport Management Extension for Fleetbase",
     "repository": "https://github.com/fleetbase/fleetops",
     "license": "AGPL-3.0-or-later",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@fleetbase/fleetops-engine",
-    "version": "0.6.15",
+    "version": "0.6.17",
     "description": "Fleet & Transport Management Extension for Fleetbase",
     "fleetbase": {
         "route": "fleet-ops"

package/server/migrations/2025_08_11_170800_add_company_index_to_routes_table.php

@@ -0,0 +1,21 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    public function up(): void
+    {
+        Schema::table('routes', function (Blueprint $table) {
+            $table->index(['company_uuid', 'id'], 'idx_routes_company_id');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('routes', function (Blueprint $table) {
+            $table->dropIndex('idx_routes_company_id');
+        });
+    }
+};

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

@@ -30,6 +30,7 @@ use Fleetbase\Models\Company;
 use Fleetbase\Models\File;
 use Fleetbase\Models\Setting;
 use Fleetbase\Support\Auth;
+use Fleetbase\Support\TemplateString;
 use Illuminate\Database\Eloquent\ModelNotFoundException;
 use Illuminate\Http\Request;
 use Illuminate\Http\UploadedFile;
@@ -461,6 +462,14 @@ class OrderController extends Controller
             ]);
         }
 
+        // vehicle assignment
+        if ($request->has('vehicle')) {
+            $input['vehicle_assigned_uuid'] = Utils::getUuid('vehicles', [
+                'public_id'    => $request->input('vehicle'),
+                'company_uuid' => session('company'),
+            ]);
+        }
+
         // facilitator assignment
         if ($request->has('facilitator')) {
             $facilitator = Utils::getUuid(
@@ -1091,6 +1100,10 @@ class OrderController extends Controller
                 $activity->set('pod_method', $order->pod_method);
             }
 
+            // resolved status and details
+            $activity->set('_resolved_status', TemplateString::resolve($activity->get('status', ''), $order));
+            $activity->set('_resolved_details', TemplateString::resolve($activity->get('details', ''), $order));
+
             return $activity;
         });
 

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

@@ -61,7 +61,7 @@ class OrderConfigController extends FleetOpsController
         }
 
         // `core_service` order configs cannot be deleted
-        if ($orderConfig->core_service) {
+        if ($orderConfig->core_service === 1) {
             return response()->error('Core service order config\'s cannot be deleted.');
         }
 
@@ -72,5 +72,7 @@ class OrderConfigController extends FleetOpsController
 
             return new $this->resource($orderConfig);
         }
+
+        return response()->error('Unable to delete order config.');
     }
 }

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

@@ -32,6 +32,7 @@ use Fleetbase\Http\Requests\Internal\BulkDeleteRequest;
 use Fleetbase\Models\CustomFieldValue;
 use Fleetbase\Models\File;
 use Fleetbase\Models\Type;
+use Fleetbase\Support\TemplateString;
 use Illuminate\Database\Eloquent\ModelNotFoundException;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\DB;
@@ -722,20 +723,42 @@ class OrderController extends FleetOpsController
      *
      * @return \Illuminate\Http\Response
      */
-    public function nextActivity(string $id)
+    public function nextActivity(string $id, Request $request)
     {
-        $order = Order::withoutGlobalScopes()
-            ->where('uuid', $id)
-            ->orWhere('public_id', $id)
-            ->first();
+        $waypointId = $request->input('waypoint');
 
-        if (!$order) {
+        try {
+            $order = Order::findRecordOrFail($id, ['payload']);
+        } catch (ModelNotFoundException $exception) {
             return response()->error('No order found.');
         }
 
-        $nextActivities = $order->config()->nextActivity();
+        // Get waypoint record if available
+        $waypoint = null;
+        if ($waypointId) {
+            $waypoint = Waypoint::where('payload_uuid', $order->payload_uuid)->whereHas('place', function ($query) use ($waypointId) {
+                $query->where('public_id', $waypointId);
+            })->first();
+        }
+
+        $activities = $order->config()->nextActivity($waypoint);
+
+        // If activity is to complete order add proof of delivery properties if required
+        // This is a temporary fix until activity is updated to handle POD on it's own
+        $activities = $activities->map(function ($activity) use ($order) {
+            if ($activity->completesOrder() && $order->pod_required) {
+                $activity->set('require_pod', true);
+                $activity->set('pod_method', $order->pod_method);
+            }
+
+            // resolved status and details
+            $activity->set('_resolved_status', TemplateString::resolve($activity->get('status', ''), $order));
+            $activity->set('_resolved_details', TemplateString::resolve($activity->get('details', ''), $order));
+
+            return $activity;
+        });
 
-        return response()->json($nextActivities);
+        return response()->json($activities);
     }
 
     /**

package/server/src/Models/Entity.php

@@ -7,6 +7,7 @@ use Fleetbase\Casts\Json;
 use Fleetbase\Casts\PolymorphicType;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\FleetOps\Traits\HasTrackingNumber;
+use Fleetbase\FleetOps\Traits\PayloadAccessors;
 use Fleetbase\Models\Model;
 use Fleetbase\Traits\HasApiModelBehavior;
 use Fleetbase\Traits\HasInternalId;
@@ -15,6 +16,9 @@ use Fleetbase\Traits\HasPublicId;
 use Fleetbase\Traits\HasUuid;
 use Fleetbase\Traits\SendsWebhooks;
 use Fleetbase\Traits\TracksApiCredential;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+use Illuminate\Database\Eloquent\Relations\MorphTo;
 use Illuminate\Support\Carbon;
 use Illuminate\Support\Str;
 use Milon\Barcode\Facades\DNS2DFacade as DNS2D;
@@ -31,6 +35,7 @@ class Entity extends Model
     use HasTrackingNumber;
     use HasApiModelBehavior;
     use HasMetaAttributes;
+    use PayloadAccessors;
 
     /**
      * The database table used by the model.
@@ -162,81 +167,81 @@ class Entity extends Model
     }
 
     /**
-     * @var \Illuminate\Database\Eloquent\Relations\BelongsTo
+     * @var BelongsTo
      */
-    public function photo()
+    public function photo(): BelongsTo
     {
         return $this->belongsTo(\Fleetbase\Models\File::class);
     }
 
     /**
-     * @var \Illuminate\Database\Eloquent\Relations\HasMany
+     * @var HasMany
      */
-    public function files()
+    public function files(): HasMany
     {
         return $this->hasMany(\Fleetbase\Models\File::class);
     }
 
     /**
-     * @var \Illuminate\Database\Eloquent\Relations\HasMany
+     * @var HasMany
      */
-    public function proofs()
+    public function proofs(): HasMany
     {
         return $this->hasMany(Proof::class, 'subject_uuid');
     }
 
     /**
-     * @var \Illuminate\Database\Eloquent\Relations\BelongsTo
+     * @var BelongsTo
      */
-    public function destination()
+    public function destination(): BelongsTo
     {
         return $this->belongsTo(Place::class);
     }
 
     /**
-     * @var \Illuminate\Database\Eloquent\Relations\BelongsTo
+     * @var BelongsTo
      */
-    public function payload()
+    public function payload(): BelongsTo
     {
         return $this->belongsTo(Payload::class)->without(['entities']);
     }
 
     /**
-     * @var \Illuminate\Database\Eloquent\Relations\BelongsTo
+     * @var BelongsTo
      */
-    public function supplier()
+    public function supplier(): BelongsTo
     {
         return $this->belongsTo(Vendor::class, 'supplier_uuid', 'uuid');
     }
 
     /**
-     * @var \Illuminate\Database\Eloquent\Relations\BelongsTo
+     * @var BelongsTo
      */
-    public function driver()
+    public function driver(): BelongsTo
     {
         return $this->belongsTo(Driver::class, 'driver_assigned_uuid');
     }
 
     /**
-     * @var \Illuminate\Database\Eloquent\Relations\BelongsTo
+     * @var BelongsTo
      */
-    public function company()
+    public function company(): BelongsTo
     {
         return $this->belongsTo(\Fleetbase\Models\Company::class);
     }
 
     /**
-     * @var \Illuminate\Database\Eloquent\Relations\BelongsTo
+     * @var BelongsTo
      */
-    public function trackingNumber()
+    public function trackingNumber(): BelongsTo
     {
         return $this->belongsTo(TrackingNumber::class);
     }
 
     /**
-     * @var \Illuminate\Database\Eloquent\Relations\MorphTo
+     * @var MorphTo
      */
-    public function customer()
+    public function customer(): MorphTo
     {
         return $this->morphTo(__FUNCTION__, 'customer_type', 'customer_uuid')->withoutGlobalScopes();
     }
@@ -475,34 +480,4 @@ class Entity extends Model
         $this->customer_uuid = $model->uuid;
         $this->customer_type = Utils::getMutationType($model);
     }
-
-    public function getPayload(): ?Payload
-    {
-        $this->load('payload');
-
-        if ($this->payload instanceof Payload) {
-            return $this->payload;
-        }
-
-        if (Str::isUuid($this->payload_uuid)) {
-            return Payload::where('uuid', $this->payload_uuid)->first();
-        }
-
-        return null;
-    }
-
-    public function getTrashedPayload(): ?Payload
-    {
-        $payload = $this->payload()->withoutGlobalScopes()->first();
-
-        if ($payload instanceof Payload) {
-            return $payload;
-        }
-
-        if (Str::isUuid($this->payload_uuid)) {
-            return Payload::where('uuid', $this->payload_uuid)->withoutGlobalScopes()->first();
-        }
-
-        return null;
-    }
 }

package/server/src/Models/Waypoint.php

@@ -6,6 +6,7 @@ use Barryvdh\DomPDF\Facade\Pdf;
 use Fleetbase\Casts\PolymorphicType;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\FleetOps\Traits\HasTrackingNumber;
+use Fleetbase\FleetOps\Traits\PayloadAccessors;
 use Fleetbase\Models\Model;
 use Fleetbase\Traits\HasPublicId;
 use Fleetbase\Traits\HasUuid;
@@ -21,6 +22,7 @@ class Waypoint extends Model
     use HasPublicId;
     use TracksApiCredential;
     use HasTrackingNumber;
+    use PayloadAccessors;
 
     /**
      * The database table used by the model.

package/server/src/Traits/HasTrackingNumber.php

@@ -3,13 +3,16 @@
 namespace Fleetbase\FleetOps\Traits;
 
 use Fleetbase\FleetOps\Flow\Activity;
+use Fleetbase\FleetOps\Models\Order;
 use Fleetbase\FleetOps\Models\Proof;
 use Fleetbase\FleetOps\Models\TrackingNumber;
 use Fleetbase\FleetOps\Models\TrackingStatus;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\LaravelMysqlSpatial\Types\Point;
+use Fleetbase\Support\TemplateString;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
 
 trait HasTrackingNumber
 {
@@ -55,11 +58,11 @@ trait HasTrackingNumber
      */
     public function createActivity(Activity $activity, $location = [], $proof = null): TrackingStatus
     {
-        $status   = $activity->get('status');
-        $details  = $activity->get('details');
-        $code     = $activity->get('code');
-        $proof    = static::resolveProof($proof);
-        $activity = TrackingStatus::create([
+        $status      = $this->resolveActivityTemplateString($activity->get('status', ''));
+        $details     = $this->resolveActivityTemplateString($activity->get('details', ''));
+        $code        = $activity->get('code');
+        $proof       = static::resolveProof($proof);
+        $activity    = TrackingStatus::create([
             'company_uuid'         => data_get($this, 'company_uuid', session('company')),
             'tracking_number_uuid' => $this->tracking_number_uuid,
             'proof_uuid'           => data_get($proof, 'uuid'),
@@ -89,11 +92,11 @@ trait HasTrackingNumber
      */
     public function insertActivity(Activity $activity, $location = [], $proof = null): string
     {
-        $status     = $activity->get('status');
-        $details    = $activity->get('details');
-        $code       = $activity->get('code');
-        $proof      = static::resolveProof($proof);
-        $activityId = TrackingStatus::insertGetUuid([
+        $status      = $this->resolveActivityTemplateString($activity->get('status', ''));
+        $details     = $this->resolveActivityTemplateString($activity->get('details', ''));
+        $code        = $activity->get('code');
+        $proof       = static::resolveProof($proof);
+        $activityId  = TrackingStatus::insertGetUuid([
             'company_uuid'         => data_get($this, 'company_uuid', session('company')),
             'tracking_number_uuid' => $this->tracking_number_uuid,
             'proof_uuid'           => data_get($proof, 'uuid'),
@@ -184,4 +187,55 @@ trait HasTrackingNumber
 
         return null;
     }
+
+    /**
+     * Resolve {placeholders} inside an activity template string.
+     *
+     * Behavior:
+     * - If called on an Order, resolves placeholders against that Order.
+     * - Otherwise, if the model exposes getOrder(), resolves against the returned Order.
+     * - If no suitable target model can be determined, returns the original template unchanged.
+     * - Uses App\Support\TemplateString::resolve() to process placeholders and modifiers
+     *   (e.g., {waypoint.type}, {capitalize waypoint.type}, {order.number | snake | uppercase}).
+     *
+     * Robustness:
+     * - Fast path: if there are no braces, returns early.
+     * - Catches unexpected resolver failures and logs a warning rather than throwing inside UI flows.
+     *
+     * @param string $template the template containing {placeholders}
+     *
+     * @return string the resolved template string, or the original on fallback
+     */
+    private function resolveActivityTemplateString(string $template): string
+    {
+        // Fast path: no placeholders to resolve.
+        if ($template === '' || strpos($template, '{') === false) {
+            return $template;
+        }
+
+        // Determine which model should resolve dynamic properties.
+        // Prefer $this when it's already an Order; otherwise try a getOrder() accessor.
+        $target = $this instanceof Order
+            ? $this
+            : (method_exists($this, 'getOrder') ? $this->getOrder() : null);
+
+        // If we couldn't locate a suitable Eloquent model, leave template unchanged.
+        if (!$target instanceof Model) {
+            return $template;
+        }
+
+        try {
+            // Uses default resolver name 'resolveDynamicProperty' on the target model.
+            return TemplateString::resolve($template, $target, 'resolveDynamicProperty');
+        } catch (\Throwable $e) {
+            // Don't break user flows on template issues; log and return original.
+            Log::warning('Activity template resolution failed.', [
+                'template'  => $template,
+                'target'    => get_class($target),
+                'message'   => $e->getMessage(),
+            ]);
+
+            return $template;
+        }
+    }
 }

package/server/src/Traits/PayloadAccessors.php

@@ -0,0 +1,126 @@
+<?php
+
+namespace Fleetbase\FleetOps\Traits;
+
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Payload;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Support\Str;
+
+/**
+ * PayloadAccessors.
+ *
+ * Drop this trait into the model that has the `payload()` relationship and a `payload_uuid` FK.
+ * It provides:
+ *  - getPayload(): returns the related Payload if present (with global scopes applied)
+ *  - getTrashedPayload(): returns the related Payload without global scopes (e.g., soft-deleted)
+ *  - getOrder(): returns the Order associated through Payload (or null)
+ *
+ * Design notes / best practices:
+ *  - Avoids unconditional eager loading; checks relation cache first via relationLoaded().
+ *  - Uses the relationship query as the primary source of truth, falling back to a direct lookup by UUID.
+ *  - When resolving via direct lookup, caches the relation with setRelation() to prevent repeat queries.
+ *  - Keeps the “ignore global scopes” behavior in a single private helper.
+ *
+ * Assumptions:
+ *  - The host model defines `public function payload(): BelongsTo`.
+ *  - `payload_uuid` stores a UUID, and `Payload`’s primary key is configured for UUIDs (so `find()` works).
+ */
+trait PayloadAccessors
+{
+    /**
+     * Get the associated Payload with global scopes applied.
+     *
+     * @return \App\Models\Payload|null
+     */
+    public function getPayload(): ?Payload
+    {
+        return $this->resolvePayload(ignoreGlobalScopes: false);
+    }
+
+    /**
+     * Get the associated Payload without global scopes (e.g., include soft-deleted).
+     *
+     * @return \App\Models\Payload|null
+     */
+    public function getTrashedPayload(): ?Payload
+    {
+        return $this->resolvePayload(ignoreGlobalScopes: true);
+    }
+
+    /**
+     * Convenience accessor: get the Order via the associated Payload.
+     *
+     * @return \App\Models\Order|null
+     */
+    public function getOrder(): ?Order
+    {
+        // Leverage PHP nullsafe operator; no extra branching needed.
+        return $this->getPayload()?->order;
+    }
+
+    /**
+     * Core resolver for the Payload relation.
+     *
+     * Strategy:
+     *  1) If the relation is already loaded and we are NOT ignoring global scopes, return it.
+     *  2) Otherwise, query via the relationship, optionally disabling global scopes.
+     *  3) If still not found and payload_uuid looks like a UUID, do a direct lookup on Payload,
+     *     optionally disabling global scopes. If found, cache back into the relation.
+     *
+     * @param bool $ignoreGlobalScopes when true, fetch via `withoutGlobalScopes()`
+     *
+     * @return \App\Models\Payload|null
+     */
+    protected function resolvePayload(bool $ignoreGlobalScopes = false): ?Payload
+    {
+        // (1) If relation is already loaded and we accept scoped data, return it.
+        if (!$ignoreGlobalScopes && $this->relationLoaded('payload')) {
+            $related = $this->getRelation('payload');
+            if ($related instanceof Payload) {
+                return $related;
+            }
+        }
+
+        // (2) Query through the relationship (preferred, keeps FK semantics consistent).
+        $relation = $this->payload();
+        $query    = $ignoreGlobalScopes ? $relation->withoutGlobalScopes() : $relation;
+
+        /** @var \App\Models\Payload|null $payload */
+        $payload = $query->first();
+
+        if ($payload instanceof Payload) {
+            // Cache the resolved relation for subsequent access on this model instance.
+            $this->setRelation('payload', $payload);
+
+            return $payload;
+        }
+
+        // (3) Fallback: direct lookup by UUID (useful if relation is not properly hydrated).
+        $uuid = $this->payload_uuid ?? null;
+        if ($uuid && Str::isUuid($uuid)) {
+            $payloadQuery = Payload::query();
+            if ($ignoreGlobalScopes) {
+                $payloadQuery->withoutGlobalScopes();
+            }
+
+            $payload = $payloadQuery->find($uuid); // relies on Payload PK being 'uuid'
+
+            if ($payload instanceof Payload) {
+                // Keep the relation cache consistent for this instance.
+                $this->setRelation('payload', $payload);
+
+                return $payload;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Relationship stub (documentational).
+     * Ensure your model actually defines this in the host model—not strictly required here,
+     * but included as a guide for expected signature.
+     */
+    abstract public function payload(): BelongsTo;
+}

package/server/src/routes.php

@@ -23,7 +23,7 @@ Route::prefix(config('fleetops.api.routing.prefix', null))->namespace('Fleetbase
         */
         $router->group(['prefix' => 'v1', 'middleware' => ['fleetbase.api', Fleetbase\FleetOps\Http\Middleware\TransformLocationMiddleware::class], 'namespace' => 'Api\v1'], function ($router) {
             // drivers routes
-            $router->group(['prefix' => 'drivers', 'middleware' => [Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]], function () use ($router) {
+            $router->group(['prefix' => 'drivers', 'middleware' => []], function () use ($router) {
                 $router->post('register-device', 'DriverController@registerDevice');
                 $router->post('login-with-sms', 'DriverController@loginWithPhone');
                 $router->post('verify-code', 'DriverController@verifyCode');
@@ -74,7 +74,7 @@ Route::prefix(config('fleetops.api.routing.prefix', null))->namespace('Fleetbase
                 $router->delete('{id}', 'FuelReportController@delete');
             });
             // orders routes
-            $router->group(['prefix' => 'orders', 'middleware' => [Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]], function () use ($router) {
+            $router->group(['prefix' => 'orders', 'middleware' => []], function () use ($router) {
                 $router->post('/', 'OrderController@create');
                 $router->get('/', 'OrderController@query');
                 $router->get('{id}', 'OrderController@find');
@@ -251,8 +251,8 @@ Route::prefix(config('fleetops.api.routing.prefix', null))->namespace('Fleetbase
                         $router->fleetbaseRoutes(
                             'contacts',
                             function ($router, $controller) {
-                                $router->match(['get', 'post'], 'export', $controller('export'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
-                                $router->post('import', $controller('import'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
+                                $router->match(['get', 'post'], 'export', $controller('export'));
+                                $router->post('import', $controller('import'));
                                 $router->get('facilitators/{id}', $controller('getAsFacilitator'));
                                 $router->get('customers/{id}', $controller('getAsCustomer'));
                                 $router->delete('bulk-delete', $controller('bulkDelete'));
@@ -261,11 +261,11 @@ Route::prefix(config('fleetops.api.routing.prefix', null))->namespace('Fleetbase
                         $router->fleetbaseRoutes(
                             'drivers',
                             function ($router, $controller) {
-                                $router->get('statuses', $controller('statuses'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
-                                $router->get('avatars', $controller('avatars'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
-                                $router->match(['get', 'post'], 'export', $controller('export'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
+                                $router->get('statuses', $controller('statuses'));
+                                $router->get('avatars', $controller('avatars'));
+                                $router->match(['get', 'post'], 'export', $controller('export'));
                                 $router->delete('bulk-delete', $controller('bulkDelete'));
-                                $router->post('import', $controller('import'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
+                                $router->post('import', $controller('import'));
                             }
                         );
                         $router->fleetbaseRoutes('entities');
@@ -276,31 +276,31 @@ Route::prefix(config('fleetops.api.routing.prefix', null))->namespace('Fleetbase
                                 $router->post('remove-driver', $controller('removeDriver'));
                                 $router->post('assign-vehicle', $controller('assignVehicle'));
                                 $router->post('remove-vehicle', $controller('removeVehicle'));
-                                $router->match(['get', 'post'], 'export', $controller('export'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
-                                $router->post('import', $controller('import'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
+                                $router->match(['get', 'post'], 'export', $controller('export'));
+                                $router->post('import', $controller('import'));
                                 $router->delete('bulk-delete', $controller('bulkDelete'));
                             }
                         );
                         $router->fleetbaseRoutes(
                             'fuel-reports',
                             function ($router, $controller) {
-                                $router->match(['get', 'post'], 'export', $controller('export'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
-                                $router->post('import', $controller('import'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
+                                $router->match(['get', 'post'], 'export', $controller('export'));
+                                $router->post('import', $controller('import'));
                                 $router->delete('bulk-delete', $controller('bulkDelete'));
                             }
                         );
                         $router->fleetbaseRoutes(
                             'issues',
                             function ($router, $controller) {
-                                $router->match(['get', 'post'], 'export', $controller('export'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
-                                $router->post('import', $controller('import'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
+                                $router->match(['get', 'post'], 'export', $controller('export'));
+                                $router->post('import', $controller('import'));
                                 $router->delete('bulk-delete', $controller('bulkDelete'));
                             }
                         );
                         $router->fleetbaseRoutes(
                             'integrated-vendors',
                             function ($router, $controller) {
-                                $router->get('supported', $controller('getSupported'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
+                                $router->get('supported', $controller('getSupported'));
                                 $router->delete('bulk-delete', $controller('bulkDelete'));
                             }
                         );
@@ -309,12 +309,12 @@ Route::prefix(config('fleetops.api.routing.prefix', null))->namespace('Fleetbase
                             function ($router, $controller) {
                                 $router->get('default-config', $controller('getDefaultOrderConfig'));
                                 $router->get('search', $controller('search'));
-                                $router->get('statuses', $controller('statuses'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
+                                $router->get('statuses', $controller('statuses'));
                                 $router->get('types', $controller('types'));
                                 $router->get('label/{id}', $controller('label'));
-                                $router->get('next-activity/{id}', $controller('nextActivity'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
-                                $router->get('{id}/tracker', 'OrderController@trackerInfo')->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
-                                $router->get('{id}/eta', 'OrderController@waypointEtas')->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
+                                $router->get('next-activity/{id}', $controller('nextActivity'));
+                                $router->get('{id}/tracker', 'OrderController@trackerInfo');
+                                $router->get('{id}/eta', 'OrderController@waypointEtas');
                                 $router->post('process-imports', $controller('importFromFiles'));
                                 $router->patch('route/{id}', $controller('editOrderRoute'));
                                 $router->patch('update-activity/{id}', $controller('updateActivity'));
@@ -326,7 +326,7 @@ Route::prefix(config('fleetops.api.routing.prefix', null))->namespace('Fleetbase
                                 $router->patch('dispatch', $controller('dispatchOrder'));
                                 $router->patch('start', $controller('start'));
                                 $router->delete('bulk-delete', $controller('bulkDelete'));
-                                $router->match(['get', 'post'], 'export', $controller('export'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
+                                $router->match(['get', 'post'], 'export', $controller('export'));
                             }
                         );
                         $router->fleetbaseRoutes('order-configs');
@@ -334,12 +334,12 @@ Route::prefix(config('fleetops.api.routing.prefix', null))->namespace('Fleetbase
                         $router->fleetbaseRoutes(
                             'places',
                             function ($router, $controller) {
-                                $router->get('search', $controller('search'))->middleware(['cache.headers:private;max_age=3600', Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
-                                $router->get('lookup', $controller('geocode'))->middleware(['cache.headers:private;max_age=3600', Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
+                                $router->get('search', $controller('search'))->middleware(['cache.headers:private;max_age=3600']);
+                                $router->get('lookup', $controller('geocode'))->middleware(['cache.headers:private;max_age=3600']);
                                 $router->get('avatars', $controller('avatars'));
                                 $router->match(['get', 'post'], 'export', $controller('export'));
                                 $router->delete('bulk-delete', $controller('bulkDelete'));
-                                $router->post('import', $controller('import'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
+                                $router->post('import', $controller('import'));
                             }
                         );
                         $router->fleetbaseRoutes('proofs');
@@ -348,7 +348,7 @@ Route::prefix(config('fleetops.api.routing.prefix', null))->namespace('Fleetbase
                         $router->fleetbaseRoutes(
                             'service-areas',
                             function ($router, $controller) {
-                                $router->match(['get', 'post'], 'export', $controller('export'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
+                                $router->match(['get', 'post'], 'export', $controller('export'));
                                 $router->delete('bulk-delete', $controller('bulkDelete'));
                             }
                         );
@@ -366,8 +366,8 @@ Route::prefix(config('fleetops.api.routing.prefix', null))->namespace('Fleetbase
                             function ($router, $controller) {
                                 $router->delete('bulk-delete', $controller('bulkDelete'));
                                 $router->get('for-route', $controller('getServicesForRoute'));
-                                $router->match(['get', 'post'], 'export', $controller('export'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
-                                $router->get('for-route', $controller('getServicesForRoute'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
+                                $router->match(['get', 'post'], 'export', $controller('export'));
+                                $router->get('for-route', $controller('getServicesForRoute'));
                             }
                         );
                         $router->fleetbaseRoutes('tracking-numbers');
@@ -375,10 +375,10 @@ Route::prefix(config('fleetops.api.routing.prefix', null))->namespace('Fleetbase
                         $router->fleetbaseRoutes(
                             'vehicles',
                             function ($router, $controller) {
-                                $router->get('statuses', $controller('statuses'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
-                                $router->get('avatars', $controller('avatars'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
-                                $router->match(['get', 'post'], 'export', $controller('export'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
-                                $router->post('import', $controller('import'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
+                                $router->get('statuses', $controller('statuses'));
+                                $router->get('avatars', $controller('avatars'));
+                                $router->match(['get', 'post'], 'export', $controller('export'));
+                                $router->post('import', $controller('import'));
                                 $router->delete('bulk-delete', $controller('bulkDelete'));
                             }
                         );
@@ -386,14 +386,14 @@ Route::prefix(config('fleetops.api.routing.prefix', null))->namespace('Fleetbase
                         $router->fleetbaseRoutes(
                             'vendors',
                             function ($router, $controller) {
-                                $router->get('statuses', $controller('statuses'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
-                                $router->match(['get', 'post'], 'export', $controller('export'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
+                                $router->get('statuses', $controller('statuses'));
+                                $router->match(['get', 'post'], 'export', $controller('export'));
                                 $router->get('facilitators/{id}', $controller('getAsFacilitator'));
                                 $router->get('customers/{id}', $controller('getAsCustomer'));
                                 $router->post('{id}/assign-driver', $controller('assignDriver'));
                                 $router->post('{id}/remove-driver', $controller('removeDriver'));
                                 $router->delete('bulk-delete', $controller('bulkDelete'));
-                                $router->post('import', $controller('import'))->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
+                                $router->post('import', $controller('import'));
                             }
                         );
                         $router->group(
@@ -417,7 +417,7 @@ Route::prefix(config('fleetops.api.routing.prefix', null))->namespace('Fleetbase
                             }
                         );
                         $router->group(
-                            ['prefix' => 'geocoder', ['middleware' => [Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]]],
+                            ['prefix' => 'geocoder', ['middleware' => []]],
                             function ($router) {
                                 $router->get('reverse', 'GeocoderController@reverse');
                                 $router->get('query', 'GeocoderController@geocode');
@@ -427,12 +427,12 @@ Route::prefix(config('fleetops.api.routing.prefix', null))->namespace('Fleetbase
                             ['prefix' => 'fleet-ops'],
                             function ($router) {
                                 $router->group(
-                                    ['prefix' => 'payments', ['middleware' => [Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]]],
+                                    ['prefix' => 'payments', ['middleware' => []]],
                                     function () use ($router) {
-                                        $router->post('stripe-account', 'PaymentController@getStripeAccount')->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
-                                        $router->post('stripe-account-session', 'PaymentController@getStripeAccountSession')->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
-                                        $router->get('has-stripe-connect-account', 'PaymentController@hasStripeConnectAccount')->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
-                                        $router->get('payments-received', 'PaymentController@getCompanyReceivedPayments')->middleware([Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]);
+                                        $router->post('stripe-account', 'PaymentController@getStripeAccount');
+                                        $router->post('stripe-account-session', 'PaymentController@getStripeAccountSession');
+                                        $router->get('has-stripe-connect-account', 'PaymentController@hasStripeConnectAccount');
+                                        $router->get('payments-received', 'PaymentController@getCompanyReceivedPayments');
                                     }
                                 );
 
@@ -455,7 +455,7 @@ Route::prefix(config('fleetops.api.routing.prefix', null))->namespace('Fleetbase
                                     }
                                 );
                                 $router->group(
-                                    ['prefix' => 'settings', 'middleware' => [Spatie\ResponseCache\Middlewares\DoNotCacheResponse::class]],
+                                    ['prefix' => 'settings', 'middleware' => []],
                                     function ($router) {
                                         $router->get('customer-payments-config', 'SettingController@getCustomerPortalPaymentConfig');
                                         $router->post('customer-payments-config', 'SettingController@saveCustomerPortalPaymentConfig');