@fleetbase/fleetops-engine 0.6.37 → 0.6.39

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

@@ -0,0 +1,265 @@
+<?php
+
+namespace Fleetbase\FleetOps\Orchestration\Engines;
+
+use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Vehicle;
+use Illuminate\Support\Collection;
+
+/**
+ * DriverAssignmentEngine.
+ *
+ * Greedy shift-aware engine for matching available drivers to vehicles that
+ * have planned orders (vehicle_assigned_uuid set, driver_assigned_uuid null).
+ *
+ * Matching priority:
+ *   1. Driver is online and on an active shift
+ *   2. Driver skills satisfy the required skills of the vehicle's planned orders
+ *   3. Driver is geographically closest to the vehicle's current location
+ *
+ * This engine does not use VROOM — it is a deterministic greedy pass.
+ * For V2, a VROOM-based multi-depot driver assignment can replace this.
+ */
+class DriverAssignmentEngine
+{
+    /**
+     * Assign available drivers to vehicles with planned orders.
+     *
+     * @param Collection $orders   Orders with vehicle_assigned_uuid set but no driver
+     * @param Collection $vehicles Vehicles to assign drivers to
+     * @param array      $options  Options: require_active_shift (bool, default true)
+     *
+     * @return array{assignments: array, unassigned: array, summary: array}
+     */
+    public function assign(Collection $orders, Collection $vehicles, array $options = []): array
+    {
+        $requireActiveShift = $options['require_active_shift'] ?? false;
+        $respectSkills      = $options['respect_skills'] ?? true;
+
+        // Collect all company drivers — online status and vehicle linkage are
+        // treated as soft preferences (scored), not hard filters.
+        $companyUuid      = $orders->first()?->company_uuid;
+        $availableDrivers = Driver::where('company_uuid', $companyUuid)
+            ->with(['scheduleItems'])
+            ->get();
+
+        // Shift-awareness: if require_active_shift is explicitly set, filter
+        // to drivers that have an active shift right now. Drivers with NO
+        // schedule items at all are treated as always available — only drivers
+        // with a schedule but no active shift are excluded.
+        if ($requireActiveShift) {
+            $availableDrivers = $availableDrivers->filter(function (Driver $driver) {
+                $hasSchedule = $driver->scheduleItems && $driver->scheduleItems->isNotEmpty();
+                // No schedule → always available
+                if (!$hasSchedule) {
+                    return true;
+                }
+
+                // Has a schedule → must have an active shift right now
+                return $driver->activeShiftFor(now()) !== null;
+            });
+        }
+
+        if ($availableDrivers->isEmpty()) {
+            return [
+                'assignments' => [],
+                'unassigned'  => $vehicles->pluck('public_id')->toArray(),
+                'summary'     => ['message' => 'No available drivers found.'],
+            ];
+        }
+
+        $assignments        = [];
+        $assignedDrivers    = [];
+        $assignedVehicles   = [];
+        $unassignedOrders   = [];
+
+        // Determine if this is a standalone run (no prior vehicle assignment)
+        // or a post-vehicle-assignment run.
+        $hasVehicleAssignments = $orders->filter(fn ($o) => !empty($o->vehicle_assigned_uuid))->isNotEmpty();
+
+        if ($hasVehicleAssignments) {
+            // ── Post-vehicle-assignment mode ──────────────────────────────────
+            // Orders already have a vehicle. Group by vehicle and find the
+            // best driver for each vehicle group.
+            $ordersByVehicle = $orders->groupBy('vehicle_assigned_uuid');
+
+            foreach ($vehicles as $vehicle) {
+                $vehicleOrders  = $ordersByVehicle->get($vehicle->uuid, collect());
+                $requiredSkills = $this->aggregateRequiredSkills($vehicleOrders);
+
+                $bestDriver = $this->findBestDriver(
+                    $vehicle,
+                    $availableDrivers->reject(fn ($d) => in_array($d->uuid, $assignedDrivers)),
+                    $requiredSkills,
+                    $respectSkills
+                );
+
+                if (!$bestDriver) {
+                    foreach ($vehicleOrders as $order) {
+                        $unassignedOrders[] = $order->public_id;
+                    }
+                    continue;
+                }
+
+                $assignedDrivers[] = $bestDriver->uuid;
+
+                foreach ($vehicleOrders as $order) {
+                    $assignments[] = [
+                        'order_id'   => $order->public_id,
+                        'vehicle_id' => $vehicle->public_id,
+                        'driver_id'  => $bestDriver->public_id,
+                        'sequence'   => null,
+                    ];
+                }
+            }
+        } else {
+            // ── Standalone mode ───────────────────────────────────────────────
+            // No prior vehicle assignment. Assign each order to the nearest
+            // available vehicle + best matching driver pair.
+            $availableVehicles = $vehicles->values();
+
+            foreach ($orders as $order) {
+                // Find the nearest unassigned vehicle
+                $pickupLat = $order->payload?->pickup?->location?->getLat();
+                $pickupLng = $order->payload?->pickup?->location?->getLng();
+
+                $bestVehicle = $availableVehicles
+                    ->reject(fn ($v) => in_array($v->uuid, $assignedVehicles))
+                    ->sortBy(function ($vehicle) use ($pickupLat, $pickupLng) {
+                        if (!$pickupLat || !$pickupLng || !$vehicle->location) {
+                            return PHP_INT_MAX;
+                        }
+
+                        return $this->haversineDistance(
+                            $pickupLat, $pickupLng,
+                            $vehicle->location->getLat(), $vehicle->location->getLng()
+                        );
+                    })
+                    ->first();
+
+                if (!$bestVehicle) {
+                    $unassignedOrders[] = $order->public_id;
+                    continue;
+                }
+
+                $requiredSkills = $order->required_skills ?? [];
+                $bestDriver     = $this->findBestDriver(
+                    $bestVehicle,
+                    $availableDrivers->reject(fn ($d) => in_array($d->uuid, $assignedDrivers)),
+                    $requiredSkills,
+                    $respectSkills
+                );
+
+                if (!$bestDriver) {
+                    $unassignedOrders[] = $order->public_id;
+                    continue;
+                }
+
+                $assignedVehicles[] = $bestVehicle->uuid;
+                $assignedDrivers[]  = $bestDriver->uuid;
+
+                $assignments[] = [
+                    'order_id'   => $order->public_id,
+                    'vehicle_id' => $bestVehicle->public_id,
+                    'driver_id'  => $bestDriver->public_id,
+                    'sequence'   => null,
+                ];
+            }
+        }
+
+        return [
+            'assignments' => $assignments,
+            'unassigned'  => $unassignedOrders,
+            'summary'     => [
+                'drivers_assigned'    => count($assignedDrivers),
+                'vehicles_assigned'   => count($assignedVehicles),
+            ],
+        ];
+    }
+
+    /**
+     * Find the best available driver for a given vehicle.
+     *
+     * Scoring:
+     *   - Skills match: +100 per matching skill
+     *   - Active shift: +50
+     *   - Proximity: inversely proportional to distance (max +50)
+     */
+    protected function findBestDriver(
+        Vehicle $vehicle,
+        Collection $availableDrivers,
+        array $requiredSkills,
+        bool $respectSkills,
+    ): ?Driver {
+        if ($availableDrivers->isEmpty()) {
+            return null;
+        }
+
+        $vehicleLat = $vehicle->location?->getLat();
+        $vehicleLng = $vehicle->location?->getLng();
+
+        $scored = $availableDrivers->map(function (Driver $driver) use (
+            $requiredSkills, $respectSkills, $vehicleLat, $vehicleLng
+        ) {
+            $score = 0;
+
+            // Skills check
+            if ($respectSkills && !empty($requiredSkills)) {
+                $driverSkills = $driver->skills ?? [];
+                $matchCount   = count(array_intersect($requiredSkills, $driverSkills));
+                if ($matchCount < count($requiredSkills)) {
+                    // Driver does not meet all required skills — disqualify
+                    return null;
+                }
+                $score += $matchCount * 100;
+            }
+
+            // Online bonus
+            if ($driver->online) {
+                $score += 30;
+            }
+            // Active shift bonus — only meaningful if the driver has a schedule
+            $hasSchedule = $driver->scheduleItems && $driver->scheduleItems->isNotEmpty();
+            if ($hasSchedule && $driver->activeShiftFor(now()) !== null) {
+                $score += 50;
+            }
+
+            // Proximity bonus (only if vehicle has a known location)
+            if ($vehicleLat && $vehicleLng && $driver->location) {
+                $distance = $this->haversineDistance(
+                    $vehicleLat, $vehicleLng,
+                    $driver->location->getLat(), $driver->location->getLng()
+                );
+                // Closer = higher score; cap at 50 points for distance ≤ 1 km
+                $proximityScore = max(0, 50 - ($distance / 1000));
+                $score += $proximityScore;
+            }
+
+            return ['driver' => $driver, 'score' => $score];
+        })->filter()->sortByDesc('score');
+
+        return $scored->first()['driver'] ?? null;
+    }
+
+    /**
+     * Aggregate the unique required skills from a collection of orders.
+     */
+    protected function aggregateRequiredSkills(Collection $orders): array
+    {
+        return $orders->flatMap(fn ($o) => $o->required_skills ?? [])->unique()->values()->toArray();
+    }
+
+    /**
+     * Calculate the Haversine distance in metres between two lat/lng points.
+     */
+    protected function haversineDistance(float $lat1, float $lng1, float $lat2, float $lng2): float
+    {
+        $earthRadius = 6371000; // metres
+        $dLat        = deg2rad($lat2 - $lat1);
+        $dLng        = deg2rad($lng2 - $lng1);
+        $a           = sin($dLat / 2) ** 2 + cos(deg2rad($lat1)) * cos(deg2rad($lat2)) * sin($dLng / 2) ** 2;
+
+        return $earthRadius * 2 * atan2(sqrt($a), sqrt(1 - $a));
+    }
+}

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

