@fleetbase/fleetops-engine 0.6.70 → 0.6.72

package/server/src/Models/Order.php

@@ -8,8 +8,11 @@ use Fleetbase\FleetOps\Events\OrderCanceled;
 use Fleetbase\FleetOps\Events\OrderCompleted;
 use Fleetbase\FleetOps\Events\OrderDispatched;
 use Fleetbase\FleetOps\Events\OrderDriverAssigned;
+use Fleetbase\FleetOps\Events\OrderDriverUnassigned;
 use Fleetbase\FleetOps\Flow\Activity;
+use Fleetbase\FleetOps\Notifications\OrderUnassigned;
 use Fleetbase\FleetOps\Support\LabelPdf;
+use Fleetbase\FleetOps\Support\OrderEditPolicy;
 use Fleetbase\FleetOps\Support\OrderTracker;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\FleetOps\Traits\HasTrackingNumber;
@@ -35,6 +38,7 @@ use Illuminate\Database\Eloquent\Relations\MorphTo;
 use Illuminate\Database\Eloquent\Relations\Relation;
 use Illuminate\Support\Carbon;
 use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\Log;
 use Illuminate\Support\Str;
 use Spatie\Activitylog\LogOptions;
 use Spatie\Activitylog\Traits\LogsActivity;
@@ -196,6 +200,38 @@ class Order extends Model
      */
     protected $with = [];
 
+    /**
+     * Relation paths and tables the cached order lists embed, so a write to any
+     * of them invalidates those lists (fleetbase/core-api#301).
+     *
+     * They mirror OrderFilter::queryForInternal()'s eager loads and whereHas
+     * membership, the payload relation's own `with`, Payload's `$with` and the
+     * public query's loads. customer and facilitator are morphTo relations, so
+     * their tables (contacts, vendors, integrated_vendors) are named instead;
+     * a vendor loads its place, which payload.pickup already covers. files
+     * (customer photo, vendor logo) is left out: every upload writes it, and a
+     * new photo is set by writing the contact's or vendor's own row.
+     *
+     * @var string[]
+     */
+    protected $apiCacheDependencies = [
+        'payload',
+        'payload.pickup',
+        'payload.dropoff',
+        'payload.return',
+        'payload.entities',
+        'payload.waypoints',
+        'payload.firstWaypointMarker.place',
+        'payload.lastWaypointMarker.place',
+        'trackingNumber',
+        'trackingStatuses',
+        'driverAssigned',
+        'vehicleAssigned',
+        'contacts',
+        'vendors',
+        'integrated_vendors',
+    ];
+
     /**
      * The attributes that should be cast to native types.
      *
@@ -244,6 +280,16 @@ class Order extends Model
         '_key',
     ];
 
+    /**
+     * Set for one save: the driver assignment being saved sends no assignment notification.
+     */
+    public bool $silentDriverAssignment = false;
+
+    /**
+     * Set for one save: the driver taken off the order is not sent an unassigned push (they declined it themselves).
+     */
+    public bool $quietDriverUnassignment = false;
+
     /**
      * Enforce a morph map.
      */
@@ -263,6 +309,31 @@ class Order extends Model
         );
     }
 
+    /**
+     * Bulk removal deletes the matched orders one at a time instead of with a single
+     * query, so the "deleted" event fires for each and OrderObserver cascades the soft
+     * delete to the order's payload, entities and tracking data. Matching, the tenant
+     * constraint (GHSA-3wj9-hh56-7fw7) and the returned count follow core-api's version.
+     */
+    public function bulkRemove($ids = [])
+    {
+        $orders = static::where(function ($query) use ($ids) {
+            $query->whereIn($this->getQualifiedKeyName(), $ids)->orWhereIn($this->getQualifiedPublicId(), $ids);
+        });
+
+        // Tenant constraint: never delete another company's orders.
+        $companyUuid = session('company');
+        if ($companyUuid) {
+            $orders->where($this->qualifyColumn('company_uuid'), $companyUuid);
+        }
+
+        $orders = $orders->get();
+        $orders->each->delete();
+        $this->invalidateApiCacheOnChange();
+
+        return $orders->count();
+    }
+
     /**
      * Get the activity log options for the model.
      */
