@fleetbase/fleetops-engine 0.6.48 → 0.6.49

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

@@ -0,0 +1,279 @@
+<?php
+
+namespace Fleetbase\FleetOps\Console\Commands;
+
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Position;
+use Fleetbase\FleetOps\Notifications\LateDeparture;
+use Fleetbase\FleetOps\Notifications\ProlongedStoppage;
+use Fleetbase\FleetOps\Notifications\RouteDeviation;
+use Fleetbase\FleetOps\Support\Utils;
+use Fleetbase\LaravelMysqlSpatial\Types\Point;
+use Fleetbase\Models\Setting;
+use Fleetbase\Support\NotificationRegistry;
+use Illuminate\Console\Command;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Facades\Cache;
+
+class ProcessOperationalAlerts extends Command
+{
+    protected $signature = 'fleetops:process-operational-alerts
+        {--days=2 : Only include orders created in the last N days}
+        {--chunk=250 : How many orders to process per chunk}
+        {--no-lock : Skip process locking}
+        {--dry : Dry run without updating notification markers}';
+
+    protected $description = 'Evaluate FleetOps operational alerts for late departures, route deviations, and prolonged stoppages.';
+
+    public function handle(): int
+    {
+        $days     = max(1, (int) $this->option('days'));
+        $perChunk = max(50, (int) $this->option('chunk'));
+        $dryRun   = (bool) $this->option('dry');
+        $useLock  = !$this->option('no-lock');
+        $lock     = null;
+
+        if ($useLock) {
+            $lock = Cache::lock('fleetops:process-operational-alerts', 600);
+            if (!$lock->get()) {
+                $this->warn('Another operational alert run appears to be in progress.');
+
+                return self::SUCCESS;
+            }
+        }
+
+        try {
+            $cutoff = Carbon::now()->subDays($days);
+            $query  = $this->ordersQuery($cutoff);
+            $total  = (clone $query)->count('id');
+
+            if ($total === 0) {
+                $this->info('No qualifying orders found.');
+
+                return self::SUCCESS;
+            }
+
+            $triggered = 0;
+
+            $query->orderBy('id')->chunkById($perChunk, function ($orders) use ($dryRun, &$triggered) {
+                $orders->loadMissing(['driverAssigned', 'vehicleAssigned', 'route']);
+
+                foreach ($orders as $order) {
+                    session(['company' => $order->company_uuid]);
+                    $settings = $this->alertSettings();
+
+                    if ($this->processLateDeparture($order, $settings, $dryRun)) {
+                        $triggered++;
+                    }
+
+                    if ($this->processRouteDeviation($order, $settings, $dryRun)) {
+                        $triggered++;
+                    }
+
+                    if ($this->processProlongedStoppage($order, $settings, $dryRun)) {
+                        $triggered++;
+                    }
+                }
+            });
+
+            $this->info(($dryRun ? '[Dry Run] ' : '') . "Operational alerts triggered: {$triggered}");
+
+            return self::SUCCESS;
+        } finally {
+            if ($lock) {
+                $lock->release();
+            }
+        }
+    }
+
+    protected function ordersQuery(Carbon $cutoff)
+    {
+        return Order::query()
+            ->withoutGlobalScopes()
+            ->whereNotIn('status', ['completed', 'canceled'])
+            ->whereNull('deleted_at')
+            ->whereNotNull('company_uuid')
+            ->where('created_at', '>=', $cutoff);
+    }
+
+    protected function processLateDeparture(Order $order, array $settings, bool $dryRun): bool
+    {
+        if (!data_get($settings, 'late_departures.enabled')) {
+            return false;
+        }
+
+        if (!$order->scheduled_at || $order->started_at || $order->started) {
+            return false;
+        }
+
+        $graceMinutes = (int) data_get($settings, 'late_departures.grace_period_minutes', 15);
+        if (Carbon::parse($order->scheduled_at)->addMinutes($graceMinutes)->isFuture()) {
+            return false;
+        }
+
+        return $this->notifyOnce($order, 'late_departure', LateDeparture::class, [
+            'scheduled_at'         => $order->scheduled_at,
+            'grace_period_minutes' => $graceMinutes,
+        ], $dryRun);
+    }
+
+    protected function processRouteDeviation(Order $order, array $settings, bool $dryRun): bool
+    {
+        if (!data_get($settings, 'route_deviations.enabled')) {
+            return false;
+        }
+
+        $latestPosition = $this->latestPositionForOrder($order);
+        if (!$latestPosition?->coordinates) {
+            return false;
+        }
+
+        $routePoints = $this->routePoints($order);
+        if (count($routePoints) < 2) {
+            return false;
+        }
+
+        $thresholdMeters = (int) data_get($settings, 'route_deviations.distance_threshold_meters', 500);
+        $distanceMeters  = $this->minimumDistanceToRoute($latestPosition->coordinates, $routePoints);
+
+        if ($distanceMeters <= $thresholdMeters) {
+            return false;
+        }
+
+        return $this->notifyOnce($order, 'route_deviation', RouteDeviation::class, [
+            'distance_meters'           => round($distanceMeters, 2),
+            'distance_threshold_meters' => $thresholdMeters,
+            'position_id'               => $latestPosition->uuid,
+        ], $dryRun);
+    }
+
+    protected function processProlongedStoppage(Order $order, array $settings, bool $dryRun): bool
+    {
+        if (!data_get($settings, 'prolonged_stoppages.enabled')) {
+            return false;
+        }
+
+        if (!$order->started_at && !$order->started) {
+            return false;
+        }
+
+        $latestPosition = $this->latestPositionForOrder($order);
+        if (!$latestPosition || ((float) $latestPosition->speed) > 1) {
+            return false;
+        }
+
+        $thresholdMinutes = (int) data_get($settings, 'prolonged_stoppages.duration_threshold_minutes', 30);
+        if (Carbon::parse($latestPosition->created_at)->addMinutes($thresholdMinutes)->isFuture()) {
+            return false;
+        }
+
+        return $this->notifyOnce($order, 'prolonged_stoppage', ProlongedStoppage::class, [
+            'duration_threshold_minutes' => $thresholdMinutes,
+            'position_id'                => $latestPosition->uuid,
+            'stopped_since'              => $latestPosition->created_at,
+        ], $dryRun);
+    }
+
+    protected function notifyOnce(Order $order, string $key, string $notificationClass, array $context, bool $dryRun): bool
+    {
+        $metaKey = "operational_alerts.{$key}.notified_at";
+        if ($order->getMeta($metaKey)) {
+            return false;
+        }
+
+        NotificationRegistry::notify($notificationClass, $order, $context);
+
+        if (!$dryRun) {
+            $order->setMeta("operational_alerts.{$key}", [
+                'notified_at' => Carbon::now()->toDateTimeString(),
+                'context'     => $context,
+            ]);
+            $order->saveQuietly();
+        }
+
+        return true;
+    }
+
+    protected function latestPositionForOrder(Order $order): ?Position
+    {
+        return Position::where('company_uuid', $order->company_uuid)
+            ->where('order_uuid', $order->uuid)
+            ->latest()
+            ->first();
+    }
+
+    protected function routePoints(Order $order): array
+    {
+        $details = data_get($order, 'route.details', []);
+
+        return $this->collectPoints($details);
+    }
+
+    protected function collectPoints(mixed $value): array
+    {
+        if (!is_array($value)) {
+            return [];
+        }
+
+        if ($point = $this->pointFromPair($value)) {
+            return [$point];
+        }
+
+        $points = [];
+        foreach ($value as $item) {
+            foreach ($this->collectPoints($item) as $point) {
+                $points[] = $point;
+            }
+        }
+
+        return $points;
+    }
+
+    protected function pointFromPair(array $value): ?Point
+    {
+        if (count($value) !== 2 || !is_numeric($value[0]) || !is_numeric($value[1])) {
+            return null;
+        }
+
+        $first  = (float) $value[0];
+        $second = (float) $value[1];
+
+        if (abs($first) <= 90 && abs($second) <= 180) {
+            return new Point($first, $second);
+        }
+
+        if (abs($first) <= 180 && abs($second) <= 90) {
+            return new Point($second, $first);
+        }
+
+        return null;
+    }
+
+    protected function minimumDistanceToRoute(Point $position, array $routePoints): float
+    {
+        return collect($routePoints)
+            ->map(fn (Point $point) => Utils::vincentyGreatCircleDistance($position, $point))
+            ->min() ?? 0;
+    }
+
+    protected function alertSettings(): array
+    {
+        $settings = Setting::lookupCompany('tracking', []);
+        $alerts   = data_get($settings, 'alerts', []);
+
+        return [
+            'late_departures' => [
+                'enabled'              => (bool) data_get($alerts, 'late_departures.enabled', true),
+                'grace_period_minutes' => (int) data_get($alerts, 'late_departures.grace_period_minutes', 15),
+            ],
+            'route_deviations' => [
+                'enabled'                   => (bool) data_get($alerts, 'route_deviations.enabled', true),
+                'distance_threshold_meters' => (int) data_get($alerts, 'route_deviations.distance_threshold_meters', 500),
+            ],
+            'prolonged_stoppages' => [
+                'enabled'                    => (bool) data_get($alerts, 'prolonged_stoppages.enabled', true),
+                'duration_threshold_minutes' => (int) data_get($alerts, 'prolonged_stoppages.duration_threshold_minutes', 30),
+            ],
+        ];
+    }
+}

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

