@fleetbase/fleetops-engine 0.6.38 → 0.6.40

package/server/src/Jobs/ProcessAllocationJob.php

@@ -0,0 +1,119 @@
+<?php
+
+namespace Fleetbase\FleetOps\Jobs;
+
+use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Orchestration\OrchestrationEngineRegistry;
+use Fleetbase\Models\Setting;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * ProcessAllocationJob.
+ *
+ * Dispatched asynchronously when auto-allocation is triggered (e.g. on order
+ * creation or on delivery completion when auto_reallocate_on_complete is
+ * enabled). The job runs the active allocation engine and commits all
+ * assignments automatically.
+ *
+ * The job is idempotent — if an order has already been assigned by the time
+ * the job runs, it is silently skipped.
+ *
+ * @example Dispatching from a listener:
+ *   ProcessAllocationJob::dispatch($companyUuid, $orderIds);
+ */
+class ProcessAllocationJob implements ShouldQueue
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    /**
+     * Maximum number of retry attempts before the job is marked as failed.
+     */
+    public int $tries = 3;
+
+    /**
+     * @param string $companyUuid the company to run allocation for
+     * @param array  $orderIds    Optional list of order public_ids to allocate.
+     *                            If empty, all unassigned orders are used.
+     */
+    public function __construct(
+        protected string $companyUuid,
+        protected array $orderIds = [],
+    ) {
+    }
+
+    public function handle(OrchestrationEngineRegistry $registry): void
+    {
+        $ordersQuery = Order::where('company_uuid', $this->companyUuid)
+            ->whereNull('driver_assigned_uuid')
+            ->whereNotIn('status', ['completed', 'cancelled'])
+            ->with(['payload.dropoff', 'payload.waypoints']);
+
+        if (!empty($this->orderIds)) {
+            $ordersQuery->whereIn('public_id', $this->orderIds);
+        }
+
+        $orders = $ordersQuery->get();
+
+        if ($orders->isEmpty()) {
+            Log::info("[ProcessAllocationJob] No unassigned orders for company {$this->companyUuid}.");
+
+            return;
+        }
+
+        $vehicles = Vehicle::where('company_uuid', $this->companyUuid)
+            ->with(['driver' => fn ($q) => $q->where('online', true)])
+            ->get()
+            ->filter(fn ($v) => $v->driver !== null);
+
+        if ($vehicles->isEmpty()) {
+            Log::info("[ProcessAllocationJob] No available vehicles for company {$this->companyUuid}.");
+
+            return;
+        }
+
+        $engineId = Setting::lookup('fleetops.orchestrator_engine', 'greedy');
+        $engine   = $registry->resolve($engineId);
+
+        $result = $engine->allocate($orders, $vehicles, [
+            'max_travel_time'  => Setting::lookup('fleetops.allocation_max_travel_time', 3600),
+            'balance_workload' => Setting::lookup('fleetops.allocation_balance_workload', false),
+        ]);
+
+        foreach ($result['assignments'] as $assignment) {
+            $order  = Order::where('public_id', $assignment['order_id'])->first();
+            $driver = Driver::where('public_id', $assignment['driver_id'])->first();
+
+            if (!$order || !$driver) {
+                continue;
+            }
+
+            // Skip if already assigned (idempotency guard)
+            if ($order->driver_assigned_uuid) {
+                continue;
+            }
+
+            $order->driver_assigned_uuid = $driver->uuid;
+            $order->save();
+            $order->firstDispatchWithActivity();
+        }
+
+        Log::info(
+            sprintf(
+                '[ProcessAllocationJob] Committed %d assignments, %d unassigned for company %s.',
+                count($result['assignments']),
+                count($result['unassigned']),
+                $this->companyUuid
+            )
+        );
+    }
+}

package/server/src/Listeners/HandleDeliveryCompletion.php

