@fleetbase/fleetops-engine 0.6.47 → 0.6.49

package/server/src/Tracking/Providers/CalculatedTrackingProvider.php

@@ -0,0 +1,65 @@
+<?php
+
+namespace Fleetbase\FleetOps\Tracking\Providers;
+
+use Fleetbase\FleetOps\Support\Utils;
+use Fleetbase\FleetOps\Tracking\Contracts\TrackingProviderInterface;
+use Fleetbase\FleetOps\Tracking\TrackingContext;
+use Fleetbase\FleetOps\Tracking\TrackingOptions;
+use Fleetbase\FleetOps\Tracking\TrackingProviderCapabilities;
+use Fleetbase\FleetOps\Tracking\TrackingProviderResult;
+
+class CalculatedTrackingProvider implements TrackingProviderInterface
+{
+    public function key(): string
+    {
+        return 'calculated';
+    }
+
+    public function capabilities(): TrackingProviderCapabilities
+    {
+        return new TrackingProviderCapabilities();
+    }
+
+    public function canTrack(TrackingContext $context): bool
+    {
+        return $context->canRoute();
+    }
+
+    public function track(TrackingContext $context, TrackingOptions $options): TrackingProviderResult
+    {
+        $points   = $context->routePoints();
+        $distance = 0;
+        $legs     = [];
+
+        for ($i = 0; $i < count($points) - 1; $i++) {
+            $legDistance = Utils::vincentyGreatCircleDistance($points[$i], $points[$i + 1]);
+            $legDuration = $this->durationFromDistance($legDistance, $options);
+            $distance += $legDistance;
+            $legs[] = [
+                'index'                 => $i,
+                'distance_m'            => $legDistance,
+                'duration_s'            => $legDuration,
+                'duration_in_traffic_s' => null,
+                'provider'              => $this->key(),
+            ];
+        }
+
+        return new TrackingProviderResult(
+            provider: $this->key(),
+            distanceMeters: $distance,
+            durationSeconds: $this->durationFromDistance($distance, $options),
+            durationInTrafficSeconds: null,
+            legs: $legs,
+            warnings: ['calculated_route_used'],
+            confidence: 'low'
+        );
+    }
+
+    protected function durationFromDistance(float $distanceMeters, TrackingOptions $options): float
+    {
+        $metersPerSecond = max($options->defaultVehicleSpeedKph, 1) * 1000 / 3600;
+
+        return round($distanceMeters / $metersPerSecond);
+    }
+}

package/server/src/Tracking/Providers/GoogleRoutesTrackingProvider.php

