@fleetbase/fleetops-engine 0.6.38 → 0.6.40

package/server/src/Models/Waypoint.php

@@ -51,7 +51,7 @@ class Waypoint extends Model
      *
      * @var array
      */
-    protected $fillable = ['_key', '_import_id', 'company_uuid', 'payload_uuid', 'place_uuid', 'tracking_number_uuid', 'customer_uuid', 'customer_type', 'type', 'order'];
+    protected $fillable = ['_key', '_import_id', 'company_uuid', 'payload_uuid', 'place_uuid', 'tracking_number_uuid', 'customer_uuid', 'customer_type', 'type', 'order', 'time_window_start', 'time_window_end', 'service_time', 'notes', 'pod_method', 'pod_required'];
 
     /**
      * Dynamic attributes that are appended to object.
@@ -81,6 +81,12 @@ class Waypoint extends Model
      */
     protected $casts = [
         'customer_type'    => PolymorphicType::class,
+        // Orchestrator
+        'time_window_start' => 'datetime',
+        'time_window_end'   => 'datetime',
+        'service_time'      => 'integer',
+        // Per-stop POD and notes (mirrors order-level fields)
+        'pod_required'      => 'boolean',
     ];
 
     /**

package/server/src/Models/WorkOrder.php

@@ -3,7 +3,9 @@
 namespace Fleetbase\FleetOps\Models;
 
 use Fleetbase\Casts\Json;
+use Fleetbase\Casts\Money;
 use Fleetbase\Casts\PolymorphicType;
+use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Models\File;
 use Fleetbase\Models\Model;
 use Fleetbase\Models\User;
@@ -17,6 +19,7 @@ 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\Str;
 use Spatie\Activitylog\LogOptions;
 use Spatie\Activitylog\Traits\LogsActivity;
 
@@ -85,10 +88,30 @@ class WorkOrder extends Model
         'closed_at',
         'instructions',
         'checklist',
+        'estimated_cost',
+        'approved_budget',
+        'actual_cost',
+        'currency',
+        'cost_breakdown',
+        'cost_center',
+        'budget_code',
         'meta',
-        'slug',
     ];
 
+    /**
+     * Boot the model.
+     */
+    public static function boot(): void
+    {
+        parent::boot();
+
+        static::creating(function ($model) {
+            if (empty($model->code)) {
+                $model->code = 'WO-' . strtoupper(Str::random(8));
+            }
+        });
+    }
+
     /**
      * Dynamic attributes that are appended to object.
      *
@@ -104,11 +127,11 @@ class WorkOrder extends Model
     ];
 
     /**
-     * The attributes excluded from the model's JSON form.
+     * Relationships to always eager load.
      *
      * @var array
      */