@@ -0,0 +1,47 @@
+<?php
+
+namespace Fleetbase\FleetOps\Listeners;
+
+use Fleetbase\FleetOps\Events\OrderCompleted;
+use Fleetbase\FleetOps\Jobs\ProcessAllocationJob;
+use Fleetbase\Models\Setting;
+use Illuminate\Contracts\Queue\ShouldQueue;
+
+/**
+ * HandleDeliveryCompletion.
+ *
+ * Listens for the OrderCompleted event and dispatches a new allocation run
+ * when the 'auto_reallocate_on_complete' setting is enabled.
+ *
+ * This closes the re-allocation loop: as drivers complete deliveries and
+ * become available, the engine automatically picks up the next batch of
+ * unassigned orders without dispatcher intervention.
+ *
+ * The listener is registered in EventServiceProvider alongside the existing
+ * HandleOrderDispatched and HandleOrderReady listeners.
+ */
+class HandleDeliveryCompletion implements ShouldQueue
+{
+    /**
+     * Handle the OrderCompleted event.
+     */
+    public function handle(OrderCompleted $event): void
+    {
+        $order = $event->order ?? null;
+
+        if (!$order) {
+            return;
+        }
+
+        $companyUuid = $order->company_uuid;
+
+        // Only re-allocate if the setting is enabled for this company
+        if (!Setting::lookup('fleetops.auto_reallocate_on_complete', false)) {
+            return;
+        }
+
+        // Dispatch the allocation job asynchronously so it does not block
+        // the order completion response.
+        ProcessAllocationJob::dispatch($companyUuid);
+    }
+}

package/server/src/Listeners/NotifyDriverOnShiftChange.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace Fleetbase\FleetOps\Listeners;
+
+use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Notifications\DriverShiftChanged;
+use Fleetbase\Models\Schedule;
+use Fleetbase\Models\ScheduleItem;
+use Fleetbase\Models\Setting;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Queue\InteractsWithQueue;
+
+/**
+ * Listener: NotifyDriverOnShiftChange.
+ *
+ * Fires after a ScheduleItem is created or updated. Checks the company-level
+ * `notify_drivers_on_shift_change` scheduling setting and, if enabled, sends
+ * a DriverShiftChanged mail notification to the driver who owns the schedule.
+ */
+class NotifyDriverOnShiftChange implements ShouldQueue
+{
+    use InteractsWithQueue;
+
+    /**
+     * Handle the event.
+     *
+     * @param object $event Either ScheduleItemCreated or ScheduleItemUpdated
+     */
+    public function handle($event): void
+    {
+        /** @var ScheduleItem $scheduleItem */
+        $scheduleItem = $event->scheduleItem ?? null;
+        if (!$scheduleItem instanceof ScheduleItem) {
+            return;
+        }
+
+        // Load the parent schedule to find the subject (driver)
+        /** @var Schedule|null $schedule */
+        $schedule = $scheduleItem->schedule()->with('subject')->first();
+        if (!$schedule) {
+            return;
+        }
+
+        // Only proceed if the subject is a Driver
+        $subject = $schedule->subject;
+        if (!$subject instanceof Driver) {
+            return;
+        }
+
+        // Check the company-level scheduling setting
+        $settings     = Setting::lookupFromCompany('fleet-ops.scheduling-settings', []);
+        $shouldNotify = (bool) data_get($settings, 'notify_drivers_on_shift_change', false);
+        if (!$shouldNotify) {
+            return;
+        }
+
+        // Determine if this is a new shift or an update
+        $isNew = $event instanceof \Fleetbase\Events\ScheduleItemCreated;
+
+        // Send the notification to the driver
+        $subject->notify(new DriverShiftChanged($scheduleItem, $isNew));
+    }
+}