@@ -0,0 +1,155 @@
+<?php
+
+namespace Fleetbase\FleetOps\Orchestration\Engines;
+
+use Fleetbase\FleetOps\Orchestration\Contracts\OrchestrationEngineInterface;
+use Illuminate\Support\Collection;
+
+/**
+ * GreedyOrchestrationEngine.
+ *
+ * A simple, dependency-free allocation engine that assigns orders to vehicles
+ * without requiring an external routing service such as VROOM.
+ *
+ * Algorithm:
+ *   1. Sort orders by priority (descending) then scheduled_at (ascending).
+ *   2. For each order, find the nearest available vehicle (by Haversine distance
+ *      from the vehicle/driver location to the order pickup point).
+ *   3. Assign the order to that vehicle and mark the vehicle as "occupied" for
+ *      the purpose of this run (one order per vehicle per run by default; pass
+ *      `allow_multi_order = true` in $options to allow multiple orders per vehicle).
+ *
+ * This engine is registered as 'greedy' in the OrchestrationEngineRegistry and is
+ * used automatically when VROOM is unavailable or when the user explicitly
+ * selects it in the orchestrator settings.
+ */
+class GreedyOrchestrationEngine implements OrchestrationEngineInterface
+{
+    public function getName(): string
+    {
+        return 'Greedy (built-in)';
+    }
+
+    public function getIdentifier(): string
+    {
+        return 'greedy';
+    }
+
+    /**
+     * Run the greedy nearest-vehicle assignment.
+     */
+    public function allocate(Collection $orders, Collection $vehicles, array $options = []): array
+    {
+        $allowMulti = (bool) ($options['allow_multi_order'] ?? false);
+
+        // Sort orders: highest priority first, then earliest scheduled_at
+        $sorted = $orders->sortBy([
+            fn ($a, $b) => ($b->orchestrator_priority ?? 0) <=> ($a->orchestrator_priority ?? 0),
+            fn ($a, $b) => ($a->scheduled_at ?? now()) <=> ($b->scheduled_at ?? now()),
+        ])->values();
+
+        // Build a mutable list of available vehicles with their current location
+        $vehiclePool = $vehicles->map(function ($vehicle) {
+            $driver   = $vehicle->driver;
+            $location = $driver?->location ?? $vehicle->location;
+
+            return [
+                'model'     => $vehicle,
+                'id'        => $vehicle->public_id,
+                'driver_id' => $driver?->public_id,
+                'lat'       => $location?->getLat(),
+                'lng'       => $location?->getLng(),
+                'assigned'  => 0,
+            ];
+        })->values()->toArray();
+
+        $assignments = [];
+        $unassigned  = [];
+
+        foreach ($sorted as $order) {
+            $pickupLat = $order->payload?->pickup?->lat ?? null;
+            $pickupLng = $order->payload?->pickup?->lng ?? null;
+
+            // Find the best vehicle: nearest with capacity remaining
+            $bestIdx  = null;
+            $bestDist = PHP_INT_MAX;
+
+            foreach ($vehiclePool as $idx => $v) {
+                // In single-order mode, skip vehicles that already have an assignment
+                if (!$allowMulti && $v['assigned'] > 0) {
+                    continue;
+                }
+
+                if ($v['lat'] === null || $v['lng'] === null) {
+                    // Vehicle has no known location — eligible but deprioritised
+                    if ($bestIdx === null) {
+                        $bestIdx = $idx;
+                    }
+                    continue;
+                }
+
+                if ($pickupLat !== null && $pickupLng !== null) {
+                    $dist = $this->haversineDistance($v['lat'], $v['lng'], (float) $pickupLat, (float) $pickupLng);
+                } else {
+                    $dist = 0; // No pickup location — treat as zero distance
+                }
+
+                if ($dist < $bestDist) {
+                    $bestDist = $dist;
+                    $bestIdx  = $idx;
+                }
+            }
+
+            if ($bestIdx === null) {
+                $unassigned[] = $order->public_id;
+                continue;
+            }
+
+            $v = $vehiclePool[$bestIdx];
+
+            $assignments[] = [
+                'order_id'   => $order->public_id,
+                'vehicle_id' => $v['id'],
+                'driver_id'  => $v['driver_id'],
+                'sequence'   => ++$vehiclePool[$bestIdx]['assigned'],
+                'arrival'    => null,
+                'duration'   => null,
+                'distance'   => $bestDist < PHP_INT_MAX ? (int) round($bestDist) : null,
+            ];
+
+            // Update vehicle's "current position" to the order dropoff so the
+            // next order assigned to this vehicle is measured from the dropoff.
+            if ($allowMulti) {
+                $dropoffLat = $order->payload?->dropoff?->lat;
+                $dropoffLng = $order->payload?->dropoff?->lng;
+                if ($dropoffLat !== null && $dropoffLng !== null) {
+                    $vehiclePool[$bestIdx]['lat'] = (float) $dropoffLat;
+                    $vehiclePool[$bestIdx]['lng'] = (float) $dropoffLng;
+                }
+            }
+        }
+
+        return [
+            'assignments' => $assignments,
+            'unassigned'  => $unassigned,
+            'summary'     => [
+                'engine'     => 'greedy',
+                'assigned'   => count($assignments),
+                'unassigned' => count($unassigned),
+            ],
+        ];
+    }
+
+    /**
+     * Haversine distance in metres between two lat/lng points.
+     */
+    protected function haversineDistance(float $lat1, float $lng1, float $lat2, float $lng2): float
+    {
+        $R    = 6371000;
+        $dLat = deg2rad($lat2 - $lat1);
+        $dLng = deg2rad($lng2 - $lng1);
+        $a    = sin($dLat / 2) ** 2 + cos(deg2rad($lat1)) * cos(deg2rad($lat2)) * sin($dLng / 2) ** 2;
+
+        return $R * 2 * atan2(sqrt($a), sqrt(1 - $a));
+    }
+}

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

