@fleetbase/fleetops-engine 0.6.47 → 0.6.49

package/server/src/Orchestration/Support/OrchestrationPayloadBuilder.php

@@ -141,85 +141,243 @@ class OrchestrationPayloadBuilder
     }
 
     /**
-     * Build the normalized job list from a collection of Orders.
+     * Build normalized route tasks from Fleetbase orders.
      *
-     * Each job contains:
-     *   - id:            order public_id
-     *   - location:      [longitude, latitude] of the delivery destination
-     *   - pickup:        [longitude, latitude] of the pickup (for PDPTW shipments)
-     *   - service:       service time in seconds (waypoint.service_time → order meta → default 300)
-     *   - time_windows:  [[earliest_unix, latest_unix]] from order.time_window_start/end or scheduled_at
-     *   - skills:        integer skill codes from order.required_skills or custom fields
-     *   - amount:        multi-dimensional capacity demand [weight_kg, volume_litres, pallets, parcels]
-     *   - priority:      orchestrator_priority (0–100, higher = more important)
-     *   - description:   human-readable label for debugging
+     * Fleetbase orders must remain atomic during allocation. A task contains
+     * the full ordered stop list for the order, but engine adapters decide how
+     * much of that route shape their solver can safely model.
      */
-    public static function buildJobs(Collection $orders): array
+    public static function buildRouteTasks(Collection $orders): array
     {
         return $orders->map(function (Order $order) {
-            $payload     = $order->payload;
-            $destination = $payload?->dropoff ?? $payload?->waypoints?->last();
+            $candidates  = static::buildRouteStopCandidates($order);
+            $invalidStop = collect($candidates)->first(fn (array $stop) => !static::coordinatesFromPlace($stop['place'] ?? null));
+            $stops       = static::normalizeRouteStops($candidates);
+
+            if ($invalidStop) {
+                return [
+                    'id'          => $order->public_id,
+                    'description' => $order->public_id,
+                    'invalid'     => true,
+                    'reason'      => sprintf('Order %s stop is missing valid coordinates.', $invalidStop['role'] ?? 'route'),
+                    'stops'       => [],
+                ];
+            }
 
-            if (!$destination || !$destination->location) {
-                return null;
+            if (empty($stops)) {
+                return [
+                    'id'          => $order->public_id,
+                    'description' => $order->public_id,
+                    'invalid'     => true,
+                    'reason'      => 'Order has no routable pickup, dropoff, or waypoint coordinates.',
+                    'stops'       => [],
+                ];
             }
 
-            // --- Location ---
-            $job = [
+            $task = [
                 'id'          => $order->public_id,
-                'location'    => [$destination->location->getLng(), $destination->location->getLat()],
                 'description' => $order->public_id,
+                'stops'       => $stops,
+                'amount'      => static::computePayloadDemand($order),
+                'service'     => static::resolveServiceTime($order),
             ];
 
-            // Pickup location (for pickup-and-delivery problems)
-            $pickup = $payload?->pickup;
-            if ($pickup && $pickup->location) {
-                $job['pickup'] = [$pickup->location->getLng(), $pickup->location->getLat()];
-            }
-
-            // --- Service time ---
-            // Prefer waypoint-level service_time, then order meta, then default 300s
-            $waypointMarker = $payload?->waypointMarkers?->last();
-            $job['service'] = (int) (
-                $waypointMarker?->service_time
-                ?? $order->getMeta('service_time_seconds')
-                ?? 300
-            );
-
-            // --- Capacity demand ---
-            // Aggregated dynamically from payload entities; falls back to order meta.
-            $job['amount'] = static::computePayloadDemand($order);
-
-            // --- Time windows ---
-            // Prefer explicit orchestrator time_window columns, fall back to scheduled_at
             if ($order->time_window_start && $order->time_window_end) {
-                $job['time_windows'] = [[
+                $task['time_windows'] = [[
                     $order->time_window_start->timestamp,
                     $order->time_window_end->timestamp,
                 ]];
             } elseif ($order->scheduled_at) {
-                $start               = $order->scheduled_at->timestamp;
-                $end                 = $order->scheduled_at->copy()->addHours(4)->timestamp;
-                $job['time_windows'] = [[$start, $end]];
+                $start                = $order->scheduled_at->timestamp;
+                $end                  = $order->scheduled_at->copy()->addHours(4)->timestamp;
+                $task['time_windows'] = [[$start, $end]];
             }
 
-            // --- Skills ---
-            // Prefer first-class required_skills JSON column, fall back to custom fields
             $skills = static::resolveSkills(
                 $order->required_skills ?? [],
                 $order->custom_fields ?? []
             );
             if (!empty($skills)) {
-                $job['skills'] = $skills;
+                $task['skills'] = $skills;
             }
 
-            // --- Priority ---
             if ($order->orchestrator_priority !== null && $order->orchestrator_priority > 0) {
-                $job['priority'] = (int) $order->orchestrator_priority;
+                $task['priority'] = (int) $order->orchestrator_priority;
             }
 
-            return $job;
-        })->filter()->values()->toArray();
+            return $task;
+        })->values()->toArray();
+    }
+
+    /**
+     * @deprecated Use buildRouteTasks(). Kept for older engine adapters.
+     */
+    public static function buildJobs(Collection $orders): array
+    {
+        return array_values(array_filter(
+            static::buildRouteTasks($orders),
+            fn (array $task) => empty($task['invalid'])
+        ));
+    }
+
+    /**
+     * Build normalized capacity-only tasks from Fleetbase orders.
+     *
+     * Capacity allocation does not require route stops. It only needs an order
+     * demand vector plus optional skills, priority, and task limits.
+     */
+    public static function buildCapacityTasks(Collection $orders): array
+    {
+        return $orders->map(function (Order $order) {
+            if (!$order->payload) {
+                return [
+                    'id'          => $order->public_id,
+                    'description' => $order->public_id,
+                    'invalid'     => true,
+                    'reason'      => 'Order has no payload to compute capacity demand.',
+                    'amount'      => [0, 0, 0, 0],
+                ];
+            }
+
+            $task = [
+                'id'          => $order->public_id,
+                'description' => $order->public_id,
+                'amount'      => static::computePayloadDemand($order),
+                'service'     => static::resolveServiceTime($order),
+            ];
+
+            $skills = static::resolveSkills(
+                $order->required_skills ?? [],
+                $order->custom_fields ?? []
+            );
+            if (!empty($skills)) {
+                $task['skills'] = $skills;
+            }
+
+            if ($order->orchestrator_priority !== null && $order->orchestrator_priority > 0) {
+                $task['priority'] = (int) $order->orchestrator_priority;
+            }
+
+            return $task;
+        })->values()->toArray();
+    }
+
+    /**
+     * Return Fleetbase's canonical ordered stops for an order:
+     * pickup, then waypoints by marker order, then dropoff.
+     */
+    public static function buildRouteStops(Order $order): array
+    {
+        return static::normalizeRouteStops(static::buildRouteStopCandidates($order));
+    }
+
+    protected static function buildRouteStopCandidates(Order $order): array
+    {
+        $payload = $order->payload;
+        if (!$payload) {
+            return [];
+        }
+
+        $stops = [];
+
+        if ($payload->pickup) {
+            $stops[] = ['role' => 'pickup', 'place' => $payload->pickup];
+        }
+
+        $waypointMarkers = method_exists($payload, 'relationLoaded') && $payload->relationLoaded('waypointMarkers')
+            ? $payload->waypointMarkers
+            : collect();
+        if ($waypointMarkers->isNotEmpty()) {
+            foreach ($waypointMarkers->sortBy('order')->values() as $index => $waypoint) {
+                $stops[] = [
+                    'role'          => 'waypoint',
+                    'place'         => $waypoint->place,
+                    'waypoint_id'   => $waypoint->public_id,
+                    'waypoint_uuid' => $waypoint->uuid,
+                    'order'         => $waypoint->order ?? $index,
+                ];
+            }
+        } elseif (isset($payload->waypoints) && $payload->waypoints) {
+            foreach ($payload->waypoints->values() as $index => $waypoint) {
+                $stops[] = [
+                    'role'  => 'waypoint',
+                    'place' => $waypoint,
+                    'order' => $index,
+                ];
+            }
+        }
+
+        if ($payload->dropoff) {
+            $stops[] = ['role' => 'dropoff', 'place' => $payload->dropoff];
+        }
+
+        return $stops;
+    }
+
+    protected static function normalizeRouteStops(array $stops): array
+    {
+        return collect($stops)
+            ->map(function (array $stop) {
+                $coordinates = static::coordinatesFromPlace($stop['place'] ?? null);
+                if (!$coordinates) {
+                    return null;
+                }
+
+                unset($stop['place'], $stop['waypoint_uuid']);
+
+                return array_merge($stop, [
+                    'location' => $coordinates,
+                ]);
+            })
+            ->filter()
+            ->values()
+            ->toArray();
+    }
+
+    protected static function resolveServiceTime(Order $order): int
+    {
+        $payload        = $order->payload;
+        $waypointMarker = $payload?->waypointMarkers?->last();
+
+        return (int) (
+            $waypointMarker?->service_time
+            ?? $order->getMeta('service_time_seconds')
+            ?? 300
+        );
+    }
+
+    protected static function coordinatesFromPlace($place): ?array
+    {
+        $location = $place?->location;
+        if (!$location) {
+            return null;
+        }
+
+        $lng = $location->getLng();
+        $lat = $location->getLat();
+
+        if (!static::isValidCoordinate($lng, $lat)) {
+            return null;
+        }
+
+        return [(float) $lng, (float) $lat];
+    }
+
+    protected static function isValidCoordinate($lng, $lat): bool
+    {
+        if (!is_numeric($lng) || !is_numeric($lat)) {
+            return false;
+        }
+
+        $lng = (float) $lng;
+        $lat = (float) $lat;
+
+        return is_finite($lng)
+            && is_finite($lat)
+            && $lng >= -180
+            && $lng <= 180
+            && $lat >= -90
+            && $lat <= 90;
     }
 
     /**
@@ -337,6 +495,56 @@ class OrchestrationPayloadBuilder
         })->filter()->values()->toArray();
     }
 
+    /**
+     * Build vehicles for non-geospatial capacity allocation.
+     *
+     * Unlike buildVehicles(), this intentionally does not require a vehicle or
+     * driver location because no routing engine will be asked to calculate
+     * travel distance or duration.
+     */
+    public static function buildCapacityVehicles(Collection $vehicles): array
+    {
+        return $vehicles->map(function (Vehicle $vehicle) {
+            $driver = $vehicle->driver;
+            $entry  = [
+                'id'        => $vehicle->public_id,
+                'driver_id' => $driver?->public_id,
+                'capacity'  => static::buildVehicleCapacity($vehicle),
+            ];
+
+            if ($vehicle->max_tasks !== null && $vehicle->max_tasks > 0) {
+                $entry['max_tasks'] = (int) $vehicle->max_tasks;
+            }
+
+            $maxTravel = $driver?->max_travel_time ?? static::safeMeta($vehicle, 'max_travel_time_seconds');
+            if ($maxTravel) {
+                $entry['max_travel_time'] = (int) $maxTravel;
+            }
+
+            if ($driver?->time_window_start && $driver?->time_window_end) {
+                $entry['time_window'] = [
+                    $driver->time_window_start->timestamp,
+                    $driver->time_window_end->timestamp,
+                ];
+            } elseif ($vehicle->time_window_start && $vehicle->time_window_end) {
+                $entry['time_window'] = [
+                    $vehicle->time_window_start->timestamp,
+                    $vehicle->time_window_end->timestamp,
+                ];
+            }
+
+            $skills = array_values(array_unique(array_merge(
+                static::resolveSkills($vehicle->skills ?? [], $vehicle->custom_fields ?? []),
+                static::resolveSkills($driver?->skills ?? [], $driver?->custom_fields ?? [])
+            )));
+            if (!empty($skills)) {
+                $entry['skills'] = $skills;
+            }
+
+            return $entry;
+        })->values()->toArray();
+    }
+
     /**
      * Resolve integer skill codes from a first-class skills array and/or custom fields.
      *

package/server/src/Providers/FleetOpsServiceProvider.php

@@ -65,6 +65,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,
     ];
 
     /**
@@ -99,6 +100,13 @@ class FleetOpsServiceProvider extends CoreServiceProvider
             \Fleetbase\FleetOps\Orchestration\OrchestrationEngineRegistry::class,
             fn () => new \Fleetbase\FleetOps\Orchestration\OrchestrationEngineRegistry()
         );
+
+        // Register the TrackingProviderRegistry as a singleton so FleetOps core
+        // and third-party extensions can share tracking intelligence providers.
+        $this->app->singleton(
+            \Fleetbase\FleetOps\Tracking\TrackingProviderRegistry::class,
+            fn () => new \Fleetbase\FleetOps\Tracking\TrackingProviderRegistry()
+        );
     }
 
     /**
@@ -119,6 +127,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');
@@ -135,6 +144,26 @@ class FleetOpsServiceProvider extends CoreServiceProvider
                 if (!$registry->has('greedy')) {
                     $registry->register(new \Fleetbase\FleetOps\Orchestration\Engines\GreedyOrchestrationEngine());
                 }
+                if (!$registry->has('capacity')) {
+                    $registry->register(new \Fleetbase\FleetOps\Orchestration\Engines\CapacityAllocationEngine());
+                }
+            }
+        );
+
+        // Register built-in tracking providers. Third-party extensions can
+        // register additional providers from their own service providers.
+        $this->app->resolving(
+            \Fleetbase\FleetOps\Tracking\TrackingProviderRegistry::class,
+            function (\Fleetbase\FleetOps\Tracking\TrackingProviderRegistry $registry) {
+                if (!$registry->has('google_routes')) {
+                    $registry->register(new \Fleetbase\FleetOps\Tracking\Providers\GoogleRoutesTrackingProvider());
+                }
+                if (!$registry->has('osrm')) {
+                    $registry->register(new \Fleetbase\FleetOps\Tracking\Providers\OsrmTrackingProvider());
+                }
+                if (!$registry->has('calculated')) {
+                    $registry->register(new \Fleetbase\FleetOps\Tracking\Providers\CalculatedTrackingProvider());
+                }
             }
         );
         $this->loadRoutesFrom(__DIR__ . '/../routes.php');
@@ -165,6 +194,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(),
+            ],
+        ];
+    }
+}