@@ -0,0 +1,118 @@
+<?php
+
+namespace Fleetbase\FleetOps\Tracking\Providers;
+
+use Fleetbase\FleetOps\Tracking\Contracts\TrackingProviderInterface;
+use Fleetbase\FleetOps\Tracking\TrackingContext;
+use Fleetbase\FleetOps\Tracking\TrackingOptions;
+use Fleetbase\FleetOps\Tracking\TrackingProviderCapabilities;
+use Fleetbase\FleetOps\Tracking\TrackingProviderResult;
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Str;
+
+class GoogleRoutesTrackingProvider implements TrackingProviderInterface
+{
+    public function key(): string
+    {
+        return 'google_routes';
+    }
+
+    public function capabilities(): TrackingProviderCapabilities
+    {
+        return new TrackingProviderCapabilities(traffic: true, perLegEta: true, routeGeometry: true);
+    }
+
+    public function canTrack(TrackingContext $context): bool
+    {
+        return $context->canRoute() && filled($this->apiKey());
+    }
+
+    public function track(TrackingContext $context, TrackingOptions $options): TrackingProviderResult
+    {
+        $points      = $context->routePoints();
+        $origin      = array_shift($points);
+        $destination = array_pop($points);
+        $body        = [
+            'origin'                   => ['location' => ['latLng' => $this->latLng($origin)]],
+            'destination'              => ['location' => ['latLng' => $this->latLng($destination)]],
+            'travelMode'               => 'DRIVE',
+            'routingPreference'        => $options->trafficEnabled ? 'TRAFFIC_AWARE_OPTIMAL' : 'TRAFFIC_UNAWARE',
+            'computeAlternativeRoutes' => false,
+            'languageCode'             => 'en-US',
+            'units'                    => 'METRIC',
+        ];
+
+        if (!empty($points)) {
+            $body['intermediates'] = array_map(fn ($point) => ['location' => ['latLng' => $this->latLng($point)]], $points);
+        }
+
+        $response = Http::timeout(5)
+            ->withHeaders([
+                'X-Goog-Api-Key'   => $this->apiKey(),
+                'X-Goog-FieldMask' => 'routes.distanceMeters,routes.duration,routes.staticDuration,routes.polyline.encodedPolyline,routes.legs.distanceMeters,routes.legs.duration,routes.legs.staticDuration',
+            ])
+            ->post('https://routes.googleapis.com/directions/v2:computeRoutes', $body);
+
+        if (!$response->successful()) {
+            throw new \RuntimeException('Google Routes request failed with status ' . $response->status());
+        }
+
+        $route = data_get($response->json(), 'routes.0');
+        if (!$route) {
+            throw new \RuntimeException('Google Routes returned no route.');
+        }
+
+        $duration        = $this->durationToSeconds(data_get($route, 'staticDuration')) ?? $this->durationToSeconds(data_get($route, 'duration'));
+        $trafficDuration = $this->durationToSeconds(data_get($route, 'duration'));
+
+        return new TrackingProviderResult(
+            provider: $this->key(),
+            distanceMeters: data_get($route, 'distanceMeters'),
+            durationSeconds: $duration,
+            durationInTrafficSeconds: $options->trafficEnabled ? $trafficDuration : null,
+            polyline: data_get($route, 'polyline.encodedPolyline'),
+            legs: $this->legs(data_get($route, 'legs', []), $options),
+            warnings: [],
+            confidence: $options->trafficEnabled ? 'high' : 'medium',
+            raw: $route
+        );
+    }
+
+    protected function legs(array $legs, TrackingOptions $options): array
+    {
+        return collect($legs)->map(function ($leg, $index) use ($options) {
+            $duration        = $this->durationToSeconds(data_get($leg, 'staticDuration')) ?? $this->durationToSeconds(data_get($leg, 'duration'));
+            $trafficDuration = $this->durationToSeconds(data_get($leg, 'duration'));
+
+            return [
+                'index'                 => $index,
+                'distance_m'            => data_get($leg, 'distanceMeters'),
+                'duration_s'            => $duration,
+                'duration_in_traffic_s' => $options->trafficEnabled ? $trafficDuration : null,
+                'provider'              => $this->key(),
+            ];
+        })->all();
+    }
+
+    protected function latLng($point): array
+    {
+        return [
+            'latitude'  => $point->getLat(),
+            'longitude' => $point->getLng(),
+        ];
+    }
+
+    protected function durationToSeconds(?string $duration): ?float
+    {
+        if (!$duration) {
+            return null;
+        }
+
+        return (float) Str::replaceLast('s', '', $duration);
+    }
+
+    protected function apiKey(): ?string
+    {
+        return config('services.google_maps.api_key') ?: env('GOOGLE_MAPS_API_KEY');
+    }
+}

package/server/src/Tracking/Providers/OsrmTrackingProvider.php

