@fleetbase/fleetops-engine 0.6.37 → 0.6.39

package/server/src/Auth/Schemas/FleetOps.php

@@ -113,6 +113,22 @@ class FleetOps
             'name'    => 'issue',
             'actions' => ['export', 'import'],
         ],
+        [
+            'name'    => 'maintenance',
+            'actions' => ['export', 'import'],
+        ],
+        [
+            'name'    => 'work-order',
+            'actions' => ['export', 'import'],
+        ],
+        [
+            'name'    => 'equipment',
+            'actions' => ['export', 'import'],
+        ],
+        [
+            'name'    => 'part',
+            'actions' => ['export', 'import'],
+        ],
         [
             'name'    => 'custom-field',
             'actions' => [],
@@ -264,6 +280,23 @@ class FleetOps
                 'list order',
             ],
         ],
+        [
+            'name'        => 'MaintenanceManager',
+            'description' => 'Policy for managing maintenance records, work orders, equipment, and parts.',
+            'permissions' => [
+                'see extension',
+                '* maintenance',
+                '* work-order',
+                '* equipment',
+                '* part',
+                'see vehicle',
+                'list vehicle',
+                'view vehicle',
+                'see driver',
+                'list driver',
+                'view driver',
+            ],
+        ],
         [
             'name'        => 'OperationsAdmin',
             'description' => 'Policy for monitoring activities, issues, and fuel reports within the fleet operations.',
@@ -276,6 +309,10 @@ class FleetOps
                 '* fuel-report',
                 '* issue',
                 '* place',
+                '* maintenance',
+                '* work-order',
+                '* equipment',
+                '* part',
             ],
         ],
         [
@@ -370,6 +407,13 @@ class FleetOps
                 'OperationsAdmin',
             ],
         ],