@@ -1034,6 +1105,7 @@ class Order extends Model
         $route->save();
 
         $this->updateQuietly(['route_uuid' => $route->uuid]);
+        $this->invalidateApiCache();
 
         return $this;
     }
@@ -1169,6 +1241,7 @@ class Order extends Model
         ]);
 
         if ($attached) {
+            $this->invalidateApiCache();
             $this->setRelation('purchaseRate', $purchaseRate);
 
             if ($purchaseRate->transaction_uuid) {
@@ -1231,6 +1304,7 @@ class Order extends Model
             ]);
 
             $this->updateQuietly(['transaction_uuid' => $transaction->uuid]);
+            $this->invalidateApiCache();
         } catch (\Throwable $e) {
         }
 
@@ -1270,6 +1344,7 @@ class Order extends Model
         if ($save) {
             $this->saveQuietly();
             $this->flushAttributesCache();
+            $this->invalidateApiCache();
         }
 
         dispatch(fn () => event(new OrderDispatched($this)))->afterCommit();
@@ -1308,6 +1383,29 @@ class Order extends Model
         return $this;
     }
 
+    /**
+     * Determine whether the order is still waiting to be dispatched.
+     *
+     * A deferred dispatch, such as the queued finalize job for orders created with
+     * `dispatch: true`, can run after the order was already dispatched or started
+     * through another path. Dispatching it then would move the status back to
+     * "dispatched", so only an order that still sits at its initial status with no
+     * dispatch or start recorded qualifies.
+     */
+    public function isAwaitingDispatch(): bool
+    {
+        if ($this->dispatched || $this->dispatched_at || $this->started || $this->started_at) {
+            return false;
+        }
+
+        $status = $this->status ?? 'created';
+        if ($status !== 'created' && $status !== $this->config()?->getInitialStatusCode()) {
+            return false;
+        }
+
+        return !$this->hasDispatchedStatus();
+    }
+
     /**
      * Dispatches the order only if it hasn't been dispatched yet.
      * A check is performed before dispatching the order.
@@ -1346,10 +1444,33 @@ class Order extends Model
      */
     public function cancel()
     {
-        $this->status = 'canceled';
+        return $this->cancelWithReason(null);
+    }
 
+    /**
+     * Cancels the order, recording why.
+     *
+     * The reason becomes the details of the canceled tracking status and is carried on
+     * the OrderCanceled event's activity, which the canceled notifications read.
+     *
+     * @return mixed the result of the OrderCanceled event
+     */
+    public function cancelWithReason(?string $reason = null)
+    {
+        // The canceled activity comes from the order config, which may define its own code.
         $this->loadMissing('orderConfig');
-        $canceledActivity = $this->orderConfig->getCanceledActivity();
+        $orderConfig      = $this->orderConfig ?? $this->config();
+        $canceledActivity = $orderConfig->getCanceledActivity();
+
+        // A reason given for the cancellation becomes the canceled status details, which
+        // the canceled notifications read. The config's activity itself is left untouched.
+        $reason         = is_string($reason) ? trim($reason) : null;
+        $reasonActivity = null;
+        if ($reason !== null && $reason !== '' && $canceledActivity instanceof Activity) {
+            $canceledActivity = $reasonActivity = (clone $canceledActivity)->set('details', $reason);
+        }
+
+        $this->status     = $canceledActivity->code ?? 'canceled';
         $this->updateActivity($canceledActivity);
 
         if ($this->isIntegratedVendorOrder()) {
@@ -1360,7 +1481,13 @@ class Order extends Model
             }
         }
 