@@ -0,0 +1,71 @@
+<?php
+
+namespace Fleetbase\FleetOps\Tracking\Providers;
+
+use Fleetbase\FleetOps\Support\OSRM;
+use Fleetbase\FleetOps\Tracking\Contracts\TrackingProviderInterface;
+use Fleetbase\FleetOps\Tracking\TrackingContext;
+use Fleetbase\FleetOps\Tracking\TrackingOptions;
+use Fleetbase\FleetOps\Tracking\TrackingProviderCapabilities;
+use Fleetbase\FleetOps\Tracking\TrackingProviderResult;
+use Illuminate\Support\Arr;
+
+class OsrmTrackingProvider implements TrackingProviderInterface
+{
+    public function key(): string
+    {
+        return 'osrm';
+    }
+
+    public function capabilities(): TrackingProviderCapabilities
+    {
+        return new TrackingProviderCapabilities(perLegEta: true, routeGeometry: true);
+    }
+
+    public function canTrack(TrackingContext $context): bool
+    {
+        return $context->canRoute();
+    }
+
+    public function track(TrackingContext $context, TrackingOptions $options): TrackingProviderResult
+    {
+        $response = OSRM::getRouteFromPoints($context->routePoints(), [
+            'overview'    => 'full',
+            'geometries'  => 'polyline',
+            'steps'       => 'false',
+            'annotations' => 'false',
+        ]);
+
+        if (data_get($response, 'code') !== 'Ok') {
+            throw new \RuntimeException('OSRM did not return a routable response.');
+        }
+
+        $route = Arr::first(data_get($response, 'routes', []));
+        if (!$route) {
+            throw new \RuntimeException('OSRM returned no route.');
+        }
+
+        $legs = collect(data_get($route, 'legs', []))->map(function ($leg, $index) {
+            return [
+                'index'                 => $index,
+                'distance_m'            => data_get($leg, 'distance'),
+                'duration_s'            => data_get($leg, 'duration'),
+                'duration_in_traffic_s' => null,
+                'provider'              => $this->key(),
+            ];
+        })->all();
+
+        return new TrackingProviderResult(
+            provider: $this->key(),
+            distanceMeters: data_get($route, 'distance'),
+            durationSeconds: data_get($route, 'duration'),
+            durationInTrafficSeconds: null,
+            polyline: data_get($route, 'geometry'),
+            coordinates: data_get($route, 'waypoints', []),
+            legs: $legs,
+            warnings: ['no_live_traffic'],
+            confidence: 'medium',
+            raw: $route
+        );
+    }
+}

package/server/src/Tracking/README.md

@@ -0,0 +1,25 @@
+# Order Tracking Providers
+
+FleetOps tracking providers adapt third-party routing or tracking systems into the canonical tracking intelligence response.
+
+Providers must implement `Fleetbase\FleetOps\Tracking\Contracts\TrackingProviderInterface`:
+
+```php
+public function key(): string;
+public function capabilities(): TrackingProviderCapabilities;
+public function canTrack(TrackingContext $context): bool;
+public function track(TrackingContext $context, TrackingOptions $options): TrackingProviderResult;
+```
+
+Register providers from a service provider:
+
+```php
+use Fleetbase\FleetOps\Tracking\TrackingProviderRegistry;
+
+public function boot(): void
+{
+    app(TrackingProviderRegistry::class)->register(new TomTomTrackingProvider());
+}
+```
+
+Provider adapters should never expose vendor response shapes directly. Map provider responses into `TrackingProviderResult` and declare capabilities such as traffic-aware ETA, per-leg ETA, route geometry, or map matching.

package/server/src/Tracking/Support/FakeTrackingProvider.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace Fleetbase\FleetOps\Tracking\Support;
+
+use Fleetbase\FleetOps\Tracking\Contracts\TrackingProviderInterface;
+use Fleetbase\FleetOps\Tracking\Providers\CalculatedTrackingProvider;
+use Fleetbase\FleetOps\Tracking\TrackingContext;
+use Fleetbase\FleetOps\Tracking\TrackingOptions;
+use Fleetbase\FleetOps\Tracking\TrackingProviderCapabilities;
+use Fleetbase\FleetOps\Tracking\TrackingProviderResult;
+
+class FakeTrackingProvider implements TrackingProviderInterface
+{
+    public function __construct(protected string $providerKey = 'fake')
+    {
+    }
+
+    public function key(): string
+    {
+        return $this->providerKey;
+    }
+
+    public function capabilities(): TrackingProviderCapabilities
+    {
+        return new TrackingProviderCapabilities(traffic: true, perLegEta: true);
+    }
+
+    public function canTrack(TrackingContext $context): bool
+    {
+        return $context->canRoute();
+    }
+
+    public function track(TrackingContext $context, TrackingOptions $options): TrackingProviderResult
+    {
+        $result             = (new CalculatedTrackingProvider())->track($context, $options);
+        $result->provider   = $this->providerKey;
+        $result->confidence = 'high';
+        $result->warnings   = [];
+
+        return $result;
+    }
+}