package/server/src/Mail/MaintenanceScheduleReminder.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace Fleetbase\FleetOps\Mail;
+
+use Fleetbase\FleetOps\Models\MaintenanceSchedule;
+use Illuminate\Bus\Queueable;
+use Illuminate\Mail\Mailable;
+use Illuminate\Mail\Mailables\Content;
+use Illuminate\Mail\Mailables\Envelope;
+use Illuminate\Queue\SerializesModels;
+
+class MaintenanceScheduleReminder extends Mailable
+{
+    use Queueable;
+    use SerializesModels;
+
+    /**
+     * The maintenance schedule this reminder is for.
+     */
+    public MaintenanceSchedule $schedule;
+
+    /**
+     * How many days before the due date this reminder is firing.
+     */
+    public int $offsetDays;
+
+    /**
+     * Create a new message instance.
+     */
+    public function __construct(MaintenanceSchedule $schedule, int $offsetDays)
+    {
+        $this->schedule   = $schedule;
+        $this->offsetDays = $offsetDays;
+    }
+
+    /**
+     * Get the message envelope.
+     */
+    public function envelope(): Envelope
+    {
+        $subject = 'Maintenance Reminder: ' . $this->schedule->name;
+
+        if ($this->schedule->subject) {
+            $assetName = $this->schedule->subject->name
+                ?? $this->schedule->subject->display_name
+                ?? $this->schedule->subject->public_id;
+            $subject .= ' — ' . $assetName;
+        }
+
+        return new Envelope(subject: $subject);
+    }
+
+    /**
+     * Get the message content definition.
+     */
+    public function content(): Content
+    {
+        return new Content(
+            markdown: 'fleetops::mail.maintenance-schedule-reminder',
+            with: [
+                'schedule'   => $this->schedule,
+                'assignee'   => $this->schedule->defaultAssignee,
+                'subject'    => $this->schedule->subject,
+                'offsetDays' => $this->offsetDays,
+            ]
+        );
+    }
+}

package/server/src/Mail/WorkOrderDispatched.php

@@ -0,0 +1,58 @@
+<?php
+
+namespace Fleetbase\FleetOps\Mail;
+
+use Fleetbase\FleetOps\Models\WorkOrder;
+use Illuminate\Bus\Queueable;
+use Illuminate\Mail\Mailable;
+use Illuminate\Mail\Mailables\Content;
+use Illuminate\Mail\Mailables\Envelope;
+use Illuminate\Queue\SerializesModels;
+
+class WorkOrderDispatched extends Mailable
+{
+    use Queueable;
+    use SerializesModels;
+
+    /**
+     * The work order being dispatched.
+     */
+    public WorkOrder $workOrder;
+
+    /**
+     * Create a new message instance.
+     */
+    public function __construct(WorkOrder $workOrder)
+    {
+        $this->workOrder = $workOrder;
+    }
+
+    /**
+     * Get the message envelope.
+     */
+    public function envelope(): Envelope
+    {
+        $subject = 'Work Order #' . $this->workOrder->public_id;
+
+        if ($this->workOrder->subject) {
+            $subject .= ': ' . $this->workOrder->subject;
+        }
+
+        return new Envelope(subject: $subject);
+    }
+
+    /**
+     * Get the message content definition.
+     */
+    public function content(): Content
+    {
+        return new Content(
+            markdown: 'fleetops::mail.work-order-dispatched',
+            with: [
+                'workOrder' => $this->workOrder,
+                'assignee'  => $this->workOrder->assignee,
+                'target'    => $this->workOrder->target,
+            ]
+        );
+    }
+}

package/server/src/Models/Asset.php

@@ -210,12 +210,12 @@ class Asset extends Model
 
     public function assignedTo(): MorphTo
     {
-        return $this->morphTo();
+        return $this->morphTo(__FUNCTION__, 'assigned_to_type', 'assigned_to_uuid');
     }
 
     public function operator(): MorphTo
     {
-        return $this->morphTo();
+        return $this->morphTo(__FUNCTION__, 'operator_type', 'operator_uuid');
     }
 
     public function category(): BelongsTo

package/server/src/Models/Device.php

@@ -220,7 +220,7 @@ class Device extends Model
 
     public function attachable(): MorphTo
     {
-        return $this->morphTo();
+        return $this->morphTo(__FUNCTION__, 'attachable_type', 'attachable_uuid');
     }
 
     public function events(): HasMany

package/server/src/Models/Driver.php

@@ -11,6 +11,9 @@ use Fleetbase\LaravelMysqlSpatial\Eloquent\SpatialTrait;
 use Fleetbase\LaravelMysqlSpatial\Types\Point as SpatialPoint;
 use Fleetbase\Models\File;
 use Fleetbase\Models\Model;