-    protected $hidden = ['target', 'assignee'];
+    protected $with = ['target', 'assignee'];
 
     /**
      * The attributes that should be cast to native types.
@@ -116,13 +139,18 @@ class WorkOrder extends Model
      * @var array
      */
     protected $casts = [
-        'opened_at'     => 'datetime',
-        'due_at'        => 'datetime',
-        'closed_at'     => 'datetime',
-        'checklist'     => Json::class,
-        'meta'          => Json::class,
-        'target_type'   => PolymorphicType::class,
-        'assignee_type' => PolymorphicType::class,
+        'opened_at'        => 'datetime',
+        'due_at'           => 'datetime',
+        'closed_at'        => 'datetime',
+        'checklist'        => Json::class,
+        'cost_breakdown'   => Json::class,
+        'meta'             => Json::class,
+        'target_type'      => PolymorphicType::class,
+        'assignee_type'    => PolymorphicType::class,
+        // Money values
+        'estimated_cost'   => Money::class,
+        'approved_budget'  => Money::class,
+        'actual_cost'      => Money::class,
     ];
 
     /**
@@ -166,12 +194,12 @@ class WorkOrder extends Model
 
     public function target(): MorphTo
     {
-        return $this->morphTo();
+        return $this->morphTo(__FUNCTION__, 'target_type', 'target_uuid');
     }
 
     public function assignee(): MorphTo
     {
-        return $this->morphTo();
+        return $this->morphTo(__FUNCTION__, 'assignee_type', 'assignee_uuid');
     }
 
     public function maintenances(): HasMany
@@ -532,4 +560,86 @@ class WorkOrder extends Model
                 return 1;
         }
     }
+
+    /**
+     * Create a WorkOrder instance from an import row.
+     *
+     * Monetary values (estimated_cost, approved_budget, actual_cost) must be supplied in cents.
+     * 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): WorkOrder
+    {
+        $row = array_filter($row);
+
+        $subject        = Utils::or($row, ['subject', 'title', 'name']);
+        $status         = Utils::or($row, ['status'], 'open');
+        $priority       = Utils::or($row, ['priority'], 'normal');
+        $instructions   = Utils::or($row, ['instructions', 'description', 'notes']);
+        $openedAt       = Utils::or($row, ['opened_at', 'open_date']);
+        $dueAt          = Utils::or($row, ['due_at', 'due_date']);
+        $estimatedCost  = Utils::or($row, ['estimated_cost']);
+        $approvedBudget = Utils::or($row, ['approved_budget', 'budget']);
+        $actualCost     = Utils::or($row, ['actual_cost']);
+        $currency       = Utils::or($row, ['currency'], 'USD');
+        $costCenter     = Utils::or($row, ['cost_center']);
+        $budgetCode     = Utils::or($row, ['budget_code']);
+        $vehicleName    = Utils::or($row, ['vehicle', 'vehicle_name', 'asset', 'target']);
+        $vendorName     = Utils::or($row, ['vendor', 'vendor_name', 'assignee']);
+
+        $workOrder = new static([
+            'company_uuid'    => session('company'),
+            'subject'         => $subject,
+            'status'          => $status,
+            'priority'        => $priority,
+            'instructions'    => $instructions,
+            'opened_at'       => $openedAt ? \Carbon\Carbon::parse($openedAt) : now(),
+            'due_at'          => $dueAt ? \Carbon\Carbon::parse($dueAt) : null,
+            'estimated_cost'  => $estimatedCost,
+            'approved_budget' => $approvedBudget,
+            'actual_cost'     => $actualCost,
+            'currency'        => strtoupper($currency ?? 'USD'),
+            'cost_center'     => $costCenter,
+            'budget_code'     => $budgetCode,
+        ]);
+
+        // Attempt to resolve the target (vehicle or equipment) by identifier
+        if ($vehicleName) {
+            $vehicle = Vehicle::findByName($vehicleName);
+            if ($vehicle) {
+                $workOrder->target_type = Vehicle::class;
+                $workOrder->target_uuid = $vehicle->uuid;
+            } else {
+                $equipment = Equipment::where('company_uuid', session('company'))
+                    ->where(function ($q) use ($vehicleName) {
+                        $q->where('name', 'like', '%' . $vehicleName . '%')
+                          ->orWhere('public_id', $vehicleName)
+                          ->orWhere('serial_number', $vehicleName);
+                    })->first();
+                if ($equipment) {
+                    $workOrder->target_type = Equipment::class;
+                    $workOrder->target_uuid = $equipment->uuid;
+                }
+            }
+        }
+
+        // Attempt to resolve assignee (vendor) by name
+        if ($vendorName) {
+            $vendor = Vendor::where('company_uuid', session('company'))
+                ->where('name', 'like', '%' . $vendorName . '%')
+                ->first();
+            if ($vendor) {
+                $workOrder->assignee_type = Vendor::class;
+                $workOrder->assignee_uuid = $vendor->uuid;
+            }
+        }
+
+        if ($saveInstance === true) {
+            $workOrder->save();
+        }
+
+        return $workOrder;
+    }
 }

package/server/src/Notifications/DriverShiftChanged.php

@@ -0,0 +1,110 @@
+<?php
+
+namespace Fleetbase\FleetOps\Notifications;
+
+use Fleetbase\Models\ScheduleItem;
+use Fleetbase\Support\Utils;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Notifications\Messages\MailMessage;
+use Illuminate\Notifications\Notification;
+
+class DriverShiftChanged extends Notification implements ShouldQueue
+{
+    use Queueable;
+
+    /**
+     * The schedule item that was created or updated.
+     */
+    public ScheduleItem $scheduleItem;
+
+    /**
+     * Whether this is a new shift (created) or an update to an existing one.
+     */
+    public bool $isNew;
+
+    /**
+     * Notification name.
+     */
+    public static string $name = 'Driver Shift Changed';
+
+    /**
+     * Notification description.
+     */
+    public static string $description = 'Notify a driver when their shift schedule is created or updated.';
+
+    /**
+     * Notification package.
+     */
+    public static string $package = 'fleet-ops';
+
+    /**
+     * The notification title.
+     */
+    public string $title;
+
+    /**
+     * The notification body.
+     */
+    public string $message;
+
+    /**
+     * Create a new notification instance.
+     */
+    public function __construct(ScheduleItem $scheduleItem, bool $isNew = true)
+    {
+        $this->scheduleItem = $scheduleItem;
+        $this->isNew        = $isNew;
+
+        $start = $scheduleItem->start_at ? $scheduleItem->start_at->format('D, M j g:ia') : '—';
+        $end   = $scheduleItem->end_at ? $scheduleItem->end_at->format('g:ia') : '—';
+
+        if ($isNew) {
+            $this->title   = 'New shift scheduled';
+            $this->message = "A new shift has been added to your schedule: {$start} – {$end}.";
+        } else {
+            $this->title   = 'Your shift has been updated';
+            $this->message = "Your shift has been updated: {$start} – {$end}.";
+        }
+    }
+
+    /**
+     * Get the notification's delivery channels.
+     */
+    public function via($notifiable): array
+    {
+        return ['mail'];
+    }
+
+    /**
+     * Build the mail representation of the notification.
+     */
+    public function toMail($notifiable): MailMessage
+    {
+        $message = (new MailMessage())
+            ->subject($this->title)
+            ->line($this->message);
+
+        if ($this->scheduleItem->notes) {
+            $message->line('Notes: ' . $this->scheduleItem->notes);
+        }
+
+        $message->action('View Schedule', Utils::consoleUrl('fleet-ops/operations/scheduler'));
+
+        return $message;
+    }
+
+    /**
+     * Get the array representation of the notification.
+     */
+    public function toArray($notifiable): array
+    {
+        return [
+            'id'             => $this->scheduleItem->public_id,
+            'type'           => 'driver_shift_changed',
+            'is_new'         => $this->isNew,
+            'start_at'       => $this->scheduleItem->start_at,
+            'end_at'         => $this->scheduleItem->end_at,
+        ];
+    }
+}