package/server/src/Tracking/TrackingContext.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace Fleetbase\FleetOps\Tracking;
+
+use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Payload;
+use Fleetbase\LaravelMysqlSpatial\Types\Point;
+use Illuminate\Support\Collection;
+
+class TrackingContext
+{
+    public function __construct(
+        public Order $order,
+        public ?Payload $payload,
+        public ?Driver $driver,
+        public ?Point $origin,
+        public ?Point $driverLocation,
+        public Collection $stops,
+        public Collection $completedStops,
+        public Collection $remainingStops,
+        public ?TrackingStop $activeStop,
+        public ?TrackingStop $nextStop,
+        public ?int $driverLocationAgeSeconds,
+        public array $warnings = [],
+    ) {
+    }
+
+    public function routePoints(): array
+    {
+        $points = [];
+        if ($this->origin) {
+            $points[] = $this->origin;
+        }
+
+        foreach ($this->remainingStops as $stop) {
+            $point = $stop instanceof TrackingStop ? $stop->point() : null;
+            if ($point) {
+                $points[] = $point;
+            }
+        }
+
+        return $points;
+    }
+
+    public function canRoute(): bool
+    {
+        return count($this->routePoints()) >= 2;
+    }
+
+    public function stateSignature(): string
+    {
+        return md5(json_encode($this->stops->map(function (TrackingStop $stop) {
+            return [
+                'uuid'      => $stop->uuid,
+                'type'      => $stop->type,
+                'status'    => $stop->status,
+                'completed' => $stop->completed,
+                'sequence'  => $stop->sequence,
+            ];
+        })->values()->all()));
+    }
+}

package/server/src/Tracking/TrackingContextBuilder.php

