@fleetbase/fleetops-engine 0.6.48 → 0.6.50

package/server/src/Observers/ServiceRateObserver.php

@@ -14,10 +14,10 @@ class ServiceRateObserver
      */
     public function created(ServiceRate $serviceRate)
     {
-        $serviceRateFees       = request()->input('serviceRate.rate_fees');
-        $serviceRateParcelFees = request()->input('serviceRate.parcel_fees');
+        $serviceRateFees       = request()->input('serviceRate.rate_fees', request()->input('service_rate.rate_fees'));
+        $serviceRateParcelFees = request()->input('serviceRate.parcel_fees', request()->input('service_rate.parcel_fees'));
 
-        if ($serviceRate->isFixedMeter() || $serviceRate->isPerDrop()) {
+        if ($serviceRate->isFixedMeter() || $serviceRate->isPerDrop() || $serviceRate->isMultiZoneDistance()) {
             $serviceRate->setServiceRateFees($serviceRateFees);
         }
 
@@ -33,10 +33,10 @@ class ServiceRateObserver
      */
     public function updated(ServiceRate $serviceRate)
     {
-        $serviceRateFees       = request()->input('serviceRate.rate_fees');
-        $serviceRateParcelFees = request()->input('serviceRate.parcel_fees');
+        $serviceRateFees       = request()->input('serviceRate.rate_fees', request()->input('service_rate.rate_fees'));
+        $serviceRateParcelFees = request()->input('serviceRate.parcel_fees', request()->input('service_rate.parcel_fees'));
 
-        if ($serviceRate->isFixedMeter() || $serviceRate->isPerDrop()) {
+        if ($serviceRate->isFixedMeter() || $serviceRate->isPerDrop() || $serviceRate->isMultiZoneDistance()) {
             $serviceRate->setServiceRateFees($serviceRateFees);
         }
 

package/server/src/Orchestration/Engines/VroomOrchestrationEngine.php

@@ -85,7 +85,7 @@ class VroomOrchestrationEngine implements OrchestrationEngineInterface
         $vroomPayload = [
             'jobs'      => [],
             'shipments' => [],
-            'vehicles' => array_map(function (array $v) use ($profile) {
+            'vehicles'  => array_map(function (array $v) use ($profile) {
                 $vehicle = [
                     'id'          => crc32($v['id']), // VROOM requires integer IDs
                     'description' => json_encode(['vehicle_id' => $v['id'], 'driver_id' => $v['driver_id']]),
@@ -171,12 +171,17 @@ class VroomOrchestrationEngine implements OrchestrationEngineInterface
         $vroomPayload = $this->buildCapacityOnlyPayload($capacityTasks, $vroomVehicles, $options, $jobIdReverse);
 
         if (empty($vroomPayload['vehicles'])) {
+            $vehiclePacking   = $this->resolveVehiclePacking($options);
+            $vehicleFixedCost = $this->resolveVehicleFixedCost($options);
+
             return $this->mergeInvalidTasks([
                 'assignments' => [],
                 'unassigned'  => array_column($capacityTasks, 'id'),
                 'summary'     => [
                     'engine'              => 'vroom',
                     'allocation_strategy' => 'capacity_only',
+                    'vehicle_packing'     => $vehiclePacking,
+                    'vehicle_fixed_cost'  => $vehiclePacking === 'minimize_vehicles' ? $vehicleFixedCost : null,
                     'assigned'            => 0,
                     'unassigned'          => count($capacityTasks),
                     'unassigned_reasons'  => array_map(fn (array $task) => [
@@ -192,6 +197,8 @@ class VroomOrchestrationEngine implements OrchestrationEngineInterface
         $result['summary'] = array_merge($result['summary'] ?? [], [
             'engine'              => 'vroom',
             'allocation_strategy' => 'capacity_only',
+            'vehicle_packing'     => $this->resolveVehiclePacking($options),
+            'vehicle_fixed_cost'  => $this->resolveVehiclePacking($options) === 'minimize_vehicles' ? $this->resolveVehicleFixedCost($options) : null,
         ]);
 
         return $this->mergeInvalidTasks($result, $invalidTasks);
@@ -203,10 +210,12 @@ class VroomOrchestrationEngine implements OrchestrationEngineInterface
         $profile         = $options['profile'] ?? 'capacity_only';
         $respectCapacity = (bool) ($options['respect_capacity'] ?? true);
         $respectSkills   = (bool) ($options['respect_skills'] ?? true);
+        $vehiclePacking  = $this->resolveVehiclePacking($options);
+        $fixedCost       = $this->resolveVehicleFixedCost($options);
 
         $vroomPayload = [
             'jobs'     => [],
-            'vehicles' => array_map(function (array $v) use ($profile, $respectCapacity, $respectSkills) {
+            'vehicles' => array_map(function (array $v) use ($profile, $respectCapacity, $respectSkills, $vehiclePacking, $fixedCost) {
                 $vehicle = [
                     'id'          => crc32($v['id']),
                     'description' => json_encode(['vehicle_id' => $v['id'], 'driver_id' => $v['driver_id'] ?? null]),
@@ -214,6 +223,10 @@ class VroomOrchestrationEngine implements OrchestrationEngineInterface
                     'start_index' => 0,
                 ];
 
+                if ($vehiclePacking === 'minimize_vehicles') {
+                    $vehicle['costs'] = ['fixed' => $fixedCost];
+                }
+
                 if ($respectCapacity) {
                     $vehicle['capacity'] = $v['capacity'];
                 }
@@ -265,6 +278,20 @@ class VroomOrchestrationEngine implements OrchestrationEngineInterface
         return $vroomPayload;
     }
 
+    protected function resolveVehiclePacking(array $options): string
+    {
+        $packing = strtolower((string) ($options['vehicle_packing'] ?? 'minimize_vehicles'));
+
+        return in_array($packing, ['minimize_vehicles', 'balanced', 'none'], true)
+            ? $packing
+            : 'minimize_vehicles';
+    }
+
+    protected function resolveVehicleFixedCost(array $options): int
+    {
+        return max(0, (int) ($options['vehicle_fixed_cost'] ?? 100000));
+    }
+
     protected function buildUniformMatrix(int $size): array
     {
         $matrix = [];

package/server/src/Providers/FleetOpsServiceProvider.php

@@ -56,6 +56,7 @@ class FleetOpsServiceProvider extends CoreServiceProvider
         \Fleetbase\FleetOps\Console\Commands\FixInvalidPolymorphicRelationTypeNamespaces::class,
         \Fleetbase\FleetOps\Console\Commands\AssignDriverRoles::class,
         \Fleetbase\FleetOps\Console\Commands\AssignCustomerRoles::class,
+        \Fleetbase\FleetOps\Console\Commands\AuditCustomerUserConflicts::class,
         \Fleetbase\FleetOps\Console\Commands\SimulateOrderRouteNavigation::class,
         \Fleetbase\FleetOps\Console\Commands\DebugOrderTracker::class,
         \Fleetbase\FleetOps\Console\Commands\PurgeUnpurchasedServiceQuotes::class,
@@ -65,6 +66,7 @@ class FleetOpsServiceProvider extends CoreServiceProvider
         \Fleetbase\FleetOps\Console\Commands\TestEmail::class,
         \Fleetbase\FleetOps\Console\Commands\ProcessMaintenanceTriggers::class,
         \Fleetbase\FleetOps\Console\Commands\SendMaintenanceReminders::class,
+        \Fleetbase\FleetOps\Console\Commands\ProcessOperationalAlerts::class,
     ];
 
     /**
@@ -126,6 +128,7 @@ class FleetOpsServiceProvider extends CoreServiceProvider
             $schedule->command('fleetops:purge-service-quotes')->daily()->withoutOverlapping();
             $schedule->command('fleetops:process-maintenance-triggers')->daily()->withoutOverlapping()->storeOutputInDb();
             $schedule->command('fleetops:send-maintenance-reminders')->daily()->withoutOverlapping()->storeOutputInDb();
+            $schedule->command('fleetops:process-operational-alerts')->everyMinute()->withoutOverlapping()->storeOutputInDb();
         });
         $this->registerNotifications();
         $this->registerExpansionsFrom(__DIR__ . '/../Expansions');
@@ -192,6 +195,9 @@ class FleetOpsServiceProvider extends CoreServiceProvider
             \Fleetbase\FleetOps\Notifications\OrderFailed::class,
             \Fleetbase\FleetOps\Notifications\OrderCompleted::class,
             \Fleetbase\FleetOps\Notifications\DriverArrivedAtGeofence::class,
+            \Fleetbase\FleetOps\Notifications\LateDeparture::class,
+            \Fleetbase\FleetOps\Notifications\RouteDeviation::class,
+            \Fleetbase\FleetOps\Notifications\ProlongedStoppage::class,
         ]);
 
         // Register Notifiables

package/server/src/Providers/NotificationServiceProvider.php

@@ -31,6 +31,9 @@ class NotificationServiceProvider extends CoreServiceProvider
             \Fleetbase\FleetOps\Notifications\OrderDispatched::class,
             \Fleetbase\FleetOps\Notifications\OrderDispatchFailed::class,
             \Fleetbase\FleetOps\Notifications\OrderPing::class,
+            \Fleetbase\FleetOps\Notifications\LateDeparture::class,
+            \Fleetbase\FleetOps\Notifications\RouteDeviation::class,
+            \Fleetbase\FleetOps\Notifications\ProlongedStoppage::class,
         ]);
 
         // Register Notifiables

package/server/src/Support/Analytics/AbstractAnalytics.php

@@ -0,0 +1,77 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Analytics;
+
+use Fleetbase\Models\Company;
+use Illuminate\Support\Carbon;
+
+/**
+ * Base for analytics-widget data providers. Unlike scalar Metrics, each
+ * subclass returns a widget-specific JSON shape (Chart.js datasets, ranked
+ * rows, scalar tiles, map points, etc.) so the base just provides company
+ * scoping + period parsing.
+ */
+abstract class AbstractAnalytics
+{
+    protected Company $company;
+    protected ?\DateTimeInterface $start = null;
+    protected ?\DateTimeInterface $end   = null;
+
+    abstract public function get(): array;
+
+    public static function forCompany(Company $company): static
+    {
+        return (new static())->setCompany($company);
+    }
+
+    public function between(?\DateTimeInterface $start, ?\DateTimeInterface $end): static
+    {
+        $this->start = $start;
+        $this->end   = $end;
+
+        return $this;
+    }
+
+    /**
+     * Resolve a [start, end] tuple from a `period` shorthand or explicit dates,
+     * falling back to a 30-day window. Shared by every analytics call.
+     */
+    public static function resolvePeriod(?string $period, ?\DateTimeInterface $start, ?\DateTimeInterface $end, int $defaultDays = 30): array
+    {
+        if ($period !== null && $period !== '') {
+            $days = match ($period) {
+                '7d'    => 7,
+                '14d'   => 14,
+                '30d'   => 30,
+                '90d'   => 90,
+                '180d'  => 180,
+                '365d'  => 365,
+                default => null,
+            };
+
+            if ($days !== null) {
+                return [
+                    Carbon::now()->subDays($days)->toDateTime(),
+                    Carbon::now()->toDateTime(),
+                ];
+            }
+        }
+
+        return [
+            $start ?? Carbon::now()->subDays($defaultDays)->toDateTime(),
+            $end ?? Carbon::now()->toDateTime(),
+        ];
+    }
+
+    protected function setCompany(Company $company): static
+    {
+        $this->company = $company;
+
+        return $this;
+    }
+
+    protected function companyCurrency(): string
+    {
+        return $this->company->currency ?? 'USD';
+    }
+}

package/server/src/Support/Analytics/FuelEfficiency.php

@@ -0,0 +1,83 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Analytics;
+
+use Fleetbase\FleetOps\Models\FuelReport;
+use Fleetbase\FleetOps\Models\Order;
+use Illuminate\Support\Carbon;
+
+/**
+ * Dual-axis fuel chart: weekly total cost (bars) + cost-per-km (line).
+ * Cost-per-km is sum(FuelReport.amount in primary currency) divided by
+ * sum(Order.distance, in km) for that bucket.
+ */
+class FuelEfficiency extends AbstractAnalytics
+{
+    public function get(): array
+    {
+        $currency = $this->companyCurrency();
+        $start    = $this->start ?? Carbon::now()->subDays(90)->toDateTime();
+        $end      = $this->end ?? Carbon::now()->toDateTime();
+
+        $fuelByWeek = FuelReport::where('company_uuid', $this->company->uuid)
+            ->where('currency', $currency)
+            ->whereBetween('created_at', [$start, $end])
+            ->selectRaw('YEARWEEK(created_at, 1) as wk, MIN(DATE(created_at)) as wk_start, SUM(amount) as total_cost')
+            ->groupBy('wk')
+            ->orderBy('wk')
+            ->get();
+
+        $distanceByWeek = Order::where('company_uuid', $this->company->uuid)
+            ->where('status', 'completed')
+            ->whereBetween('updated_at', [$start, $end])
+            ->selectRaw('YEARWEEK(updated_at, 1) as wk, SUM(distance) as total_distance')
+            ->groupBy('wk')
+            ->orderBy('wk')
+            ->pluck('total_distance', 'wk');
+
+        $labels    = [];
+        $costData  = [];
+        $cpkmData  = [];
+
+        foreach ($fuelByWeek as $row) {
+            $labels[]   = Carbon::parse($row->wk_start)->format('M j');
+            $cost       = (float) $row->total_cost;
+            $distanceM  = (float) ($distanceByWeek[$row->wk] ?? 0);
+            $distanceKm = $distanceM / 1000.0;
+            $costData[] = round($cost, 2);
+            $cpkmData[] = $distanceKm > 0 ? round($cost / $distanceKm, 3) : null;
+        }
+
+        $totalCost      = array_sum($costData);
+        $totalDistanceM = array_sum($distanceByWeek->all());
+        $avgCostPerKm   = $totalDistanceM > 0
+            ? round($totalCost / ($totalDistanceM / 1000.0), 3)
+            : 0.0;
+
+        return [
+            'labels'   => $labels,
+            'datasets' => [
+                [
+                    'type'            => 'bar',
+                    'label'           => 'Fuel Cost',
+                    'data'            => $costData,
+                    'yAxisID'         => 'y1',
+                    'backgroundColor' => '#3485e2',
+                ],
+                [
+                    'type'        => 'line',
+                    'label'       => 'Cost per km',
+                    'data'        => $cpkmData,
+                    'yAxisID'     => 'y2',
+                    'borderColor' => '#f59e0b',
+                    'tension'     => 0.3,
+                ],
+            ],
+            'summary' => [
+                'total_cost'       => round($totalCost, 2),
+                'currency'         => $currency,
+                'avg_cost_per_km'  => $avgCostPerKm,
+            ],
+        ];
+    }
+}

package/server/src/Support/Analytics/GeofenceViolations.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Analytics;
+
+use Fleetbase\FleetOps\Models\GeofenceEventLog;
+use Illuminate\Support\Carbon;
+
+/**
+ * Geofence dwell + violation summary. Today's violation count, period total,
+ * top-N dwell outliers (driver × zone × duration), and a bar chart of events
+ * by zone.
+ */
+class GeofenceViolations extends AbstractAnalytics
+{
+    public function get(): array
+    {
+        $companyUuid = $this->company->uuid;
+        $start       = $this->start ?? Carbon::now()->subDays(7)->toDateTime();
+        $end         = $this->end ?? Carbon::now()->toDateTime();
+
+        $violationsToday = GeofenceEventLog::where('company_uuid', $companyUuid)
+            ->where('event_type', 'dwelled')
+            ->whereDate('occurred_at', Carbon::today())
+            ->count();
+
+        $violationsPeriod = GeofenceEventLog::where('company_uuid', $companyUuid)
+            ->where('event_type', 'dwelled')
+            ->whereBetween('occurred_at', [$start, $end])
+            ->count();
+
+        $topDwells = GeofenceEventLog::where('company_uuid', $companyUuid)
+            ->where('event_type', 'dwelled')
+            ->whereBetween('occurred_at', [$start, $end])
+            ->whereNotNull('dwell_duration_minutes')
+            ->orderByDesc('dwell_duration_minutes')
+            ->limit(8)
+            ->get(['subject_name', 'driver_uuid', 'geofence_name', 'dwell_duration_minutes', 'occurred_at']);
+
+        $byZoneRows = GeofenceEventLog::where('company_uuid', $companyUuid)
+            ->whereBetween('occurred_at', [$start, $end])
+            ->selectRaw('geofence_name, COUNT(*) as total')
+            ->groupBy('geofence_name')
+            ->orderByRaw('total DESC')
+            ->limit(8)
+            ->get();
+
+        return [
+            'violations_today'  => $violationsToday,
+            'violations_period' => $violationsPeriod,
+            'top_dwells'        => $topDwells->map(fn ($e) => [
+                'driver_uuid'      => $e->driver_uuid,
+                'driver_name'      => $e->subject_name,
+                'zone_name'        => $e->geofence_name,
+                'duration_minutes' => (int) $e->dwell_duration_minutes,
+                'occurred_at'      => $e->occurred_at,
+            ])->all(),
+            'by_zone' => [
+                'labels' => $byZoneRows->pluck('geofence_name')->map(fn ($n) => $n ?: 'Unnamed')->all(),
+                'data'   => $byZoneRows->pluck('total')->map(fn ($v) => (int) $v)->all(),
+            ],
+        ];
+    }
+}

package/server/src/Support/Analytics/IssuesInsights.php

@@ -0,0 +1,67 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Analytics;
+
+use Fleetbase\FleetOps\Models\Issue;
+use Illuminate\Support\Carbon;
+
+/**
+ * Issues breakdown: category pie, priority histogram, open vs resolved counts,
+ * and average resolution time (hours).
+ */
+class IssuesInsights extends AbstractAnalytics
+{
+    public function get(): array
+    {
+        $companyUuid = $this->company->uuid;
+        $start       = $this->start ?? Carbon::now()->subDays(30)->toDateTime();
+        $end         = $this->end ?? Carbon::now()->toDateTime();
+
+        $byCategory = Issue::where('company_uuid', $companyUuid)
+            ->whereBetween('created_at', [$start, $end])
+            ->selectRaw('category, COUNT(*) as total')
+            ->groupBy('category')
+            ->orderByRaw('total DESC')
+            ->get();
+
+        $byPriority = Issue::where('company_uuid', $companyUuid)
+            ->whereBetween('created_at', [$start, $end])
+            ->selectRaw('priority, COUNT(*) as total')
+            ->groupBy('priority')
+            ->pluck('total', 'priority');
+
+        $open = Issue::where('company_uuid', $companyUuid)
+            ->where('status', 'pending')
+            ->count();
+
+        $resolvedInWindow = Issue::where('company_uuid', $companyUuid)
+            ->whereNotNull('resolved_at')
+            ->whereBetween('resolved_at', [$start, $end])
+            ->get(['created_at', 'resolved_at']);
+
+        $totalHours = 0.0;
+        foreach ($resolvedInWindow as $issue) {
+            $totalHours += (Carbon::parse($issue->resolved_at)->getTimestamp()
+                          - Carbon::parse($issue->created_at)->getTimestamp()) / 3600;
+        }
+
+        $avgResolutionHours = $resolvedInWindow->count() > 0
+            ? round($totalHours / $resolvedInWindow->count(), 1)
+            : null;
+
+        return [
+            'by_category' => [
+                'labels' => $byCategory->pluck('category')->map(fn ($c) => $c ?: 'Uncategorized')->all(),
+                'data'   => $byCategory->pluck('total')->map(fn ($v) => (int) $v)->all(),
+            ],
+            'by_priority' => [
+                'high'   => (int) ($byPriority['high'] ?? 0),
+                'medium' => (int) ($byPriority['medium'] ?? 0),
+                'low'    => (int) ($byPriority['low'] ?? 0),
+            ],
+            'open'                   => $open,
+            'resolved_this_period'   => $resolvedInWindow->count(),
+            'avg_resolution_hours'   => $avgResolutionHours,
+        ];
+    }
+}

package/server/src/Support/Analytics/LiveFleet.php

@@ -0,0 +1,127 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Analytics;
+
+use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Support\Metrics\OrdersInProgressMetric;
+
+/**
+ * Real-time fleet snapshot used as the initial-state payload for Live Fleet Map.
+ * After this single GET the frontend subscribes to `company.{uuid}` and applies
+ * `driver.location_changed` / `order.*` events incrementally instead of polling.
+ *
+ * Reads from `Driver.location` and `Vehicle.location` directly — does NOT scan the
+ * high-frequency Position table.
+ */
+class LiveFleet extends AbstractAnalytics
+{
+    public function get(): array
+    {
+        $companyUuid = $this->company->uuid;
+
+        // Driver.name is a virtual attribute backed by users.name — eager-load the
+        // user so the accessor resolves cleanly without a per-record query.
+        $drivers = Driver::with(['user:uuid,name,avatar_uuid'])
+            ->where('drivers.company_uuid', $companyUuid)
+            ->whereNotNull('drivers.location')
+            ->where(function ($q) {
+                $q->where('drivers.online', true)->orWhereNotNull('drivers.current_job_uuid');
+            })
+            ->get();
+
+        // Vehicles tracked independently of drivers (telematics-connected rigs may
+        // report position without an active driver session).
+        $vehicles = Vehicle::where('company_uuid', $companyUuid)
+            ->whereNotNull('location')
+            ->get();
+
+        $activeOrderUuids = $drivers->pluck('current_job_uuid')->filter()->unique()->values();
+
+        $activeOrders = Order::whereIn('uuid', $activeOrderUuids)
+            ->where('company_uuid', $companyUuid)
+            ->whereIn('status', OrdersInProgressMetric::IN_PROGRESS_STATUSES)
+            ->get(['uuid', 'driver_assigned_uuid', 'status', 'tracking_number_uuid']);
+
+        return [
+            'drivers' => $drivers->map(fn ($d) => $this->driverPayload($d))
+                ->filter(fn ($d) => $d['lat'] !== null && $d['lng'] !== null)
+                ->values()
+                ->all(),
+            'vehicles' => $vehicles->map(fn ($v) => $this->vehiclePayload($v))
+                ->filter(fn ($v) => $v['lat'] !== null && $v['lng'] !== null)
+                ->values()
+                ->all(),
+            'active_orders' => $activeOrders->map(fn ($o) => [
+                'uuid'        => $o->uuid,
+                'driver_uuid' => $o->driver_assigned_uuid,
+                'status'      => $o->status,
+            ])->all(),
+        ];
+    }
+
+    private function driverPayload(Driver $d): array
+    {
+        [$lat, $lng] = $this->extractLatLng($d->location);
+
+        return [
+            'uuid'               => $d->uuid,
+            'public_id'          => $d->public_id,
+            'name'               => $d->name,
+            // avatar_url falls back to vehicle avatar then a default;
+            // vehicle_avatar is what the operational live-map renders.
+            'avatar_url'         => $d->avatar_url,
+            'vehicle_avatar'     => $d->vehicle_avatar,
+            'online'             => (bool) $d->online,
+            'heading'            => (float) ($d->heading ?? 0),
+            'current_order_uuid' => $d->current_job_uuid,
+            'lat'                => $lat,
+            'lng'                => $lng,
+            'updated_at'         => $d->last_location_update_at,
+        ];
+    }
+
+    private function vehiclePayload(Vehicle $v): array
+    {
+        [$lat, $lng] = $this->extractLatLng($v->location);
+
+        return [
+            'uuid'         => $v->uuid,
+            'public_id'    => $v->public_id,
+            'name'         => $v->display_name,
+            'plate_number' => $v->plate_number,
+            'avatar_url'   => $v->avatar_url,
+            'photo_url'    => $v->photo_url,
+            'online'       => (bool) ($v->online ?? false),
+            'driver_name'  => $v->driver_name,
+            'heading'      => (float) ($v->heading ?? 0),
+            'lat'          => $lat,
+            'lng'          => $lng,
+        ];
+    }
+
+    /**
+     * Pull [lat, lng] out of whatever shape the spatial accessor handed us.
+     * Supports Point objects, [lat, lng] arrays, and {lat, lng} hashes.
+     *
+     * @return array{0:float|null,1:float|null}
+     */
+    private function extractLatLng($location): array
+    {
+        if (is_object($location) && method_exists($location, 'getLat')) {
+            return [$location->getLat(), $location->getLng()];
+        }
+
+        if (is_array($location)) {
+            // Point::toArray usually returns ['lat' => ..., 'lng' => ...] but
+            // GeoJSON-shape `coordinates` is [lng, lat]; handle both.
+            return [
+                $location['lat'] ?? $location[1] ?? null,
+                $location['lng'] ?? $location[0] ?? null,
+            ];
+        }
+
+        return [null, null];
+    }
+}

package/server/src/Support/Analytics/MaintenanceOverview.php

@@ -0,0 +1,70 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Analytics;
+
+use Fleetbase\FleetOps\Models\Maintenance;
+use Illuminate\Support\Carbon;
+
+/**
+ * Maintenance summary: overdue count, next-7-day schedule, in-progress count,
+ * month-to-date and year-to-date spend, plus a short list of upcoming items.
+ */
+class MaintenanceOverview extends AbstractAnalytics
+{
+    public function get(): array
+    {
+        $companyUuid = $this->company->uuid;
+        $currency    = $this->companyCurrency();
+        $now         = Carbon::now();
+
+        $overdue = Maintenance::where('company_uuid', $companyUuid)
+            ->where('scheduled_at', '<', $now)
+            ->where('status', '!=', 'completed')
+            ->where('status', '!=', 'canceled')
+            ->count();
+
+        $next7d = Maintenance::where('company_uuid', $companyUuid)
+            ->whereBetween('scheduled_at', [$now, $now->copy()->addDays(7)])
+            ->whereIn('status', ['scheduled', 'pending'])
+            ->count();
+
+        $inProgress = Maintenance::where('company_uuid', $companyUuid)
+            ->where('status', 'in_progress')
+            ->count();
+
+        $costThisMonth = (float) Maintenance::where('company_uuid', $companyUuid)
+            ->where('currency', $currency)
+            ->where('status', 'completed')
+            ->whereBetween('completed_at', [$now->copy()->startOfMonth(), $now])
+            ->sum('total_cost');
+
+        $costYtd = (float) Maintenance::where('company_uuid', $companyUuid)
+            ->where('currency', $currency)
+            ->where('status', 'completed')
+            ->whereBetween('completed_at', [$now->copy()->startOfYear(), $now])
+            ->sum('total_cost');
+
+        $upcoming = Maintenance::where('company_uuid', $companyUuid)
+            ->whereIn('status', ['scheduled', 'pending'])
+            ->whereNotNull('scheduled_at')
+            ->where('scheduled_at', '>=', $now)
+            ->orderBy('scheduled_at', 'asc')
+            ->limit(8)
+            ->get(['uuid', 'maintainable_uuid', 'maintainable_type', 'type', 'priority', 'scheduled_at']);
+
+        return [
+            'overdue'           => $overdue,
+            'scheduled_next_7d' => $next7d,
+            'in_progress'       => $inProgress,
+            'cost_this_month'   => round($costThisMonth, 2),
+            'cost_ytd'          => round($costYtd, 2),
+            'currency'          => $currency,
+            'upcoming'          => $upcoming->map(fn ($m) => [
+                'uuid'         => $m->uuid,
+                'type'         => $m->type,
+                'priority'     => $m->priority,
+                'scheduled_at' => $m->scheduled_at,
+            ])->all(),
+        ];
+    }
+}