@fleetbase/fleetops-engine 0.6.70 → 0.6.72

package/server/src/Console/Commands/PruneTelematicsData.php

@@ -2,6 +2,7 @@
 
 namespace Fleetbase\FleetOps\Console\Commands;
 
+use Carbon\Carbon;
 use Fleetbase\FleetOps\Support\Telematics\Retention\RetentionPolicy;
 use Illuminate\Console\Command;
 use Illuminate\Support\Collection;
@@ -21,6 +22,9 @@ class PruneTelematicsData extends Command
 
     public const LOCK = 'fleetops:prune-telematics-data';
 
+    /** Cache key prefix for the per-scope compaction watermark (see pruneDeviceEvents). */
+    public const WATERMARK_PREFIX = 'fleetops:prune-telematics-data:compacted:';
+
     protected $signature = 'fleetops:prune-telematics-data
         {--company= : Only prune data for this company (uuid or public id)}
         {--orphans-only : Only prune data without an existing company or connection}
@@ -36,6 +40,9 @@ class PruneTelematicsData extends Command
     protected int $maxBatches = 50;
     protected bool $dryRun    = false;
 
+    /** table => company uuids present in that table whose company no longer exists; resolved once per run. */
+    protected array $orphanCompaniesByTable = [];
+
     public function handle(): int
     {
         $tables = $this->requestedTables();
@@ -142,7 +149,7 @@ class PruneTelematicsData extends Command
         }
         $inbox = $telematics ? fn ($query) => $query->whereIn('telematic_uuid', $telematics) : null;
 
-        return $this->prune($rows, $inbox, $policy, $tables);
+        return $this->prune($rows, $inbox, $policy, $tables, $companyUuid);
     }
 
     /**
@@ -150,9 +157,7 @@ class PruneTelematicsData extends Command
      */
     protected function pruneOrphans(RetentionPolicy $policy, array $tables): array
     {
-        $rows = fn ($query) => $query->where(function ($where) {
-            $where->whereNull('company_uuid')->orWhereNotIn('company_uuid', DB::table('companies')->select('uuid'));
-        });
+        $rows  = fn ($query) => $this->scopeOrphanRows($query);
         $inbox = fn ($query) => $query->whereNotExists(function ($connections) use ($query) {
             $connections->selectRaw('1')
                 ->from('telematics')
@@ -160,14 +165,46 @@ class PruneTelematicsData extends Command
                 ->whereColumn('telematics.uuid', $query->from . '.telematic_uuid');
         });
 
-        return $this->prune($rows, $inbox, $policy, $tables);
+        return $this->prune($rows, $inbox, $policy, $tables, 'orphans');
+    }
+
+    /**
+     * Rows without a company, plus rows whose company uuid no longer exists. The gone
+     * companies are resolved once per table from the distinct company uuids it holds, so
+     * every batch ranges over the (company_uuid, created_at) index instead of evaluating
+     * a NOT IN subquery against every row.
+     */
+    protected function scopeOrphanRows($query)
+    {
+        $table = $query->from;
+        $gone  = $this->orphanCompaniesByTable[$table] ??= $this->orphanCompanies($table);
+
+        return $query->where(function ($where) use ($gone) {
+            $where->whereNull('company_uuid');
+            if ($gone !== []) {
+                $where->orWhereIn('company_uuid', $gone);
+            }
+        });
+    }
+
+    /**
+     * @return string[]
+     */
+    protected function orphanCompanies(string $table): array
+    {
+        return DB::table($table)
+            ->whereNotNull('company_uuid')
+            ->whereNotIn('company_uuid', DB::table('companies')->select('uuid'))
+            ->groupBy('company_uuid')
+            ->pluck('company_uuid')
+            ->all();
     }
 