@@ -0,0 +1,119 @@
+<?php
+
+namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
+
+use Fleetbase\FleetOps\Support\Analytics\AbstractAnalytics;
+use Fleetbase\FleetOps\Support\Analytics\FuelEfficiency;
+use Fleetbase\FleetOps\Support\Analytics\GeofenceViolations;
+use Fleetbase\FleetOps\Support\Analytics\IssuesInsights;
+use Fleetbase\FleetOps\Support\Analytics\LiveFleet;
+use Fleetbase\FleetOps\Support\Analytics\MaintenanceOverview;
+use Fleetbase\FleetOps\Support\Analytics\OnTimeDelivery;
+use Fleetbase\FleetOps\Support\Analytics\OperationsPulse;
+use Fleetbase\FleetOps\Support\Analytics\OrdersByStatus;
+use Fleetbase\FleetOps\Support\Analytics\RevenueTrend;
+use Fleetbase\FleetOps\Support\Analytics\TopDrivers;
+use Fleetbase\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+
+/**
+ * One public method per dashboard widget. Each method:
+ *   - Resolves a period from ?period=7d|30d|... or explicit start/end
+ *   - Constructs the corresponding Support\Analytics\* helper
+ *   - Returns the helper's JSON payload (Chart.js datasets, ranked rows,
+ *     scalar tiles, etc. — shape is widget-specific)
+ *
+ * Cache headers are set per-widget by the route middleware in routes.php.
+ */
+class AnalyticsController extends Controller
+{
+    public function operationsPulse(Request $request)
+    {
+        return $this->run($request, OperationsPulse::class);
+    }
+
+    public function revenueTrend(Request $request)
+    {
+        return $this->run($request, RevenueTrend::class, function (RevenueTrend $a) use ($request) {
+            $a->groupBy($request->string('group_by', 'day')->toString());
+        });
+    }
+
+    public function ordersByStatus(Request $request)
+    {
+        return $this->run($request, OrdersByStatus::class, defaultDays: 14);
+    }
+
+    public function onTimeDelivery(Request $request)
+    {
+        return $this->run($request, OnTimeDelivery::class, function (OnTimeDelivery $a) use ($request) {
+            $a->slaMinutes((int) $request->input('sla_minutes', 30));
+        });
+    }
+
+    public function topDrivers(Request $request)
+    {
+        return $this->run($request, TopDrivers::class, function (TopDrivers $a) use ($request) {
+            $a->limit((int) $request->input('limit', 10));
+            $a->sortBy($request->string('sort_by', 'orders_completed')->toString());
+        });
+    }
+
+    public function fuelEfficiency(Request $request)
+    {
+        return $this->run($request, FuelEfficiency::class, defaultDays: 90);
+    }
+
+    public function issuesInsights(Request $request)
+    {
+        return $this->run($request, IssuesInsights::class);
+    }
+
+    public function maintenanceOverview(Request $request)
+    {
+        return $this->run($request, MaintenanceOverview::class);
+    }
+
+    public function geofenceViolations(Request $request)
+    {
+        return $this->run($request, GeofenceViolations::class, defaultDays: 7);
+    }
+
+    public function liveFleet(Request $request)
+    {
+        return $this->run($request, LiveFleet::class);
+    }
+
+    /**
+     * Shared boilerplate: period parsing + helper construction + JSON response.
+     *
+     * @param class-string<AbstractAnalytics> $class
+     */
+    private function run(Request $request, string $class, ?callable $configure = null, int $defaultDays = 30)
+    {
+        [$start, $end] = AbstractAnalytics::resolvePeriod(
+            $request->string('period')->toString() ?: null,
+            $request->date('start'),
+            $request->date('end'),
+            $defaultDays,
+        );
+
+        try {
+            /** @var AbstractAnalytics $analytics */
+            $analytics = $class::forCompany($request->user()->company)->between($start, $end);
+
+            if ($configure !== null) {
+                $configure($analytics);
+            }
+
+            return response()->json($analytics->get());
+        } catch (\Throwable $e) {
+            report($e);
+
+            return response()->json([
+                'error'   => $e->getMessage(),
+                'widget'  => $class,
+            ], 500);
+        }
+    }
+}

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