-        return dispatch(fn () => event(new OrderCanceled($this)))->afterCommit();
+        // The event carries the activity when a reason was given, so the canceled
+        // notifications (which read the activity details) include it.
+        return dispatch(function () use ($reasonActivity) {
+            $event           = new OrderCanceled($this);
+            $event->activity = $reasonActivity;
+            event($event);
+        })->afterCommit();
     }
 
     /**
@@ -1376,6 +1503,52 @@ class Order extends Model
         }
     }
 
+    /**
+     * Tell a driver the order was taken off them: broadcasts `order.driver_unassigned`
+     * on their channels and pushes `{ type: "order_unassigned", id }` to their devices.
+     * The order is cleared as the driver's current job.
+     *
+     * @param Driver|string|null $driver the driver (or driver uuid) removed from the order
+     */
+    public function notifyDriverUnassigned($driver): bool
+    {
+        if (is_string($driver)) {
+            $driver = Driver::where('uuid', $driver)->withoutGlobalScopes()->first();
+        }
+
+        if (!$driver instanceof Driver) {
+            return false;
+        }
+
+        if ($driver->current_job_uuid && $driver->current_job_uuid === $this->uuid) {
+            $driver->forceFill(['current_job_uuid' => null])->saveQuietly();
+        }
+
+        try {
+            event(new OrderDriverUnassigned($this, $driver));
+        } catch (\Throwable $exception) {
+            Log::warning('Unable to broadcast order.driver_unassigned', ['order' => $this->public_id, 'error' => $exception->getMessage()]);
+        }
+
+        if (!$this->quietDriverUnassignment) {
+            try {
+                $driver->notify(new OrderUnassigned($this));
+            } catch (\Throwable $exception) {
+                Log::warning('Unable to notify driver of unassignment', ['order' => $this->public_id, 'error' => $exception->getMessage()]);
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * The edit policy for the order at its current status.
+     */
+    public function editPolicy(): OrderEditPolicy
+    {
+        return OrderEditPolicy::for($this);
+    }
+
     /**
      * Updates the activity of the order.
      * Updates the order status and inserts a new activity based on the provided activity details.
@@ -1633,7 +1806,7 @@ class Order extends Model
                         return $this;
                     }
 
-                    return $this->assignDriver($driver);
+                    return $this->assignDriver($driver, $silent);
                 }
 
                 throw new \Exception('Invalid driver provided for assignment!');
@@ -1646,12 +1819,16 @@ class Order extends Model
             $this->setRelation('driverAssigned', $driver);
         }
 
-        if (!$silent) {
-            $this->notifyDriverAssigned();
+        // The order observer sends OrderDriverAssigned once the assignment is saved
+        // (and tells a replaced driver they were unassigned), so it is not fired here
+        // as well. A silent assignment is flagged for that one save.
+        $this->silentDriverAssignment = (bool) $silent;
+        try {
+            $this->save();
+        } finally {
+            $this->silentDriverAssignment = false;
         }
 
-        $this->save();
-
         return $this;
     }
 
@@ -1671,7 +1848,10 @@ class Order extends Model
                 $driverAssigned = Driver::where('uuid', $this->driver_assigned_uuid)->first();
             }
 
-            if ($driverAssigned instanceof Driver) {
+            // A driver that has never reported a position still carries the
+            // POINT(0 0) placeholder it was created with. Measuring from there
+            // puts the origin at null island, so fall back to the pickup.
+            if ($driverAssigned instanceof Driver && static::isKnownPosition($driverAssigned->location)) {
                 return $driverAssigned->location;
             }
         }
@@ -1702,6 +1882,16 @@ class Order extends Model
         return $destination ? $destination->location : null;
     }
 
+    /**
+     * Determines whether a position is a real, resolved location rather than
+     * missing or the POINT(0 0) placeholder stored for drivers that have not
+     * reported a position yet and for places that failed to geocode.
+     */
+    public static function isKnownPosition($position): bool
+    {
+        return $position instanceof Point && ($position->getLat() != 0.0 || $position->getLng() != 0.0);
+    }
+
     /**
      * Sets the preliminary distance and time for the order.
      * Uses a utility method to calculate the distance and time between the current origin and destination positions.
@@ -1713,13 +1903,14 @@ class Order extends Model
         $origin      = $this->getCurrentOriginPosition();
         $destination = $this->getDestinationPosition();
 
-        if ($origin === null || $destination === null) {
+        if (!static::isKnownPosition($origin) || !static::isKnownPosition($destination)) {
             return $this;
         }
 
         $matrix = Utils::getPreliminaryDistanceMatrix($origin, $destination);
 
         $this->updateQuietly(['distance' => $matrix->distance, 'time' => $matrix->time]);
+        $this->invalidateApiCache();
 
         return $this;
     }
@@ -1735,7 +1926,7 @@ class Order extends Model
         $origin      = $this->getCurrentOriginPosition();
         $destination = $this->getDestinationPosition();
 
-        if (!$origin || !$destination) {
+        if (!static::isKnownPosition($origin) || !static::isKnownPosition($destination)) {
             return $this;
         }
 
@@ -1757,6 +1948,7 @@ class Order extends Model
                 'distance' => $matrix->distance,
                 'time'     => $matrix->time,
             ]);
+            $this->invalidateApiCache();
         }
 
         return $this;
@@ -1783,6 +1975,37 @@ class Order extends Model
         return (int) Utils::get($this, 'adhoc_distance', Utils::get($this, 'company.options.fleetops.adhoc_distance', 6000));
     }
 
+    /**
+     * Returns the initial tracking status for a newly created order.
+     *
+     * Used by the tracking number on creation. Orders whose config defines its own
+     * lifecycle start at the configured initial activity instead of `created`.
+     *
+     * @return array|null ['code', 'status', 'details'] or null to use the default created status
+     */
+    public function getInitialTrackingStatus(): ?array
+    {
+        if (!$this->order_config_uuid) {
+            return null;
+        }
+
+        $orderConfig = OrderConfig::where('uuid', $this->order_config_uuid)->first();
+        if (!$orderConfig || !$orderConfig->hasConfiguredLifecycle()) {
+            return null;
+        }
+
+        $activity = $orderConfig->getInitialActivity();
+        if (!$activity) {
+            return null;
+        }
+
+        return [
+            'code'    => $activity->code,
+            'status'  => $this->resolveActivityTemplateString((string) $activity->get('status', '')),
+            'details' => $this->resolveActivityTemplateString((string) $activity->get('details', '')),
+        ];
+    }
+
     /**
      * Retrieves the OrderConfig associated with this order.
      *

package/server/src/Models/OrderConfig.php

@@ -380,6 +380,125 @@ class OrderConfig extends Model
         return $this->activities()->firstWhere('code', $code);
     }
 
+    /**
+     * Returns the configured lifecycle semantics stored under `meta.lifecycle`.
+     *
+     * A configured lifecycle is opt-in. When absent the default dispatch lifecycle
+     * (created -> dispatched -> ... -> completed / canceled) applies unchanged.
+     *
+     * Supported keys:
+     * - `initial` (string)            activity code new orders start at
+     * - `completed` (string)          activity code that completes an order
+     * - `canceled` (string)           activity code used when an order is canceled
+     * - `terminal` (string[])         activity codes after which no transition is allowed
+     * - `dispatch` (bool)             false disables dispatch for orders using this config
+     * - `strict_transitions` (bool)   true only allows moving to a configured child activity
+     */
+    public function lifecycle(): array
+    {
+        $lifecycle = data_get($this->meta, 'lifecycle');
+
+        return is_array($lifecycle) ? $lifecycle : [];
+    }
+
+    /**
+     * Determines if this config defines its own lifecycle semantics.
+     */
+    public function hasConfiguredLifecycle(): bool
+    {
+        return !empty($this->lifecycle());
+    }
+
+    /**
+     * Returns the activity new orders using this config start at.
+     *
+     * Without a configured lifecycle this is the `created` activity, if present in the flow.
+     */
+    public function getInitialActivity(): ?Activity
+    {
+        $initialCode = data_get($this->lifecycle(), 'initial');
+        if ($initialCode) {
+            return $this->getActivityByCode($initialCode);
+        }
+
+        return $this->getCreatedActivity();
+    }
+
+    /**
+     * Returns the status code new orders using this config start at.
+     */
+    public function getInitialStatusCode(): string
+    {
+        return data_get($this->lifecycle(), 'initial') ?: 'created';
+    }
+
+    /**
+     * Determines if orders using this config may be dispatched.
+     */
+    public function allowsDispatch(): bool
+    {
+        $dispatch = data_get($this->lifecycle(), 'dispatch', true);
+
+        return !in_array($dispatch, [false, 'false', 0, '0'], true);
+    }
+
+    /**
+     * Determines if activity updates must follow the configured flow graph.
+     */
+    public function hasStrictTransitions(): bool
+    {
+        return (bool) data_get($this->lifecycle(), 'strict_transitions', false);
+    }
+
+    /**
+     * Returns the terminal activity codes of this config.
+     */
+    public function getTerminalActivityCodes(): array
+    {
+        if (!$this->hasConfiguredLifecycle()) {
+            return ['completed', 'canceled'];
+        }
+
+        $terminal = data_get($this->lifecycle(), 'terminal', []);
+        $terminal = is_array($terminal) ? $terminal : [];
+        foreach (['completed', 'canceled'] as $semantic) {
+            $code = data_get($this->lifecycle(), $semantic);
+            if ($code) {
+                $terminal[] = $code;
+            }
+        }
+
+        return array_values(array_unique($terminal));
+    }
+
+    /**
+     * Determines if the given activity code is terminal for this config.
+     */
+    public function isTerminalActivityCode(?string $code): bool
+    {
+        return $code !== null && in_array($code, $this->getTerminalActivityCodes(), true);
+    }
+
+    /**
+     * Determines if the configured flow permits moving from one activity code to another.
+     *
+     * Only the configured graph is consulted: the target must be listed as a child of the
+     * source activity, and terminal activities permit no further transition.
+     */
+    public function canTransition(?string $fromCode, string $toCode): bool
+    {
+        if ($fromCode === null || $this->isTerminalActivityCode($fromCode)) {
+            return false;
+        }
+
+        $from = $this->getActivityByCode($fromCode);
+        if (!$from) {
+            return false;
+        }
+
+        return $from->children()->contains(fn ($activity) => $activity->code === $toCode);
+    }
+
     /**
      * Creates an Activity instance representing a canceled order.
      *
@@ -391,6 +510,11 @@ class OrderConfig extends Model
      */
     public function getCanceledActivity()
     {
+        $configuredCode = data_get($this->lifecycle(), 'canceled');
+        if ($configuredCode && ($configuredActivity = $this->getActivityByCode($configuredCode))) {
+            return $configuredActivity;
+        }
+
         $canceledActivity = $this->activities()->firstWhere('code', 'canceled');
         if ($canceledActivity) {
             return $canceledActivity;
@@ -416,6 +540,11 @@ class OrderConfig extends Model
      */
     public function getCompletedActivity()
     {
+        $configuredCode = data_get($this->lifecycle(), 'completed');
+        if ($configuredCode && ($configuredActivity = $this->getActivityByCode($configuredCode))) {
+            return $configuredActivity;
+        }
+
         $completedActivity = $this->activities()->firstWhere('code', 'completed');
         if ($completedActivity) {
             return $completedActivity;