-    protected function prune(\Closure $rows, ?\Closure $inbox, RetentionPolicy $policy, array $tables): array
+    protected function prune(\Closure $rows, ?\Closure $inbox, RetentionPolicy $policy, array $tables, string $scope): array
     {
         $stats = $this->emptyStats();
         if (in_array('device_events', $tables, true)) {
-            $stats['tables']['device_events'] = $this->pruneDeviceEvents($rows, $policy);
+            $stats['tables']['device_events'] = $this->pruneDeviceEvents($rows, $policy, $scope);
         }
         if (in_array('positions', $tables, true)) {
             $stats['tables']['positions'] = $this->prunePositions($rows, $policy);
@@ -188,40 +225,69 @@ class PruneTelematicsData extends Command
         return $stats;
     }
 
-    protected function pruneDeviceEvents(\Closure $rows, RetentionPolicy $policy): array
+    protected function pruneDeviceEvents(\Closure $rows, RetentionPolicy $policy, string $scope): array
     {
         $stats  = $this->emptyTableStats();
         $cutoff = $policy->cutoff('event_retention_days');
         // Soft-deleted events only grow the table; purge them regardless of age.
-        $this->deleteInBatches('device_events', 'id', fn ($query) => $rows($query)->whereNotNull('deleted_at'), $stats);
+        $this->deleteInBatches('device_events', 'id', fn ($query) => $rows($query)->whereNotNull('deleted_at'), $stats, 'deleted_at');
         if ($cutoff) {
-            $this->deleteInBatches('device_events', 'id', fn ($query) => $rows($query)->where('created_at', '<', $cutoff->toDateTimeString()), $stats);
+            $this->deleteInBatches('device_events', 'id', fn ($query) => $rows($query)->where('created_at', '<', $cutoff->toDateTimeString()), $stats, 'created_at');
         }
         if ($policy->compactsEvents() && ($compactAt = $policy->cutoff('event_compact_after_days'))) {
             // Keep the event (type, severity, location, normalized data) but drop the raw provider blobs.
             // Rows past the delete cutoff are left to the delete sweep rather than rewritten first.
-            $this->updateInBatches(
+            // Everything older than the watermark was compacted by an earlier complete sweep, so
+            // only the rows that aged into the window since then are visited; without it every
+            // run re-scanned the whole history looking for blobs that were already gone.
+            $watermark = $this->compactionWatermark($scope);
+            $since     = $cutoff && (!$watermark || $cutoff->greaterThan($watermark)) ? $cutoff : $watermark;
+            $completed = $this->updateInBatches(
                 'device_events',
                 'id',
-                function ($query) use ($rows, $cutoff, $compactAt) {
+                function ($query) use ($rows, $since, $compactAt) {
                     $query = $rows($query)->where('created_at', '<', $compactAt->toDateTimeString())->where(fn ($where) => $where->whereNotNull('payload')->orWhereNotNull('meta'));
 
-                    return $cutoff ? $query->where('created_at', '>=', $cutoff->toDateTimeString()) : $query;
+                    return $since ? $query->where('created_at', '>=', $since->toDateTimeString()) : $query;
                 },
                 ['payload' => null, 'meta' => null],
-                $stats
+                $stats,
+                'created_at'
             );
+            if ($completed && !$this->dryRun) {
+                $this->rememberCompactionWatermark($scope, $compactAt);
+            }
         }
 
         return $stats;
     }
 
+    protected function compactionWatermark(string $scope): ?Carbon
+    {
+        try {
+            $value = Cache::get(self::WATERMARK_PREFIX . $scope);
+        } catch (\Throwable) {
+            return null;
+        }
+
+        return $value ? Carbon::parse($value) : null;
+    }
+
+    protected function rememberCompactionWatermark(string $scope, Carbon $compactedBefore): void
+    {
+        try {
+            Cache::forever(self::WATERMARK_PREFIX . $scope, $compactedBefore->toDateTimeString());
+        } catch (\Throwable) {
+            // A cache outage only costs the next run a wider scan.
+        }
+    }
+
     protected function prunePositions(\Closure $rows, RetentionPolicy $policy): array
     {
         $stats = $this->emptyTableStats();
-        $this->deleteInBatches('positions', 'id', fn ($query) => $rows($query)->whereNotNull('deleted_at'), $stats);
+        $this->deleteInBatches('positions', 'id', fn ($query) => $rows($query)->whereNotNull('deleted_at'), $stats, 'deleted_at');
         if ($cutoff = $policy->cutoff('position_retention_days')) {
-            $this->deleteInBatches('positions', 'id', fn ($query) => $rows($query)->where('created_at', '<', $cutoff->toDateTimeString()), $stats);
+            $this->deleteInBatches('positions', 'id', fn ($query) => $rows($query)->where('created_at', '<', $cutoff->toDateTimeString()), $stats, 'created_at');
         }
 
         return $stats;
@@ -232,7 +298,7 @@ class PruneTelematicsData extends Command
         $stats = $this->emptyTableStats();
         foreach (['processed' => 'processed_retention_hours', 'quarantined' => 'quarantine_retention_days'] as $status => $key) {
             if ($cutoff = $policy->cutoff($key)) {
-                $this->deleteInBatches('telematic_deliveries', 'uuid', fn ($query) => $inbox($query)->where('status', $status)->where('updated_at', '<', $cutoff->toDateTimeString()), $stats);
+                $this->deleteInBatches('telematic_deliveries', 'uuid', fn ($query) => $inbox($query)->where('status', $status)->where('updated_at', '<', $cutoff->toDateTimeString()), $stats, 'updated_at');
             }
         }
 
@@ -244,46 +310,55 @@ class PruneTelematicsData extends Command
         $stats = $this->emptyTableStats();
         if ($cutoff = $policy->cutoff('sync_run_retention_days')) {
             // In-flight runs are recovered by the drain command, never expired here.
-            $this->deleteInBatches('telematic_sync_runs', 'uuid', fn ($query) => $inbox($query)->whereNotIn('status', ['fetching', 'ingesting'])->where('updated_at', '<', $cutoff->toDateTimeString()), $stats);
+            $this->deleteInBatches('telematic_sync_runs', 'uuid', fn ($query) => $inbox($query)->whereNotIn('status', ['fetching', 'ingesting'])->where('updated_at', '<', $cutoff->toDateTimeString()), $stats, 'updated_at');
         }
 
         return $stats;
     }
 
-    protected function deleteInBatches(string $table, string $key, \Closure $scope, array &$stats): void
+    /**
+     * Batches are ordered by the column the scope ranges over (the retention indexes lead
+     * with company_uuid and that column), so each pick is an index range rather than a
+     * primary-key walk across the whole table. Returns true when the scope was drained.
+     */
+    protected function deleteInBatches(string $table, string $key, \Closure $scope, array &$stats, ?string $orderBy = null): bool
     {
         if ($this->dryRun) {
             $stats['deleted'] += $scope(DB::table($table))->count();
 
-            return;
+            return true;
         }
         for ($batch = 0; $batch < $this->maxBatches; $batch++) {
-            $ids = $scope(DB::table($table))->orderBy($key)->limit($this->batchSize)->pluck($key);
+            $ids = $scope(DB::table($table))->orderBy($orderBy ?? $key)->limit($this->batchSize)->pluck($key);
             if ($ids->isEmpty()) {
-                return;
+                return true;
             }
             $stats['batches']++;
             $stats['deleted'] += DB::table($table)->whereIn($key, $ids->all())->delete();
         }
         $stats['capped'] = true;
+
+        return false;
     }
 
-    protected function updateInBatches(string $table, string $key, \Closure $scope, array $values, array &$stats): void
+    protected function updateInBatches(string $table, string $key, \Closure $scope, array $values, array &$stats, ?string $orderBy = null): bool
     {
         if ($this->dryRun) {
             $stats['compacted'] += $scope(DB::table($table))->count();
 
-            return;
+            return true;
         }
         for ($batch = 0; $batch < $this->maxBatches; $batch++) {
-            $ids = $scope(DB::table($table))->orderBy($key)->limit($this->batchSize)->pluck($key);
+            $ids = $scope(DB::table($table))->orderBy($orderBy ?? $key)->limit($this->batchSize)->pluck($key);
             if ($ids->isEmpty()) {
-                return;
+                return true;
             }
             $stats['batches']++;
             $stats['compacted'] += DB::table($table)->whereIn($key, $ids->all())->update($values);
         }
         $stats['capped'] = true;
+
+        return false;
     }
 
     protected function report(string $label, array $stats): void

package/server/src/Events/OrderChanged.php

@@ -0,0 +1,257 @@
+<?php
+
+namespace Fleetbase\FleetOps\Events;
+
+use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Place;
+use Fleetbase\FleetOps\Notifications\OrderChanged as OrderChangedNotification;
+use Fleetbase\LaravelMysqlSpatial\Types\Point;
+use Fleetbase\Models\User;
+use Illuminate\Broadcasting\Channel;
+use Illuminate\Broadcasting\InteractsWithSockets;
+use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * Broadcast as `order.changed` when an order's route, items, contact, schedule,
+ * notes or amounts were edited after it was placed.
+ *
+ * Channels: order.{public_id}, order.{uuid}, driver.{public_id} and driver.{uuid}
+ * when a driver is assigned, customer.{public_id} when a customer exists and
+ * company.{company_uuid}.
+ *
+ * Data: { id, changes[], summary, dropoff, cod_amount, total, currency, changed_by, changed_at }.
+ *
+ * Every value is captured when the event is created, so the broadcast does not
+ * depend on the order still looking the same when the queue sends it.
+ */
+class OrderChanged implements ShouldBroadcast
+{
+    use Dispatchable;
+    use InteractsWithSockets;
+
+    /**
+     * Changes that concern the assigned driver: these send them a push.
+     */
+    public const DRIVER_CHANGES = ['pickup', 'dropoff', 'return', 'waypoints', 'items', 'cod_amount', 'schedule', 'notes'];
+
+    public string $eventId;
+
+    public string $sentAt;
+
+    public array $channelNames = [];
+
+    public array $data = [];
+
+    /**
+     * @param array  $changes the changed parts: dropoff, items, contact, schedule, notes, total, cod_amount, ...
+     * @param string $summary one human line describing the change
+     * @param array  $extra   overrides for the data: total, currency, cod_amount, changed_by, changed_at, dropoff
+     */
+    public function __construct(Order $order, array $changes, string $summary = '', array $extra = [])
+    {
+        $this->eventId      = uniqid('event_');
+        $this->sentAt       = Carbon::now()->toDateTimeString();
+        $this->channelNames = static::channelNamesFor($order);
+        $this->data         = static::dataFor($order, $changes, $summary, $extra);
+    }
+
+    /**
+     * Broadcast `order.changed` for the order and, unless told otherwise, push the
+     * change to the assigned driver when it concerns them.
+     *
+     * Storefront and other extensions call this after their own order edits.
+     */
+    public static function dispatchFor(Order $order, array $changes, string $summary = '', array $extra = [], bool $notifyDriver = true): ?self
+    {
+        $changes = array_values(array_unique(array_filter($changes, 'is_string')));
+        if ($changes === []) {
+            return null;
+        }
+
+        $event = new static($order, $changes, $summary, $extra);
+
+        try {
+            event($event);
+        } catch (\Throwable $exception) {
+            Log::warning('Unable to broadcast order.changed', ['order' => $order->public_id, 'error' => $exception->getMessage()]);
+        }
+
+        if ($notifyDriver && static::concernsDriver($changes)) {
+            static::notifyDriver($order, $event);
+        }
+
+        return $event;
+    }
+
+    /**
+     * Whether any of the changes concerns the driver doing the order.
+     */
+    public static function concernsDriver(array $changes): bool
+    {
+        return (bool) array_intersect($changes, self::DRIVER_CHANGES);
+    }
+
+    /**
+     * Push the change to the order's assigned driver.
+     */
+    public static function notifyDriver(Order $order, self $event): bool
+    {
+        if (!$order->driver_assigned_uuid) {
+            return false;
+        }
+
+        try {
+            $driver = static::assignedDriver($order);
+            if (!$driver) {
+                return false;
+            }
+
+            $driver->notify(new OrderChangedNotification($order, $event->data['changes'], (string) $event->data['summary']));
+
+            return true;
+        } catch (\Throwable $exception) {
+            Log::warning('Unable to notify driver of order change', ['order' => $order->public_id, 'error' => $exception->getMessage()]);
+
+            return false;
+        }
+    }
+
+    /**
+     * The order's assigned driver, read past the driver scope as the order listeners do.
+     */
+    public static function assignedDriver(Order $order): ?Driver
+    {
+        if (!$order->driver_assigned_uuid) {
+            return null;
+        }
+
+        $driver = $order->relationLoaded('driverAssigned') ? $order->getRelation('driverAssigned') : null;
+        if ($driver instanceof Driver && $driver->uuid === $order->driver_assigned_uuid) {
+            return $driver;
+        }
+
+        $driver = Driver::where('uuid', $order->driver_assigned_uuid)->withoutGlobalScopes()->first();
+        if ($driver) {
+            $order->setRelation('driverAssigned', $driver);
+        }
+
+        return $driver;
+    }
+
+    public static function channelNamesFor(Order $order): array
+    {
+        $channels = [
+            'order.' . $order->public_id,
+            'order.' . $order->uuid,
+        ];
+
+        if ($order->driver_assigned_uuid) {
+            $driverPublicId = static::attempt(fn () => static::assignedDriver($order)?->public_id);
+            if ($driverPublicId) {
+                $channels[] = 'driver.' . $driverPublicId;
+            }
+            $channels[] = 'driver.' . $order->driver_assigned_uuid;
+        }
+
+        if ($order->customer_uuid) {
+            $customerPublicId = data_get($order, 'customer.public_id');
+            if ($customerPublicId) {
+                $channels[] = 'customer.' . $customerPublicId;
+            }
+        }
+
+        if ($order->company_uuid) {
+            $channels[] = 'company.' . $order->company_uuid;
+        }
+
+        return array_values(array_unique($channels));
+    }
+
+    public static function dataFor(Order $order, array $changes, string $summary = '', array $extra = []): array
+    {
+        $payload = $order->relationLoaded('payload') ? $order->payload : static::attempt(fn () => $order->payload);
+
+        return [
+            'id'         => $order->public_id,
+            'changes'    => array_values($changes),
+            'summary'    => $summary,
+            'dropoff'    => array_key_exists('dropoff', $extra) ? $extra['dropoff'] : static::placeData($payload?->dropoff ?? null),
+            'cod_amount' => array_key_exists('cod_amount', $extra) ? $extra['cod_amount'] : static::numberOrNull($payload?->cod_amount ?? null),
+            'total'      => array_key_exists('total', $extra) ? $extra['total'] : static::numberOrNull(static::attempt(fn () => $order->transaction_amount)),
+            'currency'   => array_key_exists('currency', $extra) ? $extra['currency'] : (static::attempt(fn () => $order->transaction_currency) ?? $payload?->cod_currency ?? null),
+            'changed_by' => array_key_exists('changed_by', $extra) ? $extra['changed_by'] : static::currentUserName(),
+            'changed_at' => $extra['changed_at'] ?? Carbon::now()->toIso8601ZuluString(),
+        ];
+    }
+
+    /**
+     * The drop-off as `{ id, address, location: { type: Point, coordinates: [lng, lat] } }`.
+     */
+    public static function placeData(?Place $place): ?array
+    {
+        if (!$place instanceof Place) {
+            return null;
+        }
+
+        $location = $place->location;
+
+        return [
+            'id'       => $place->public_id,
+            'address'  => static::attempt(fn () => $place->address),
+            'location' => $location instanceof Point ? ['type' => 'Point', 'coordinates' => [$location->getLng(), $location->getLat()]] : null,
+        ];
+    }
+
+    public function broadcastOn(): array
+    {
+        return array_map(fn (string $name) => new Channel($name), $this->channelNames);
+    }
+
+    public function broadcastAs(): string
+    {
+        return 'order.changed';
+    }
+
+    public function broadcastWith(): array
+    {
+        return [
+            'id'          => $this->eventId,
+            'api_version' => config('api.version'),
+            'event'       => $this->broadcastAs(),
+            'created_at'  => $this->sentAt,
+            'data'        => $this->data,
+        ];
+    }
+
+    protected static function currentUserName(): ?string
+    {
+        $userUuid = session('user');
+        if (!$userUuid) {
+            return null;
+        }
+
+        return static::attempt(fn () => User::where('uuid', $userUuid)->value('name'));
+    }
+
+    protected static function numberOrNull(mixed $value): int|float|null
+    {
+        if ($value === null || $value === '' || !is_numeric($value)) {
+            return null;
+        }
+
+        return $value + 0;
+    }
+
+    protected static function attempt(callable $callback): mixed
+    {
+        try {
+            return $callback();
+        } catch (\Throwable) {
+            return null;
+        }
+    }
+}

package/server/src/Events/OrderDriverUnassigned.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace Fleetbase\FleetOps\Events;
+
+use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Models\Order;
+use Illuminate\Broadcasting\Channel;
+use Illuminate\Broadcasting\InteractsWithSockets;
+use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Support\Carbon;
+
+/**
+ * Broadcast as `order.driver_unassigned` when a driver is taken off an order,
+ * whether unassigned or replaced by another driver.
+ *
+ * Channels: driver.{old driver public_id}, driver.{old driver uuid} and the
+ * order's company channel. Data: { id: order public id, driver: old driver public id }.
+ */
+class OrderDriverUnassigned implements ShouldBroadcast
+{
+    use Dispatchable;
+    use InteractsWithSockets;
+
+    public string $eventId;
+
+    public string $sentAt;
+
+    public array $channelNames = [];
+
+    public array $data = [];
+
+    public function __construct(Order $order, Driver $driver)
+    {
+        $this->eventId      = uniqid('event_');
+        $this->sentAt       = Carbon::now()->toDateTimeString();
+        $this->channelNames = array_values(array_filter([
+            $driver->public_id ? 'driver.' . $driver->public_id : null,
+            $driver->uuid ? 'driver.' . $driver->uuid : null,
+            $order->company_uuid ? 'company.' . $order->company_uuid : null,
+        ]));
+        $this->data = [
+            'id'     => $order->public_id,
+            'driver' => $driver->public_id,
+        ];
+    }
+
+    public function broadcastOn(): array
+    {
+        return array_map(fn (string $name) => new Channel($name), $this->channelNames);
+    }
+
+    public function broadcastAs(): string
+    {
+        return 'order.driver_unassigned';
+    }
+
+    public function broadcastWith(): array
+    {
+        return [
+            'id'          => $this->eventId,
+            'api_version' => config('api.version'),
+            'event'       => $this->broadcastAs(),
+            'created_at'  => $this->sentAt,
+            'data'        => $this->data,
+        ];
+    }
+}

package/server/src/Exceptions/OrderEditLockedException.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace Fleetbase\FleetOps\Exceptions;
+
+/**
+ * Thrown when an order edit touches a field its current status locks.
+ *
+ * Carries the refused fields with the reason for each, so a controller can
+ * answer 422 with `{ error, locked: { field: reason } }`.
+ */
+class OrderEditLockedException extends \Exception
+{
+    /**
+     * @param array<string, string> $locked the refused fields and why each is locked
+     */
+    public function __construct(public array $locked = [], string $message = '', int $code = 422, ?\Throwable $previous = null)
+    {
+        if ($message === '') {
+            $message = $locked ? implode(' ', array_values(array_unique($locked))) : 'This order can no longer be edited.';
+        }
+
+        parent::__construct($message, $code, $previous);
+    }
+
+    /**
+     * The 422 response body: the message plus the refused fields.
+     */
+    public function toResponseData(): array
+    {
+        return ['locked' => $this->locked];
+    }
+}

package/server/src/Expansions/CompanyExpansion.php

@@ -4,6 +4,7 @@ namespace Fleetbase\FleetOps\Expansions;
 
 use Fleetbase\Build\Expansion;
 use Fleetbase\FleetOps\Models\Driver;
+use Illuminate\Database\Eloquent\Relations\HasMany;
 
 class CompanyExpansion implements Expansion
 {
@@ -18,11 +19,11 @@ class CompanyExpansion implements Expansion
     }
 
     /**
-     * @return \Illuminate\Database\Eloquent\Relations\HasMany
+     * @return HasMany
      */
     public static function drivers()
     {
-        return function () {
+        return function (): HasMany {
             /** @var \Illuminate\Database\Eloquent\Model $this */
             return $this->hasMany(Driver::class);
         };