@@ -3,15 +3,17 @@
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
 use Fleetbase\FleetOps\Support\Metrics;
+use Fleetbase\FleetOps\Support\Metrics\Registry;
 use Fleetbase\Http\Controllers\Controller;
 use Illuminate\Http\Request;
+use Illuminate\Support\Carbon;
 
 class MetricsController extends Controller
 {
     /**
-     * Gets all key metrics for the current session.
-     *
-     * @return \Illuminate\Http\Response
+     * Legacy bulk endpoint. Returns a flat map of slug → scalar value for the
+     * requested period. Preserved for backward compat; the dashboard widgets
+     * now prefer per-slug GET /metrics/{slug}.
      */
     public function all(Request $request)
     {
@@ -27,4 +29,81 @@ class MetricsController extends Controller
 
         return response()->json($data);
     }
+
+    /**
+     * Per-metric endpoint backing <Widget::KpiTile>.
+     *
+     * Accepts:
+     *   ?period=7d|30d|90d  OR  ?start=ISO&end=ISO
+     *   ?sparkline=true     to include a per-day mini-chart series
+     *   ?compare=true       to include period-over-period delta (default: true)
+     *
+     * Returns: { slug, value, format, currency?, delta_pct?, sparkline? }
+     */
+    public function show(Request $request, string $slug)
+    {
+        $class = Registry::resolve($slug);
+        if ($class === null) {
+            return response()->json(['error' => "Unknown metric: {$slug}"], 404);
+        }
+
+        [$start, $end] = $this->resolvePeriod($request);
+
+        $metric = $class::forCompany($request->user()->company)->between($start, $end);
+
+        if ($request->boolean('compare', true)) {
+            $duration     = $end->getTimestamp() - $start->getTimestamp();
+            $compareEnd   = (clone $start);
+            $compareStart = (clone $start)->modify("-{$duration} seconds");
+            $metric->compareTo($compareStart, $compareEnd);
+        }
+
+        if ($request->boolean('sparkline')) {
+            $buckets = (int) $request->input('sparkline_buckets', 14);
+            $metric->withSparkline($buckets, 'day');
+        }
+
+        return response()->json($metric->get());
+    }
+
+    /**
+     * Parse ?period=7d/30d/90d into a [start, end] pair, falling back to
+     * explicit ?start=&end= ISO dates, then to a 30-day default.
+     */
+    private function resolvePeriod(Request $request): array
+    {
+        $period = $request->string('period')->toString();
+
+        if ($period !== '') {
+            $days = match ($period) {
+                '7d'    => 7,
+                '14d'   => 14,
+                '30d'   => 30,
+                '90d'   => 90,
+                '180d'  => 180,
+                '365d'  => 365,
+                default => null,
+            };
+
+            if ($days !== null) {
+                $end   = Carbon::now()->toDateTime();
+                $start = Carbon::now()->subDays($days)->toDateTime();
+
+                return [$start, $end];
+            }
+        }
+
+        $start = $request->date('start') ?? Carbon::now()->subDays(30)->toDateTime();
+        $end   = $request->date('end') ?? Carbon::now()->toDateTime();
+
+        if (!$start instanceof \DateTime) {
+            $start = Carbon::parse($start)->toDateTime();
+        }
+
+        if (!$end instanceof \DateTime) {
+            $end = Carbon::parse($end)->toDateTime();
+        }
+
+        return [$start, $end];
+    }
 }

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