+use Fleetbase\Models\Schedule;
+use Fleetbase\Models\ScheduleAvailability;
+use Fleetbase\Models\ScheduleItem;
 use Fleetbase\Models\User;
 use Fleetbase\Traits\HasApiModelBehavior;
 use Fleetbase\Traits\HasApiModelCache;
@@ -25,6 +28,8 @@ use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Database\Eloquent\Relations\HasMany;
 use Illuminate\Database\Eloquent\Relations\HasManyThrough;
+use Illuminate\Database\Eloquent\Relations\MorphMany;
+use Illuminate\Database\Eloquent\Relations\MorphOne;
 use Illuminate\Notifications\Notifiable;
 use Illuminate\Support\Arr;
 use Illuminate\Support\Collection;
@@ -105,6 +110,12 @@ class Driver extends Model
         'slug',
         'status',
         'meta,',
+        // Orchestrator
+        'skills',
+        'max_travel_time',
+        'max_distance',
+        'time_window_start',
+        'time_window_end',
     ];
 
     /**
@@ -127,9 +138,13 @@ class Driver extends Model
      * @var array
      */
     protected $casts = [
-        'location'   => Point::class,
-        'online'     => 'boolean',
-        'meta'       => Json::class,
+        'location'        => Point::class,
+        'online'          => 'boolean',
+        'meta'            => Json::class,
+        // Orchestrator
+        'skills'          => Json::class,
+        'max_travel_time' => 'integer',
+        'max_distance'    => 'integer',
     ];
 
     /**
@@ -300,6 +315,69 @@ class Driver extends Model
         return $this->hasMany(\Fleetbase\Models\UserDevice::class, 'user_uuid', 'user_uuid');
     }
 
+    /**
+     * Get all schedules assigned to this driver.
+     * The driver acts as the polymorphic `subject` on the Schedule model.
+     */
+    public function schedules(): MorphMany
+    {
+        // Explicit FK columns required — Fleetbase uses *_uuid not *_id
+        return $this->morphMany(Schedule::class, 'subject', 'subject_type', 'subject_uuid');
+    }
+
+    /**
+     * Get all individual schedule items (shifts) assigned to this driver.
+     * The driver acts as the polymorphic `assignee` on the ScheduleItem model.
+     */
+    public function scheduleItems(): MorphMany
+    {
+        // Explicit FK columns required — Fleetbase uses *_uuid not *_id
+        return $this->morphMany(ScheduleItem::class, 'assignee', 'assignee_type', 'assignee_uuid');
+    }
+
+    /**
+     * The driver's current active shift — the ScheduleItem whose window
+     * contains the current timestamp and whose status is 'scheduled' or 'active'.
+     *
+     * Exposed as an eager-loadable MorphOne so the order scheduler route can
+     * request it via with: ['currentShift'] without triggering an N+1 query.
+     * The FullCalendar resource timeline uses this to render shift-window
+     * background events for each driver resource row.
+     */
+    public function currentShift(): MorphOne
+    {
+        return $this->morphOne(ScheduleItem::class, 'assignee', 'assignee_type', 'assignee_uuid')
+            ->whereIn('status', ['scheduled', 'active'])
+            ->where('start_at', '<=', now())
+            ->where('end_at', '>=', now())
+            ->latest('start_at');
+    }
+
+    /**
+     * Get the active schedule item (shift) for a given date.
+     * Used by OrchestrationPayloadBuilder to inject time_window constraints.
+     */
+    public function activeShiftFor(?\DateTimeInterface $date = null): ?ScheduleItem
+    {
+        $date = $date ?? now();
+
+        return $this->scheduleItems()
+            ->whereDate('start_at', $date)
+            ->whereIn('status', ['pending', 'active'])
+            ->orderBy('start_at')
+            ->first();
+    }
+
+    /**
+     * Get all availability records (time-off, preferred hours) for this driver.
+     * The driver acts as the polymorphic `subject` on the ScheduleAvailability model.
+     */
+    public function availabilities(): MorphMany
+    {
+        // Explicit FK columns required — Fleetbase uses *_uuid not *_id
+        return $this->morphMany(ScheduleAvailability::class, 'subject', 'subject_type', 'subject_uuid');
+    }
+
     /**
      * Get avatar url.
      */