@@ -0,0 +1,272 @@
+<?php
+
+namespace Fleetbase\FleetOps\Orchestration\Engines;
+
+use Illuminate\Support\Collection;
+
+/**
+ * RouteSequencingEngine.
+ *
+ * Used for the `optimize_routes` orchestration mode.
+ *
+ * Unlike the allocation engines (Greedy, VROOM), this engine does NOT
+ * re-assign orders to vehicles. Instead it:
+ *
+ *   1. Groups the provided orders by their already-assigned vehicle
+ *      (vehicle_assigned_uuid).
+ *   2. For each vehicle group, sequences the stops in an optimal order
+ *      using a nearest-neighbour TSP heuristic.
+ *   3. Returns one assignment entry per order, preserving the existing
+ *      vehicle_id / driver_id and updating only the sequence number.
+ *
+ * This ensures that running "Assign Vehicles" followed by "Optimize Routes"
+ * produces one properly-sequenced route per vehicle rather than re-running
+ * the allocation algorithm.
+ */
+class RouteSequencingEngine
+{
+    /**
+     * Sequence stops for each vehicle group.
+     *
+     * @param Collection $orders  Orders with payload.pickup, payload.dropoff, payload.waypoints loaded
+     * @param array      $options Engine options (currently unused, reserved for future use)
+     *
+     * @return array Standard orchestration result: { assignments, unassigned, summary }
+     */
+    public function sequence(Collection $orders, array $options = []): array
+    {
+        $assignments = [];
+        $unassigned  = [];
+
+        // Group orders by their currently assigned vehicle UUID
+        $byVehicle = [];
+        foreach ($orders as $order) {
+            $vehicleUuid = $order->vehicle_assigned_uuid ?? null;
+            if (!$vehicleUuid) {
+                // Order has no vehicle assignment — cannot sequence it
+                $unassigned[] = $order->public_id;
+                continue;
+            }
+            $byVehicle[$vehicleUuid][] = $order;
+        }
+
+        foreach ($byVehicle as $vehicleUuid => $vehicleOrders) {
+            $vehicle = $vehicleOrders[0]->vehicle ?? null;
+
+            // Determine driver public_id from the vehicle relationship
+            $driverPublicId = null;
+            if ($vehicle && $vehicle->driver) {
+                $driverPublicId = $vehicle->driver->public_id ?? null;
+            }
+
+            // Get vehicle's current location as the starting point for sequencing
+            $startLat = null;
+            $startLng = null;
+            if ($vehicle) {
+                $driver   = $vehicle->driver;
+                $location = $driver?->location ?? $vehicle->location;
+                $startLat = $location?->getLat();
+                $startLng = $location?->getLng();
+            }
+
+            // Build a flat list of stops: each order contributes pickup + dropoff
+            // (or waypoints for multi-drop orders). We keep pickup before its own
+            // dropoff as a hard constraint.
+            $sequenced = $this->_sequenceOrdersForVehicle($vehicleOrders, $startLat, $startLng);
+
+            // Build assignment entries — one per order, with the sequence number
+            // being the position of the order's FIRST stop in the sequenced list.
+            $orderSequences = [];
+            foreach ($sequenced as $seq => $stop) {
+                $orderId = $stop['order_public_id'];
+                // Only record the first occurrence (pickup position) per order
+                if (!isset($orderSequences[$orderId])) {
+                    $orderSequences[$orderId] = $seq + 1; // 1-based
+                }
+            }
+
+            foreach ($vehicleOrders as $order) {
+                $assignments[] = [
+                    'order_id'          => $order->public_id,
+                    'vehicle_id'        => $vehicle?->public_id ?? $vehicleUuid,
+                    'driver_id'         => $driverPublicId,
+                    'sequence'          => $orderSequences[$order->public_id] ?? 1,
+                    'waypoint_sequence' => null,
+                    'arrival'           => null,
+                    'duration'          => null,
+                    'distance'          => null,
+                ];
+            }
+        }
+
+        return [
+            'assignments' => $assignments,
+            'unassigned'  => $unassigned,
+            'summary'     => [
+                'engine'     => 'route_sequencing',
+                'assigned'   => count($assignments),
+                'unassigned' => count($unassigned),
+            ],
+        ];
+    }
+
+    /**
+     * Sequence stops for a single vehicle's orders using nearest-neighbour TSP.
+     *
+     * Constraints:
+     *   - Each order's pickup must appear before its dropoff (precedence constraint).
+     *   - Starts from the vehicle/driver's current location if known.
+     *
+     * @param array      $orders   Array of Order models
+     * @param float|null $startLat Vehicle starting latitude
+     * @param float|null $startLng Vehicle starting longitude
+     *
+     * @return array Ordered array of stop records: { order_public_id, lat, lng, type }
+     */
+    protected function _sequenceOrdersForVehicle(array $orders, ?float $startLat, ?float $startLng): array
+    {
+        // Build a flat pool of stops with precedence constraints
+        $pool = [];
+        foreach ($orders as $order) {
+            $payload = $order->payload;
+            if (!$payload) {
+                continue;
+            }
+
+            $waypoints    = $payload->waypoints;
+            $hasWaypoints = $waypoints && $waypoints->count() > 0;
+            $isMultiDrop  = $hasWaypoints && !$payload->pickup_uuid && !$payload->dropoff_uuid;
+
+            if ($isMultiDrop) {
+                // Multi-drop: add each waypoint as a stop
+                $sorted = $waypoints->sortBy('order')->values();
+                foreach ($sorted as $idx => $wp) {
+                    $place = $wp->place;
+                    if (!$place) {
+                        continue;
+                    }
+                    $pool[] = [
+                        'order_public_id'  => $order->public_id,
+                        'lat'              => (float) ($place->lat ?? 0),
+                        'lng'              => (float) ($place->lng ?? 0),
+                        'type'             => 'waypoint',
+                        'precedence_after' => $idx > 0 ? ($pool[count($pool) - 1]['id'] ?? null) : null,
+                        'id'               => $order->public_id . '_wp_' . $idx,
+                    ];
+                }
+            } else {
+                // Standard pickup → dropoff
+                $pickup  = $payload->pickup;
+                $dropoff = $payload->dropoff;
+
+                $pickupId  = $order->public_id . '_pickup';
+                $dropoffId = $order->public_id . '_dropoff';
+
+                if ($pickup && $pickup->lat && $pickup->lng) {
+                    $pool[] = [
+                        'order_public_id'  => $order->public_id,
+                        'lat'              => (float) $pickup->lat,
+                        'lng'              => (float) $pickup->lng,
+                        'type'             => 'pickup',
+                        'precedence_after' => null, // pickup has no prerequisite
+                        'id'               => $pickupId,
+                        'blocks'           => $dropoffId, // dropoff must come after this
+                    ];
+                }
+
+                if ($dropoff && $dropoff->lat && $dropoff->lng) {
+                    $pool[] = [
+                        'order_public_id'  => $order->public_id,
+                        'lat'              => (float) $dropoff->lat,
+                        'lng'              => (float) $dropoff->lng,
+                        'type'             => 'dropoff',
+                        'precedence_after' => $pickupId, // must come after pickup
+                        'id'               => $dropoffId,
+                    ];
+                }
+            }
+        }
+
+        if (empty($pool)) {
+            return [];
+        }
+
+        // Nearest-neighbour TSP with precedence constraints
+        $visited  = [];
+        $sequence = [];
+        $curLat   = $startLat;
+        $curLng   = $startLng;
+
+        while (count($visited) < count($pool)) {
+            $bestIdx  = null;
+            $bestDist = PHP_INT_MAX;
+
+            foreach ($pool as $idx => $stop) {
+                if (in_array($idx, $visited)) {
+                    continue;
+                }
+
+                // Check precedence: if this stop requires another stop to come first
+                if (!empty($stop['precedence_after'])) {
+                    $prerequisiteId   = $stop['precedence_after'];
+                    $prerequisiteDone = false;
+                    foreach ($sequence as $done) {
+                        if ($done['id'] === $prerequisiteId) {
+                            $prerequisiteDone = true;
+                            break;
+                        }
+                    }
+                    if (!$prerequisiteDone) {
+                        continue;
+                    } // not yet eligible
+                }
+
+                if ($curLat === null || $curLng === null) {
+                    // No current position — just pick the first eligible stop
+                    $bestIdx = $idx;
+                    break;
+                }
+
+                $dist = $this->_haversine($curLat, $curLng, $stop['lat'], $stop['lng']);
+                if ($dist < $bestDist) {
+                    $bestDist = $dist;
+                    $bestIdx  = $idx;
+                }
+            }
+
+            if ($bestIdx === null) {
+                // No eligible stop found — add all remaining stops in original order
+                // (safety fallback to avoid infinite loop)
+                foreach ($pool as $idx => $stop) {
+                    if (!in_array($idx, $visited)) {
+                        $visited[]  = $idx;
+                        $sequence[] = $stop;
+                        $curLat     = $stop['lat'];
+                        $curLng     = $stop['lng'];
+                    }
+                }
+                break;
+            }
+
+            $visited[]  = $bestIdx;
+            $sequence[] = $pool[$bestIdx];
+            $curLat     = $pool[$bestIdx]['lat'];
+            $curLng     = $pool[$bestIdx]['lng'];
+        }
+
+        return $sequence;
+    }
+
+    /**
+     * Haversine distance in metres.
+     */
+    protected function _haversine(float $lat1, float $lng1, float $lat2, float $lng2): float
+    {
+        $R    = 6371000;
+        $dLat = deg2rad($lat2 - $lat1);
+        $dLng = deg2rad($lng2 - $lng1);
+        $a    = sin($dLat / 2) ** 2 + cos(deg2rad($lat1)) * cos(deg2rad($lat2)) * sin($dLng / 2) ** 2;
+
+        return $R * 2 * atan2(sqrt($a), sqrt(1 - $a));
+    }
+}