@@ -112,13 +112,19 @@ class OrderController extends FleetOpsController
                         $input['integrated_vendor_order'] = $integratedVendorOrder;
                     }
 
-                    // Normalize order config + type onto the company transport
-                    // config when an explicit config was not provided.
-                    $resolvedOrderConfig = null;
-                    if (!empty($input['order_config_uuid']) || !empty($input['type'])) {
-                        $resolvedOrderConfig = OrderConfig::resolveFromIdentifier([$input['order_config_uuid'] ?? null, $input['type'] ?? null]);
+                    // Normalize order config + type. Invalid explicit configs must
+                    // not silently fall back to the default transport config.
+                    $hasExplicitOrderConfig = !empty($input['order_config_uuid']);
+                    $hasExplicitOrderType   = !empty($input['type']);
+                    $resolvedOrderConfig    = OrderConfig::resolveFromIdentifier([$input['order_config_uuid'] ?? null, $input['type'] ?? null]);
+
+                    if (!$resolvedOrderConfig && $hasExplicitOrderConfig) {
+                        throw new FleetbaseRequestValidationException(['order_config_uuid' => 'The selected order config is invalid.']);
+                    }
+
+                    if (!$resolvedOrderConfig && !$hasExplicitOrderType) {
+                        $resolvedOrderConfig = OrderConfig::defaultOrCreate();
                     }
-                    $resolvedOrderConfig ??= OrderConfig::defaultOrCreate();
 
                     if ($resolvedOrderConfig) {
                         $input['order_config_uuid'] = $resolvedOrderConfig->uuid;

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

@@ -251,6 +251,7 @@ class SettingController extends Controller
             'route_cache_ttl_seconds'          => (int) $request->input('route_cache_ttl_seconds', data_get($config, 'route_cache_ttl_seconds', 600)),
             'stale_location_threshold_seconds' => (int) $request->input('stale_location_threshold_seconds', data_get($config, 'stale_location_threshold_seconds', 300)),
             'default_vehicle_speed_kph'        => (float) $request->input('default_vehicle_speed_kph', data_get($config, 'default_vehicle_speed_kph', 35)),
+            'alerts'                           => $this->normalizeTrackingAlertSettings((array) $request->input('alerts', data_get($config, 'alerts', []))),
         ]);
 
         return response()->json([
@@ -275,7 +276,9 @@ class SettingController extends Controller
             'route_cache_ttl_seconds'          => data_get($config, 'route_cache_ttl_seconds', 600),
             'stale_location_threshold_seconds' => data_get($config, 'stale_location_threshold_seconds', 300),
             'default_vehicle_speed_kph'        => data_get($config, 'default_vehicle_speed_kph', 35),
+            'alerts'                           => data_get($config, 'alerts', $this->trackingAlertDefaults()),
         ]);