package/server/src/Observers/WorkOrderObserver.php

@@ -0,0 +1,107 @@
+<?php
+
+namespace Fleetbase\FleetOps\Observers;
+
+use Fleetbase\FleetOps\Models\Maintenance;
+use Fleetbase\FleetOps\Models\MaintenanceSchedule;
+use Fleetbase\FleetOps\Models\WorkOrder;
+
+/**
+ * WorkOrderObserver.
+ *
+ * Listens for status transitions on WorkOrder records. When a work order is
+ * closed (completed), this observer:
+ *
+ *  1. Automatically creates a Maintenance (history) record from the work order's
+ *     data and any completion metadata captured in the work order's meta field.
+ *  2. Resets the linked MaintenanceSchedule's next-due thresholds so the cycle
+ *     restarts from the completion point.
+ *  3. Dispatches a `work_order.completed` event for downstream integrations.
+ */
+class WorkOrderObserver
+{
+    /**
+     * Handle the WorkOrder "updated" event.
+     * We intercept the status transition to "closed" here rather than in a
+     * dedicated "closed" event because Eloquent does not have a per-value event.
+     */
+    public function updated(WorkOrder $workOrder): void
+    {
+        // Only act when the status has just changed to "closed"
+        if (!$workOrder->wasChanged('status') || $workOrder->status !== 'closed') {
+            return;
+        }
+
+        $this->createMaintenanceRecord($workOrder);
+        $this->resetSchedule($workOrder);
+
+        event('work_order.completed', $workOrder);
+    }
+
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+
+    /**
+     * Create a Maintenance history record from the completed work order.
+     */
+    private function createMaintenanceRecord(WorkOrder $workOrder): void
+    {
+        // Avoid duplicate records if one was already manually created for this WO
+        if (Maintenance::where('work_order_uuid', $workOrder->uuid)->exists()) {
+            return;
+        }
+
+        $meta           = $workOrder->meta ?? [];
+        $completionData = $meta['completion_data'] ?? [];
+
+        Maintenance::create([
+            'company_uuid'       => $workOrder->company_uuid,
+            'work_order_uuid'    => $workOrder->uuid,
+            'maintainable_type'  => $workOrder->target_type,
+            'maintainable_uuid'  => $workOrder->target_uuid,
+            'type'               => 'scheduled',
+            'status'             => 'done',
+            'priority'           => $workOrder->priority,
+            'scheduled_at'       => $workOrder->opened_at,
+            'completed_at'       => $workOrder->closed_at ?? now(),
+            'performed_by_type'  => $workOrder->assignee_type,
+            'performed_by_uuid'  => $workOrder->assignee_uuid,
+            'summary'            => $workOrder->subject,
+            'notes'              => $completionData['notes'] ?? null,
+            'odometer'           => $completionData['odometer'] ?? null,
+            'engine_hours'       => $completionData['engine_hours'] ?? null,
+            'labor_cost'         => $completionData['labor_cost'] ?? null,
+            'parts_cost'         => $completionData['parts_cost'] ?? null,
+            'tax'                => $completionData['tax'] ?? null,
+            'total_cost'         => $completionData['total_cost'] ?? null,
+            'currency'           => $completionData['currency'] ?? null,
+            'line_items'         => $completionData['line_items'] ?? null,
+            'created_by_uuid'    => $workOrder->created_by_uuid,
+        ]);
+    }
+
+    /**
+     * Reset the linked schedule's next-due thresholds after completion.
+     */
+    private function resetSchedule(WorkOrder $workOrder): void
+    {
+        if (!$workOrder->schedule_uuid) {
+            return;
+        }
+
+        $schedule = MaintenanceSchedule::where('uuid', $workOrder->schedule_uuid)->first();
+        if (!$schedule) {
+            return;
+        }
+
+        $meta           = $workOrder->meta ?? [];
+        $completionData = $meta['completion_data'] ?? [];
+
+        $schedule->resetAfterCompletion(
+            odometer: isset($completionData['odometer']) ? (int) $completionData['odometer'] : null,
+            completedEngineHours: isset($completionData['engine_hours']) ? (int) $completionData['engine_hours'] : null,
+            completedAt: $workOrder->closed_at ?? now()
+        );
+    }
+}