@@ -364,7 +442,7 @@ class Driver extends Model
             function ($option) {
                 $key = str_replace(['.svg', '.png'], '', $option);
 
-                return [$key => Utils::assetFromS3('static/driver-icons/' . $option)];
+                return [$key => Utils::assetFromFleetbase('static/driver-icons/' . $option)];
             }
         );
 

package/server/src/Models/Equipment.php

@@ -3,6 +3,8 @@
 namespace Fleetbase\FleetOps\Models;
 
 use Fleetbase\Casts\Json;
+use Fleetbase\Casts\Money;
+use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Models\File;
 use Fleetbase\Models\Model;
 use Fleetbase\Models\User;
@@ -87,6 +89,7 @@ class Equipment extends Model
         'equipable_uuid',
         'purchased_at',
         'purchase_price',
+        'currency',
         'meta',
         'slug',
     ];
@@ -119,7 +122,8 @@ class Equipment extends Model
      */
     protected $casts = [
         'purchased_at'   => 'date',
-        'purchase_price' => 'decimal:2',
+        // Money values
+        'purchase_price' => Money::class,
         'meta'           => Json::class,
     ];
 
@@ -184,7 +188,7 @@ class Equipment extends Model
 
     public function equipable(): MorphTo
     {
-        return $this->morphTo();
+        return $this->morphTo(__FUNCTION__, 'equipable_type', 'equipable_uuid');
     }
 
     public function maintenances(): HasMany
@@ -480,4 +484,60 @@ class Equipment extends Model
 
         return null;
     }
+
+    /**
+     * Create an Equipment instance from an import row.
+     *
+     * Monetary values (purchase_price) must be supplied in cents (integers).
+     * The Money cast will strip non-numeric characters before storage.
+     *
+     * @param array $row          Associative array from the import spreadsheet
+     * @param bool  $saveInstance Whether to persist the record immediately
+     */
+    public static function createFromImport(array $row, bool $saveInstance = false): Equipment
+    {
+        $row = array_filter($row);
+
+        $name          = Utils::or($row, ['name']);
+        $code          = Utils::or($row, ['code', 'internal_id']);
+        $type          = Utils::or($row, ['type'], 'equipment');
+        $status        = Utils::or($row, ['status'], 'operational');
+        $serialNumber  = Utils::or($row, ['serial_number', 'serial']);
+        $manufacturer  = Utils::or($row, ['manufacturer', 'make', 'brand']);
+        $model         = Utils::or($row, ['model', 'equipment_model']);
+        $purchasePrice = Utils::or($row, ['purchase_price', 'price', 'cost']);
+        $currency      = Utils::or($row, ['currency'], 'USD');
+        $purchasedAt   = Utils::or($row, ['purchased_at', 'purchase_date']);
+        $warrantyName  = Utils::or($row, ['warranty_name', 'warranty']);
+
+        $equipment = new static([
+            'company_uuid'   => session('company'),
+            'name'           => $name,
+            'code'           => $code,
+            'type'           => $type,
+            'status'         => $status,
+            'serial_number'  => $serialNumber,
+            'manufacturer'   => $manufacturer,
+            'model'          => $model,
+            'purchase_price' => $purchasePrice,
+            'currency'       => strtoupper($currency ?? 'USD'),
+            'purchased_at'   => $purchasedAt ? \Carbon\Carbon::parse($purchasedAt) : null,
+        ]);
+
+        // Attempt to resolve warranty by name
+        if ($warrantyName) {
+            $warranty = Warranty::where('company_uuid', session('company'))
+                ->where('name', 'like', '%' . $warrantyName . '%')
+                ->first();
+            if ($warranty) {
+                $equipment->warranty_uuid = $warranty->uuid;
+            }
+        }
+
+        if ($saveInstance === true) {
+            $equipment->save();
+        }
+
+        return $equipment;
+    }
 }