+        $trackingSettings['alerts']    = $this->normalizeTrackingAlertSettings(data_get($trackingSettings, 'alerts', []));
         $trackingSettings['providers'] = $this->trackingProviderOptions();
 
         return response()->json($trackingSettings);
@@ -304,6 +307,7 @@ class SettingController extends Controller
             'route_cache_ttl_seconds'          => (int) $request->input('route_cache_ttl_seconds', data_get($config, 'route_cache_ttl_seconds', 600)),
             'stale_location_threshold_seconds' => (int) $request->input('stale_location_threshold_seconds', data_get($config, 'stale_location_threshold_seconds', 300)),
             'default_vehicle_speed_kph'        => (float) $request->input('default_vehicle_speed_kph', data_get($config, 'default_vehicle_speed_kph', 35)),
+            'alerts'                           => $this->normalizeTrackingAlertSettings((array) $request->input('alerts', data_get($config, 'alerts', []))),
         ]);
 
         return response()->json($this->getAdminTrackingSettings()->getData(true));
@@ -519,7 +523,48 @@ class SettingController extends Controller
         $config         = config('fleetops.tracking', []);
         $systemSettings = Setting::lookup('fleet-ops.tracking-settings', []);
 
-        return array_merge($config, is_array($systemSettings) ? $systemSettings : []);
+        $defaults = array_merge($config, is_array($systemSettings) ? $systemSettings : []);
+        $defaults['alerts'] = $this->normalizeTrackingAlertSettings(data_get($defaults, 'alerts', []));
+
+        return $defaults;
+    }
+
+    protected function trackingAlertDefaults(): array
+    {
+        return [
+            'late_departures' => [
+                'enabled'              => true,
+                'grace_period_minutes' => 15,
+            ],
+            'route_deviations' => [
+                'enabled'                    => true,
+                'distance_threshold_meters'  => 500,
+            ],
+            'prolonged_stoppages' => [
+                'enabled'                  => true,
+                'duration_threshold_minutes' => 30,
+            ],
+        ];
+    }
+
+    protected function normalizeTrackingAlertSettings(array $alerts): array
+    {
+        $defaults = $this->trackingAlertDefaults();
+
+        return [
+            'late_departures' => [
+                'enabled'              => (bool) data_get($alerts, 'late_departures.enabled', data_get($defaults, 'late_departures.enabled')),
+                'grace_period_minutes' => max(0, (int) data_get($alerts, 'late_departures.grace_period_minutes', data_get($defaults, 'late_departures.grace_period_minutes'))),
+            ],
+            'route_deviations' => [
+                'enabled'                   => (bool) data_get($alerts, 'route_deviations.enabled', data_get($defaults, 'route_deviations.enabled')),
+                'distance_threshold_meters' => max(0, (int) data_get($alerts, 'route_deviations.distance_threshold_meters', data_get($defaults, 'route_deviations.distance_threshold_meters'))),
+            ],
+            'prolonged_stoppages' => [
+                'enabled'                    => (bool) data_get($alerts, 'prolonged_stoppages.enabled', data_get($defaults, 'prolonged_stoppages.enabled')),
+                'duration_threshold_minutes' => max(0, (int) data_get($alerts, 'prolonged_stoppages.duration_threshold_minutes', data_get($defaults, 'prolonged_stoppages.duration_threshold_minutes'))),
+            ],
+        ];
     }
 
     protected function trackingProviderOptions(): array

