@fleetbase/fleetops-engine 0.6.16 → 0.6.17

package/composer.json

@@ -1,6 +1,6 @@
 {
     "name": "fleetbase/fleetops-api",
-    "version": "0.6.16",
+    "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.16",
+    "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.16",
+    "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/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;
+}