package/server/src/Orchestration/Contracts/OrchestrationEngineInterface.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace Fleetbase\FleetOps\Orchestration\Contracts;
+
+use Illuminate\Support\Collection;
+
+/**
+ * OrchestrationEngineInterface.
+ *
+ * Defines the single contract that every orchestration/optimization engine must
+ * implement. The interface is intentionally minimal — engines receive a
+ * normalized set of jobs and vehicles and return a normalized result array.
+ * All engine-specific payload construction and response parsing is handled
+ * inside the concrete engine implementation, not by the caller.
+ *
+ * Third-party engines can be registered into the OrchestrationEngineRegistry
+ * from any Laravel service provider:
+ *
+ *   app(OrchestrationEngineRegistry::class)->register(new MyEngine());
+ *
+ * The registered engine will then appear in the FleetOps orchestrator settings
+ * dropdown automatically.
+ */
+interface OrchestrationEngineInterface
+{
+    /**
+     * Run the allocation/optimization algorithm.
+     *
+     * @param Collection $orders   collection of Order models to allocate
+     * @param Collection $vehicles collection of Vehicle models (with loaded driver)
+     * @param array      $options  Engine-specific options (e.g. max_travel_time,
+     *                             balance_workload, geometry). Keys are defined
+     *                             per-engine; unknown keys MUST be silently ignored.
+     *
+     * @return array{
+     *     assignments: array<array{order_id: string, vehicle_id: string, driver_id: string, sequence: int}>,
+     *     unassigned:  array<string>,
+     *     summary:     array<string, mixed>
+     * }
+     *
+     * The returned array MUST contain:
+     *   - assignments: ordered list of {order_id, vehicle_id, driver_id, sequence}
+     *   - unassigned:  list of order public_ids that could not be assigned
+     *   - summary:     engine-specific metadata (duration, distance, cost, etc.)
+     */
+    public function allocate(Collection $orders, Collection $vehicles, array $options = []): array;
+
+    /**
+     * Return the human-readable display name for this engine.
+     * Used in the settings UI dropdown.
+     *
+     * @return string e.g. "VROOM", "Google OR-Tools", "Custom Solver"
+     */
+    public function getName(): string;
+
+    /**
+     * Return the machine-readable identifier for this engine.
+     * Must be unique across all registered engines.
+     *
+     * @return string e.g. "vroom", "or-tools", "custom"
+     */
+    public function getIdentifier(): string;
+}