package/server/src/Http/Resources/v1/Driver.php

@@ -38,6 +38,7 @@ class Driver extends FleetbaseResource
             'email'                         => $this->email,
             'phone'                         => $this->phone,
             'drivers_license_number'        => $this->drivers_license_number,
+            'license_expiry'                => $this->license_expiry,
             'photo_url'                     => $this->photo_url,
             'avatar_url'                    => $this->avatar_url,
             'avatar_value'                  => $this->when(Http::isInternalRequest(), $this->getOriginal('avatar_url')),
@@ -94,6 +95,7 @@ class Driver extends FleetbaseResource
             'email'                  => $this->email,
             'phone'                  => $this->phone,
             'photo_url'              => $this->photo_url,
+            'license_expiry'         => $this->license_expiry,
             'vehicle'                => data_get($this, 'vehicle.public_id'),
             'current_job'            => data_get($this, 'currentJob.public_id'),
             'vendor'                 => data_get($this, 'vendor.public_id'),

package/server/src/Http/Resources/v1/Fleet.php

@@ -23,6 +23,10 @@ class Fleet extends FleetbaseResource
             }, $request->array('with'));
 
             $this->load($with);
+
+            if (in_array('subfleets', $with, true) && in_array('vehicles', $with, true)) {
+                $this->loadMissing('subFleets.vehicles');
+            }
         }
 
         return $this->withCustomFields([