+        [
+            'name'        => 'Maintenance Technician',
+            'description' => 'Role for technicians responsible for managing maintenance records, work orders, equipment, and parts inventory.',
+            'policies'    => [
+                'MaintenanceManager',
+            ],
+        ],
         [
             'name'        => 'Driver Coordinator',
             'description' => 'Role responsible for coordinating drivers, vehicles, and orders.',

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

@@ -0,0 +1,150 @@
+<?php
+
+namespace Fleetbase\FleetOps\Console\Commands;
+
+use Carbon\Carbon;
+use Fleetbase\FleetOps\Models\MaintenanceSchedule;
+use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Models\WorkOrder;
+use Illuminate\Console\Command;
+
+/**
+ * ProcessMaintenanceTriggers.
+ *
+ * Scans all active MaintenanceSchedule records and determines whether a
+ * preventive maintenance work order should be created based on:
+ *
+ *  - Time/date thresholds  (next_due_date)
+ *  - Odometer thresholds   (next_due_odometer vs. current vehicle odometer)
+ *  - Engine-hour thresholds (next_due_engine_hours vs. current engine hours)
+ *
+ * When a schedule is triggered, a WorkOrder is automatically created from the
+ * schedule's default settings and a `maintenance.triggered` event is dispatched.
+ *
+ * Designed to run on a scheduled basis (e.g. daily via the Laravel scheduler).
+ */
+class ProcessMaintenanceTriggers extends Command
+{
+    /**
+     * The name and signature of the console command.
+     *
+     * @var string
+     */
+    protected $signature = 'fleetops:process-maintenance-triggers
+                            {--sandbox : Run in sandbox database mode}
+                            {--dry-run : Report triggers without creating work orders}';
+
+    /**
+     * The console command description.
+     *
+     * @var string
+     */
+    protected $description = 'Process preventive maintenance schedule triggers and auto-create work orders';
+
+    /**
+     * Execute the console command.
+     */
+    public function handle(): void
+    {
+        date_default_timezone_set('UTC');
+
+        $sandbox = (bool) $this->option('sandbox');
+        $dryRun  = (bool) $this->option('dry-run');
+        $conn    = $sandbox ? 'sandbox' : 'mysql';
+
+        $this->info('Processing maintenance schedule triggers' . ($dryRun ? ' [DRY RUN]' : '') . ' at ' . Carbon::now()->toDateTimeString());
+
+        $triggered = 0;
+
+        // ------------------------------------------------------------------
+        // Load all active schedules that have at least one threshold set
+        // ------------------------------------------------------------------
+        $schedules = MaintenanceSchedule::on($conn)
+            ->withoutGlobalScopes()
+            ->where('status', 'active')
+            ->where(function ($q) {
+                $q->whereNotNull('next_due_date')
+                  ->orWhereNotNull('next_due_odometer')
+                  ->orWhereNotNull('next_due_engine_hours');
+            })
+            ->whereNull('deleted_at')
+            ->with('subject')
+            ->get();
+
+        foreach ($schedules as $schedule) {
+            $subject         = $schedule->subject;
+            $currentOdometer = null;
+            $currentEngHours = null;
+
+            // Resolve current readings from the subject asset if it is a vehicle
+            if ($subject instanceof Vehicle) {
+                $currentOdometer = $subject->odometer;
+                $currentEngHours = $subject->engine_hours;
+            }
+
+            if (!$schedule->isDue($currentOdometer, $currentEngHours)) {
+                continue;
+            }
+
+            // Build a human-readable reason string for logging
+            $reasons = [];
+            if ($schedule->next_due_date && now()->gte($schedule->next_due_date)) {
+                $reasons[] = 'date due ' . $schedule->next_due_date->toDateString();
+            }
+            if ($schedule->next_due_odometer && $currentOdometer !== null && $currentOdometer >= $schedule->next_due_odometer) {
+                $reasons[] = "odometer {$currentOdometer} >= {$schedule->next_due_odometer}";
+            }
+            if ($schedule->next_due_engine_hours && $currentEngHours !== null && $currentEngHours >= $schedule->next_due_engine_hours) {
+                $reasons[] = "engine hours {$currentEngHours} >= {$schedule->next_due_engine_hours}";
+            }
+
+            $this->line("Triggered: schedule {$schedule->public_id} ({$schedule->name}) — " . implode(', ', $reasons));
+
+            if (!$dryRun) {
+                // Check if a pending work order already exists for this schedule
+                // to avoid duplicates on repeated runs before the WO is completed
+                $existingOpen = WorkOrder::on($conn)
+                    ->withoutGlobalScopes()
+                    ->where('schedule_uuid', $schedule->uuid)
+                    ->whereIn('status', ['open', 'in_progress'])
+                    ->whereNull('deleted_at')
+                    ->exists();
+
+                if ($existingOpen) {
+                    $this->line('  → Skipped: open work order already exists for this schedule.');
+                    continue;
+                }
+
+                // Auto-generate a work order from the schedule defaults
+                // Generate a sequential WO code: WO-YYYYMMDD-XXXX
+                $woCount = WorkOrder::on($conn)->withoutGlobalScopes()->whereNull('deleted_at')->count() + 1;
+                $woCode  = 'WO-' . now()->format('Ymd') . '-' . str_pad($woCount, 4, '0', STR_PAD_LEFT);
+
+                $workOrder = WorkOrder::on($conn)->create([
+                    'company_uuid'    => $schedule->company_uuid,
+                    'schedule_uuid'   => $schedule->uuid,
+                    'subject'         => $schedule->name,
+                    'code'            => $woCode,
+                    'status'          => 'open',
+                    'priority'        => $schedule->default_priority ?? 'normal',
+                    'target_type'     => $schedule->subject_type,
+                    'target_uuid'     => $schedule->subject_uuid,
+                    'assignee_type'   => $schedule->default_assignee_type,
+                    'assignee_uuid'   => $schedule->default_assignee_uuid,
+                    'instructions'    => $schedule->instructions,
+                    'due_at'          => $schedule->next_due_date,
+                    'opened_at'       => now(),
+                    'created_by_uuid' => null, // system-generated
+                ]);
+
+                $this->line("  → Created work order {$workOrder->public_id}");
+
+                event('maintenance.triggered', [$schedule, $workOrder]);
+            }
+
+            $triggered++;
+        }
+
+        $this->info("Processed {$triggered} schedule trigger(s)" . ($dryRun ? ' (dry run — no work orders created)' : '.'));
+    }
+}

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

@@ -0,0 +1,128 @@
+<?php
+
+namespace Fleetbase\FleetOps\Console\Commands;
+
+use Fleetbase\FleetOps\Mail\MaintenanceScheduleReminder;
+use Fleetbase\FleetOps\Models\MaintenanceSchedule;
+use Illuminate\Console\Command;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Mail;
+
+/**
+ * Sends reminder emails for upcoming maintenance schedules.
+ *
+ * Runs daily. For each active schedule that has reminder_offsets configured,
+ * it checks whether any offset threshold has been crossed (i.e. today is within
+ * N days of next_due_date) and — if no reminder has already been sent for that
+ * offset + due-date combination — sends a MaintenanceScheduleReminder email to
+ * the default assignee and records the send in maintenance_schedule_reminders.
+ */
+class SendMaintenanceReminders extends Command
+{
+    /**
+     * The name and signature of the console command.
+     *
+     * @var string
+     */
+    protected $signature = 'fleetops:send-maintenance-reminders
+                            {--sandbox : Run against the sandbox database connection}
+                            {--dry-run : Log which emails would be sent without actually sending}';
+
+    /**
+     * The console command description.
+     *
+     * @var string
+     */
+    protected $description = 'Send reminder emails for maintenance schedules that are approaching their due date';
+
+    /**
+     * Execute the console command.
+     */
+    public function handle(): void
+    {
+        date_default_timezone_set('UTC');
+        $sandbox = (bool) $this->option('sandbox');
+        $dryRun  = (bool) $this->option('dry-run');
+        $conn    = $sandbox ? 'sandbox' : 'mysql';
+
+        $this->info('Sending maintenance schedule reminders' . ($dryRun ? ' [DRY RUN]' : '') . ' at ' . Carbon::now()->toDateTimeString());
+
+        $sent = 0;
+
+        // Load all active schedules that have:
+        //   - a non-null next_due_date (reminders are date-based only)
+        //   - a non-null reminder_offsets JSON array
+        //   - a default_assignee configured
+        $schedules = MaintenanceSchedule::on($conn)
+            ->withoutGlobalScopes()
+            ->where('status', 'active')
+            ->whereNotNull('next_due_date')
+            ->whereNotNull('reminder_offsets')
+            ->whereNotNull('default_assignee_uuid')
+            ->whereNull('deleted_at')
+            ->with(['subject', 'defaultAssignee'])
+            ->get();
+
+        foreach ($schedules as $schedule) {
+            $offsets     = $schedule->reminder_offsets;
+            $nextDueDate = $schedule->next_due_date;
+
+            if (empty($offsets) || !$nextDueDate) {
+                continue;
+            }
+
+            // Resolve the recipient email from the polymorphic defaultAssignee
+            $assignee = $schedule->defaultAssignee;
+            $email    = $assignee?->email ?? null;
+
+            if (!$email) {
+                $this->line("  → Skipped schedule {$schedule->public_id}: no email on default assignee.");
+                continue;
+            }
+
+            $dueDateSnapshot = $nextDueDate->toDateString();
+
+            foreach ($offsets as $offsetDays) {
+                $offsetDays = (int) $offsetDays;
+
+                // The reminder window: today must be on or after (due_date - offset_days)
+                $reminderDate = $nextDueDate->copy()->subDays($offsetDays);
+
+                if (Carbon::today()->lt($reminderDate)) {
+                    // Not yet within the reminder window for this offset
+                    continue;
+                }
+
+                // Check whether we already sent this reminder for this cycle
+                $alreadySent = DB::connection($conn)
+                    ->table('maintenance_schedule_reminders')
+                    ->where('schedule_uuid', $schedule->uuid)
+                    ->where('offset_days', $offsetDays)
+                    ->where('due_date_snapshot', $dueDateSnapshot)
+                    ->exists();
+
+                if ($alreadySent) {
+                    continue;
+                }
+
+                $this->line("Sending reminder: schedule {$schedule->public_id} ({$schedule->name}) — {$offsetDays} days before {$dueDateSnapshot} → {$email}");
+
+                if (!$dryRun) {
+                    Mail::to($email)->send(new MaintenanceScheduleReminder($schedule, $offsetDays));
+
+                    DB::connection($conn)->table('maintenance_schedule_reminders')->insert([
+                        'schedule_uuid'     => $schedule->uuid,
+                        'offset_days'       => $offsetDays,
+                        'due_date_snapshot' => $dueDateSnapshot,
+                        'sent_at'           => Carbon::now(),
+                    ]);
+                }
+
+                $sent++;
+            }
+        }
+
+        $this->info("Sent {$sent} reminder(s)" . ($dryRun ? ' (dry run — no emails sent)' : '.'));
+    }
+}

package/server/src/Http/Controllers/Internal/v1/DriverController.php

@@ -29,6 +29,7 @@ use Maatwebsite\Excel\Facades\Excel;
 
 class DriverController extends FleetOpsController
 {
+    use Traits\DriverSchedulingTrait;
     /**
      * The resource to query.
      *

package/server/src/Http/Controllers/Internal/v1/EquipmentController.php

@@ -3,6 +3,9 @@
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
+use Fleetbase\FleetOps\Imports\EquipmentImport;
+use Fleetbase\Http\Requests\ImportRequest;
+use Maatwebsite\Excel\Facades\Excel;
 
 class EquipmentController extends FleetOpsController
 {
@@ -12,4 +15,28 @@ class EquipmentController extends FleetOpsController
      * @var string
      */
     public $resource = 'equipment';
+
+    /**
+     * Process import files (excel, csv) into Equipment records.
+     *
+     * @return \Illuminate\Http\Response
+     */
+    public function import(ImportRequest $request)
+    {
+        $disk          = $request->input('disk', config('filesystems.default'));
+        $files         = $request->resolveFilesFromIds();
+        $importedCount = 0;
+
+        foreach ($files as $file) {
+            try {
+                $import = new EquipmentImport();
+                Excel::import($import, $file->path, $disk);
+                $importedCount += $import->imported;
+            } catch (\Throwable $e) {
+                return response()->error('Invalid file, unable to process.');
+            }
+        }
+
+        return response()->json(['status' => 'ok', 'message' => 'Import completed', 'imported' => $importedCount]);
+    }
 }

package/server/src/Http/Controllers/Internal/v1/LiveController.php

@@ -38,9 +38,16 @@ class LiveController extends Controller
                 ->applyDirectivesForPermissions('fleet-ops list order')
                 ->get();
 
-            // Loop through each order to get its current destination location
+            // Loop through each order to get its current destination location.
+            // Filter out null and 0,0 fallback coordinates — these are returned
+            // by getCurrentDestinationLocation() when an order has no dropoff or
+            // waypoint set, and would cause the location service to resolve to
+            // the ocean (0,0 = Gulf of Guinea).
             foreach ($orders as $order) {
-                $coordinates[] = $order->getCurrentDestinationLocation();
+                $location = $order->getCurrentDestinationLocation();
+                if ($location && !($location->getLat() == 0 && $location->getLng() == 0)) {
+                    $coordinates[] = $location;
+                }
             }
 
             return response()->json($coordinates);

package/server/src/Http/Controllers/Internal/v1/MaintenanceController.php

@@ -3,6 +3,12 @@
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
+use Fleetbase\FleetOps\Imports\MaintenanceImport;
+use Fleetbase\FleetOps\Models\Maintenance;
+use Fleetbase\Http\Requests\ImportRequest;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Maatwebsite\Excel\Facades\Excel;
 
 class MaintenanceController extends FleetOpsController
 {
@@ -12,4 +18,163 @@ class MaintenanceController extends FleetOpsController
      * @var string
      */
     public $resource = 'maintenance';
+
+    /**
+     * Eager-load polymorphic relationships after create so they appear in the API response.
+     * Called automatically by HasApiControllerBehavior::createRecord() via getControllerCallback.
+     */
+    public function onAfterCreate($request, Maintenance $record, array $input): void
+    {
+        $record->load(['maintainable', 'performedBy']);
+    }
+
+    /**
+     * Eager-load polymorphic relationships after update so they appear in the API response.
+     * Called automatically by HasApiControllerBehavior::updateRecord() via getControllerCallback.
+     */
+    public function onAfterUpdate($request, Maintenance $record, array $input): void
+    {
+        $record->load(['maintainable', 'performedBy']);
+    }
+
+    /**
+     * Eager-load polymorphic relationships when finding record so they appear in the API response.
+     * Called automatically by HasApiControllerBehavior::findRecord() via getControllerCallback.
+     */
+    public function onFindRecord($builder, $request): void
+    {
+        $builder->with(['maintainable', 'performedBy']);
+    }
+
+    /**
+     * Add a cost line item to a maintenance record.
+     * POST /maintenances/{id}/line-items.
+     */
+    public function addLineItem(string $id, Request $request): JsonResponse
+    {
+        $maintenance = Maintenance::where('uuid', $id)
+            ->orWhere('public_id', $id)
+            ->firstOrFail();
+
+        $validated = $request->validate([
+            'description' => 'required|string|max:255',
+            'quantity'    => 'required|numeric|min:0',
+            'unit_cost'   => 'required|integer|min:0',
+            'currency'    => 'nullable|string|size:3',
+        ]);
+
+        $maintenance->addLineItem($validated);
+        $maintenance->refresh();
+        $this->recalculateCosts($maintenance);
+
+        return response()->json([
+            'status'     => 'ok',
+            'line_items' => $maintenance->line_items,
+            'total_cost' => $maintenance->total_cost,
+        ]);
+    }
+
+    /**
+     * Update a cost line item on a maintenance record.
+     * PUT /maintenances/{id}/line-items/{index}.
+     */
+    public function updateLineItem(string $id, int $index, Request $request): JsonResponse
+    {
+        $maintenance = Maintenance::where('uuid', $id)
+            ->orWhere('public_id', $id)
+            ->firstOrFail();
+
+        $validated = $request->validate([
+            'description' => 'required|string|max:255',
+            'quantity'    => 'required|numeric|min:0',
+            'unit_cost'   => 'required|integer|min:0',
+            'currency'    => 'nullable|string|size:3',
+        ]);
+
+        $lineItems = $maintenance->line_items ?? [];
+
+        if (!isset($lineItems[$index])) {
+            return response()->json(['error' => 'Line item not found.'], 404);
+        }
+
+        $lineItems[$index] = array_merge($lineItems[$index], $validated, [
+            'updated_at' => now(),
+        ]);
+
+        $maintenance->update(['line_items' => $lineItems]);
+        $maintenance->refresh();
+        $this->recalculateCosts($maintenance);
+
+        return response()->json([
+            'status'     => 'ok',
+            'line_items' => $maintenance->line_items,
+            'total_cost' => $maintenance->total_cost,
+        ]);
+    }
+
+    /**
+     * Remove a cost line item from a maintenance record.
+     * DELETE /maintenances/{id}/line-items/{index}.
+     */
+    public function removeLineItem(string $id, int $index): JsonResponse
+    {
+        $maintenance = Maintenance::where('uuid', $id)
+            ->orWhere('public_id', $id)
+            ->firstOrFail();
+
+        if (!$maintenance->removeLineItem($index)) {
+            return response()->json(['error' => 'Line item not found.'], 404);
+        }
+
+        $maintenance->refresh();
+        $this->recalculateCosts($maintenance);
+
+        return response()->json([
+            'status'     => 'ok',
+            'line_items' => $maintenance->line_items,
+            'total_cost' => $maintenance->total_cost,
+        ]);
+    }
+
+    /**
+     * Process import files (excel, csv) into Maintenance records.
+     *
+     * @return \Illuminate\Http\Response
+     */
+    public function import(ImportRequest $request)
+    {
+        $disk          = $request->input('disk', config('filesystems.default'));
+        $files         = $request->resolveFilesFromIds();
+        $importedCount = 0;
+
+        foreach ($files as $file) {
+            try {
+                $import = new MaintenanceImport();
+                Excel::import($import, $file->path, $disk);
+                $importedCount += $import->imported;
+            } catch (\Throwable $e) {
+                return response()->error('Invalid file, unable to process.');
+            }
+        }
+
+        return response()->json(['status' => 'ok', 'message' => 'Import completed', 'imported' => $importedCount]);
+    }
+
+    /**
+     * Recalculate and persist parts_cost and total_cost derived from line_items.
+     * All monetary values are stored as integers (smallest currency unit, e.g. cents).
+     */
+    protected function recalculateCosts(Maintenance $maintenance): void
+    {
+        $lineItems = $maintenance->line_items ?? [];
+        $partsCost = (int) collect($lineItems)->sum(fn ($item) => ($item['quantity'] ?? 0) * ($item['unit_cost'] ?? 0));
+        $laborCost = (int) ($maintenance->labor_cost ?? 0);
+        $tax       = (int) ($maintenance->tax ?? 0);
+        $totalCost = $laborCost + $partsCost + $tax;
+
+        $maintenance->update([
+            'parts_cost' => $partsCost,
+            'total_cost' => $totalCost,
+        ]);
+    }
 }