@@ -0,0 +1,204 @@
+<?php
+
+namespace Fleetbase\FleetOps\Tracking;
+
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Place;
+use Fleetbase\FleetOps\Models\Waypoint;
+use Fleetbase\FleetOps\Support\Utils;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Str;
+
+class TrackingContextBuilder
+{
+    public function build(Order $order, TrackingOptions $options): TrackingContext
+    {
+        $order->loadAssignedDriver();
+        $order->loadMissing([
+            'payload',
+            'payload.pickup',
+            'payload.dropoff',
+            'payload.waypoints',
+            'payload.waypointMarkers.place',
+        ]);
+
+        $payload           = $order->payload;
+        $driver            = $order->driverAssigned;
+        $warnings          = [];
+        $driverLocationAge = $driver?->updated_at ? now()->diffInSeconds($driver->updated_at) : null;
+
+        $origin         = null;
+        $driverLocation = null;
+        if ($driver && $driver->location) {
+            try {
+                $driverLocation = Utils::getPointFromMixed($driver);
+                if (!$this->isValidPoint($driverLocation)) {
+                    $driverLocation = null;
+                }
+            } catch (\Throwable) {
+                $driverLocation = null;
+            }
+        }
+
+        if ($driverLocation) {
+            $origin = $driverLocation;
+        } else {
+            $warnings[] = 'missing_driver_location';
+            $origin     = $this->fallbackOrigin($payload);
+        }
+
+        if ($driverLocationAge !== null && $driverLocationAge > $options->staleLocationThresholdSeconds) {
+            $warnings[] = 'stale_driver_location';
+        }
+
+        $stops          = $this->stops($payload, $order);
+        $completedStops = $stops->filter(fn (TrackingStop $stop) => $stop->completed)->values();
+        $remainingStops = $stops->reject(fn (TrackingStop $stop) => $stop->completed)->values();
+        $activeStop     = $this->activeStop($payload, $remainingStops);
+        $nextStop       = $remainingStops->first(fn (TrackingStop $stop) => !$activeStop || $stop->uuid !== $activeStop->uuid);
+
+        if (!$activeStop && $remainingStops->isNotEmpty()) {
+            $activeStop = $remainingStops->first();
+        }
+
+        $missingStopLocations = $remainingStops->filter(fn (TrackingStop $stop) => !$stop->point())->count();
+        if ($missingStopLocations > 0) {
+            $warnings[] = 'missing_stop_location';
+        }
+
+        return new TrackingContext(
+            order: $order,
+            payload: $payload,
+            driver: $driver,
+            origin: $origin,
+            driverLocation: $driverLocation,
+            stops: $stops,
+            completedStops: $completedStops,
+            remainingStops: $remainingStops,
+            activeStop: $activeStop,
+            nextStop: $nextStop,
+            driverLocationAgeSeconds: $driverLocationAge,
+            warnings: array_values(array_unique($warnings))
+        );
+    }
+
+    protected function stops($payload, Order $order): Collection
+    {
+        if (!$payload) {
+            return collect();
+        }
+
+        $stops    = collect();
+        $sequence = 0;
+
+        if ($payload->pickup instanceof Place) {
+            $stops->push(new TrackingStop(
+                uuid: $payload->pickup->uuid,
+                publicId: $payload->pickup->public_id,
+                type: 'pickup',
+                status: null,
+                place: $payload->pickup,
+                completed: !in_array($order->status, ['created', 'dispatched', 'pending']),
+                sequence: ++$sequence
+            ));
+        }
+
+        $markers = $payload->waypointMarkers instanceof Collection ? $payload->waypointMarkers : collect();
+        if ($markers->isNotEmpty()) {
+            foreach ($markers->sortBy('order')->values() as $waypoint) {
+                $stops->push($this->stopFromWaypoint($waypoint, ++$sequence));
+            }
+        } elseif ($payload->waypoints instanceof Collection) {
+            foreach ($payload->waypoints as $place) {
+                if ($place instanceof Place) {
+                    $stops->push(new TrackingStop(
+                        uuid: $place->uuid,
+                        publicId: $place->public_id,
+                        type: 'waypoint',
+                        status: null,
+                        place: $place,
+                        completed: false,
+                        sequence: ++$sequence
+                    ));
+                }
+            }
+        }
+
+        if ($payload->dropoff instanceof Place) {
+            $stops->push(new TrackingStop(
+                uuid: $payload->dropoff->uuid,
+                publicId: $payload->dropoff->public_id,
+                type: 'dropoff',
+                status: null,
+                place: $payload->dropoff,
+                completed: in_array($order->status, ['completed', 'canceled']),
+                sequence: ++$sequence
+            ));
+        }
+
+        return $stops->values();
+    }
+
+    protected function stopFromWaypoint(Waypoint $waypoint, int $sequence): TrackingStop
+    {
+        $waypoint->loadMissing('place');
+        $status = strtolower((string) $waypoint->status_code);
+
+        return new TrackingStop(
+            uuid: $waypoint->place_uuid,
+            publicId: data_get($waypoint, 'place.public_id'),
+            type: 'waypoint',
+            status: $status ?: null,
+            place: $waypoint->place,
+            waypoint: $waypoint,
+            completed: in_array($status, ['completed', 'canceled']),
+            sequence: $sequence
+        );
+    }
+
+    protected function activeStop($payload, Collection $remainingStops): ?TrackingStop
+    {
+        if (!$payload || !$payload->current_waypoint_uuid || !Str::isUuid($payload->current_waypoint_uuid)) {
+            return $remainingStops->first();
+        }
+
+        return $remainingStops->first(function (TrackingStop $stop) use ($payload) {
+            return $stop->uuid === $payload->current_waypoint_uuid
+                || data_get($stop->waypoint, 'uuid') === $payload->current_waypoint_uuid
+                || data_get($stop->waypoint, 'place_uuid') === $payload->current_waypoint_uuid;
+        });
+    }
+
+    protected function fallbackOrigin($payload)
+    {
+        if (!$payload) {
+            return null;
+        }
+
+        try {
+            $point = Utils::getPointFromMixed($payload->getPickupOrCurrentWaypoint());
+
+            return $this->isValidPoint($point) ? $point : null;
+        } catch (\Throwable) {
+            return null;
+        }
+    }
+
+    protected function isValidPoint($point): bool
+    {
+        if (!$point || !method_exists($point, 'getLat') || !method_exists($point, 'getLng')) {
+            return false;
+        }
+
+        $lat = (float) $point->getLat();
+        $lng = (float) $point->getLng();
+
+        return is_finite($lat)
+            && is_finite($lng)
+            && $lat >= -90
+            && $lat <= 90
+            && $lng >= -180
+            && $lng <= 180
+            && !(abs($lat) < 0.000001 && abs($lng) < 0.000001);
+    }
+}