@fleetbase/fleetops-engine 0.6.42 → 0.6.44

package/server/src/Http/Controllers/Api/v1/VehicleController.php

@@ -2,17 +2,23 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Api\v1;
 
+use Fleetbase\FleetOps\Events\GeofenceEntered;
+use Fleetbase\FleetOps\Events\GeofenceExited;
 use Fleetbase\FleetOps\Events\VehicleLocationChanged;
 use Fleetbase\FleetOps\Http\Requests\CreateVehicleRequest;
 use Fleetbase\FleetOps\Http\Requests\UpdateVehicleRequest;
 use Fleetbase\FleetOps\Http\Resources\v1\DeletedResource;
 use Fleetbase\FleetOps\Http\Resources\v1\Vehicle as VehicleResource;
+use Fleetbase\FleetOps\Jobs\CheckGeofenceDwell;
 use Fleetbase\FleetOps\Models\Driver;
 use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Support\GeofenceIntersectionService;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Http\Controllers\Controller;
 use Fleetbase\LaravelMysqlSpatial\Types\Point;
 use Illuminate\Http\Request;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Facades\DB;
 
 class VehicleController extends Controller
 {
@@ -276,6 +282,88 @@ class VehicleController extends Controller
 
         broadcast(new VehicleLocationChanged($vehicle));
 
+        try {
+            $newLocation     = new Point($latitude, $longitude);
+            $geofenceService = app(GeofenceIntersectionService::class);
+            $this->processVehicleGeofenceCrossings($vehicle, $newLocation, $geofenceService->detectVehicleCrossings($vehicle, $newLocation));
+        } catch (\Throwable $geofenceException) {
+            if (app()->bound('sentry')) {
+                app('sentry')->captureException($geofenceException);
+            }
+        }
+
         return new VehicleResource($vehicle);
     }
+
+    private function processVehicleGeofenceCrossings(Vehicle $vehicle, Point $newLocation, array $crossings): void
+    {
+        foreach ($crossings as $crossing) {
+            $geofence     = $crossing['geofence'];
+            $geofenceType = $crossing['geofence_type'];
+
+            if ($crossing['type'] === 'entered') {
+                if (!$geofence->trigger_on_entry && empty($geofence->dwell_threshold_minutes)) {
+                    continue;
+                }
+
+                DB::table('vehicle_geofence_states')->upsert(
+                    [
+                        'vehicle_uuid'  => $vehicle->uuid,
+                        'geofence_uuid' => $geofence->uuid,
+                        'geofence_type' => $geofenceType,
+                        'is_inside'     => true,
+                        'entered_at'    => now(),
+                        'exited_at'     => null,
+                        'dwell_job_id'  => null,
+                        'created_at'    => now(),
+                        'updated_at'    => now(),
+                    ],
+                    ['vehicle_uuid', 'geofence_uuid'],
+                    ['is_inside', 'entered_at', 'exited_at', 'dwell_job_id', 'updated_at']
+                );
+
+                if ($geofence->trigger_on_entry) {
+                    event(new GeofenceEntered($vehicle, $geofence, $geofenceType, $newLocation));
+                }
+
+                if ($geofence->dwell_threshold_minutes > 0) {
+                    $dwellJob = CheckGeofenceDwell::dispatch(
+                        $vehicle->uuid,
+                        $geofence->uuid,
+                        $geofenceType,
+                        'vehicle'
+                    )->delay(now()->addMinutes($geofence->dwell_threshold_minutes));
+
+                    DB::table('vehicle_geofence_states')
+                        ->where('vehicle_uuid', $vehicle->uuid)
+                        ->where('geofence_uuid', $geofence->uuid)
+                        ->update(['dwell_job_id' => (string) $dwellJob]);
+                }
+            } elseif ($crossing['type'] === 'exited') {
+                $state = DB::table('vehicle_geofence_states')
+                    ->where('vehicle_uuid', $vehicle->uuid)
+                    ->where('geofence_uuid', $geofence->uuid)
+                    ->first();
+
+                $dwellMinutes = null;
+                if ($state && $state->entered_at) {
+                    $dwellMinutes = (int) Carbon::parse($state->entered_at)->diffInMinutes(now());
+                }
+
+                DB::table('vehicle_geofence_states')
+                    ->where('vehicle_uuid', $vehicle->uuid)
+                    ->where('geofence_uuid', $geofence->uuid)
+                    ->update([
+                        'is_inside'    => false,
+                        'exited_at'    => now(),
+                        'dwell_job_id' => null,
+                        'updated_at'   => now(),
+                    ]);
+
+                if ($geofence->trigger_on_exit) {
+                    event(new GeofenceExited($vehicle, $geofence, $geofenceType, $newLocation, $dwellMinutes));
+                }
+            }
+        }
+    }
 }

package/server/src/Http/Controllers/Api/v1/ZoneController.php

@@ -24,7 +24,7 @@ class ZoneController extends Controller
     public function create(CreateZoneRequest $request)
     {
         // get request input
-        $input = $request->only(['name', 'border', 'status', 'description', 'color', 'stroke_color']);
+        $input = $request->only(['name', 'border', 'status', 'description', 'color', 'stroke_color', 'trigger_on_entry', 'trigger_on_exit', 'dwell_threshold_minutes', 'speed_limit_kmh']);
 
         // get radius for creating zone border - default to 500 meters
         $radius = $request->input('radius', 500);
@@ -97,7 +97,7 @@ class ZoneController extends Controller
         }
 
         // get request input
-        $input = $request->only(['name', 'border', 'status', 'description', 'color', 'stroke_color']);
+        $input = $request->only(['name', 'border', 'status', 'description', 'color', 'stroke_color', 'trigger_on_entry', 'trigger_on_exit', 'dwell_threshold_minutes', 'speed_limit_kmh']);
 
         // get radius for creating zone border - default to 500 meters
         $radius = $request->input('radius', 500);

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

@@ -0,0 +1,7 @@
+<?php
+
+namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
+
+class GeofenceController extends \Fleetbase\FleetOps\Http\Controllers\Api\v1\GeofenceController
+{
+}

package/server/src/Http/Requests/CreateServiceAreaRequest.php

@@ -46,10 +46,14 @@ class CreateServiceAreaRequest extends FleetbaseRequest
 
                 return false;
             })],
-            'parent'    => ['nullable', 'exists:service_areas,public_id'],
-            'location'  => ['nullable', new ResolvablePoint()],
-            'latitude'  => ['nullable', 'required_with:longitude'],
-            'longitude' => ['nullable', 'required_with:latitude'],
+            'parent'                  => ['nullable', 'exists:service_areas,public_id'],
+            'location'                => ['nullable', new ResolvablePoint()],
+            'latitude'                => ['nullable', 'required_with:longitude'],
+            'longitude'               => ['nullable', 'required_with:latitude'],
+            'trigger_on_entry'        => ['nullable', 'boolean'],
+            'trigger_on_exit'         => ['nullable', 'boolean'],
+            'dwell_threshold_minutes' => ['nullable', 'integer', 'min:1', 'max:10080'],
+            'speed_limit_kmh'         => ['nullable', 'integer', 'min:1', 'max:1000'],
         ];
     }
 }

package/server/src/Http/Requests/CreateZoneRequest.php

@@ -45,10 +45,14 @@ class CreateZoneRequest extends FleetbaseRequest
 
                 return false;
             })],
-            'location'     => ['nullable', new ResolvablePoint()],
-            'latitude'     => ['nullable', 'required_with:longitude'],
-            'longitude'    => ['nullable', 'required_with:latitude'],
-            'status'       => ['nullable', 'in:active,inactive'],
+            'location'                => ['nullable', new ResolvablePoint()],
+            'latitude'                => ['nullable', 'required_with:longitude'],
+            'longitude'               => ['nullable', 'required_with:latitude'],
+            'status'                  => ['nullable', 'in:active,inactive'],
+            'trigger_on_entry'        => ['nullable', 'boolean'],
+            'trigger_on_exit'         => ['nullable', 'boolean'],
+            'dwell_threshold_minutes' => ['nullable', 'integer', 'min:1', 'max:10080'],
+            'speed_limit_kmh'         => ['nullable', 'integer', 'min:1', 'max:1000'],
         ];
     }
 }

package/server/src/Jobs/CheckGeofenceDwell.php

@@ -0,0 +1,139 @@
+<?php
+
+namespace Fleetbase\FleetOps\Jobs;
+
+use Fleetbase\FleetOps\Events\GeofenceDwelled;
+use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Models\ServiceArea;
+use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Models\Zone;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * CheckGeofenceDwell.
+ *
+ * A delayed queue job dispatched when a driver enters a geofence that has
+ * a dwell_threshold_minutes configured. The job is delayed by that number
+ * of minutes. When it runs, it checks whether the driver is still inside
+ * the geofence. If so, it fires the GeofenceDwelled event.
+ *
+ * If the driver exits before the job runs, the dwell_job_id in the state
+ * table is cleared, but the job still runs and exits silently because the
+ * state record will show is_inside = false.
+ *
+ * This job runs on the dedicated 'geofence' queue and has tries = 1 because
+ * dwell checks should not be retried — a failed check is simply missed.
+ */
+class CheckGeofenceDwell implements ShouldQueue
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    /**
+     * The number of times the job may be attempted.
+     * Dwell checks are fire-and-forget; retrying would produce false events.
+     */
+    public int $tries = 1;
+
+    /**
+     * The number of seconds the job can run before timing out.
+     */
+    public int $timeout = 30;
+
+    /**
+     * The UUID of the driver to check.
+     */
+    protected string $driverUuid;
+
+    /**
+     * The UUID of the geofence to check.
+     */
+    protected string $geofenceUuid;
+
+    /**
+     * The type of geofence: 'zone' or 'service_area'.
+     */
+    protected string $geofenceType;
+
+    /**
+     * The subject type for the dwell check: 'driver' or 'vehicle'.
+     */
+    protected string $subjectType;
+
+    /**
+     * Create a new CheckGeofenceDwell job.
+     *
+     * @param string $geofenceType 'zone' | 'service_area'
+     */
+    public function __construct(string $subjectUuid, string $geofenceUuid, string $geofenceType, string $subjectType = 'driver')
+    {
+        $this->driverUuid   = $subjectUuid;
+        $this->geofenceUuid = $geofenceUuid;
+        $this->geofenceType = $geofenceType;
+        $this->subjectType  = $subjectType;
+        $this->onQueue('geofence');
+    }
+
+    /**
+     * Execute the job.
+     */
+    public function handle(): void
+    {
+        // Check if the driver is still inside the geofence
+        $stateTable    = $this->subjectType === 'vehicle' ? 'vehicle_geofence_states' : 'driver_geofence_states';
+        $subjectColumn = $this->subjectType === 'vehicle' ? 'vehicle_uuid' : 'driver_uuid';
+
+        $state = DB::table($stateTable)
+            ->where($subjectColumn, $this->driverUuid)
+            ->where('geofence_uuid', $this->geofenceUuid)
+            ->where('is_inside', true)
+            ->first();
+
+        if (!$state) {
+            // Driver has already exited; dwell event should not fire
+            return;
+        }
+
+        // Load the driver
+        $subject = $this->subjectType === 'vehicle'
+            ? Vehicle::where('uuid', $this->driverUuid)->withoutGlobalScopes()->first()
+            : Driver::where('uuid', $this->driverUuid)->withoutGlobalScopes()->first();
+
+        if (!$subject) {
+            Log::warning('CheckGeofenceDwell: Subject not found', [
+                'subject_uuid' => $this->driverUuid,
+                'subject_type' => $this->subjectType,
+            ]);
+
+            return;
+        }
+
+        // Load the geofence model
+        $geofence = $this->geofenceType === 'service_area'
+            ? ServiceArea::where('uuid', $this->geofenceUuid)->first()
+            : Zone::where('uuid', $this->geofenceUuid)->first();
+
+        if (!$geofence) {
+            Log::warning('CheckGeofenceDwell: Geofence not found', [
+                'geofence_uuid' => $this->geofenceUuid,
+                'geofence_type' => $this->geofenceType,
+            ]);
+
+            return;
+        }
+
+        // Parse the entry timestamp
+        $enteredAt = \Carbon\Carbon::parse($state->entered_at);
+
+        // Fire the dwell event
+        event(new GeofenceDwelled($subject, $geofence, $this->geofenceType, $enteredAt));
+    }
+}

package/server/src/Listeners/HandleGeofenceDwelled.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace Fleetbase\FleetOps\Listeners;
+
+use Fleetbase\FleetOps\Events\GeofenceDwelled;
+use Fleetbase\FleetOps\Models\GeofenceEventLog;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Support\Str;
+
+/**
+ * HandleGeofenceDwelled.
+ *
+ * Handles the business logic triggered when a driver has dwelled inside
+ * a geofence for the configured threshold duration:
+ *   1. Writes a record to the geofence_events_log table with the dwell duration.
+ */
+class HandleGeofenceDwelled implements ShouldQueue
+{
+    use InteractsWithQueue;
+
+    /**
+     * The number of times the job may be attempted.
+     */
+    public int $tries = 3;
+
+    /**
+     * Handle the event.
+     */
+    public function handle(GeofenceDwelled $event): void
+    {
+        $driver  = $event->driver;
+        $vehicle = $event->vehicle;
+        $order   = $driver?->getCurrentOrder();
+        $subject = $event->subjectType === 'vehicle' ? $vehicle : $driver;
+
+        GeofenceEventLog::create([
+            'uuid'                   => Str::uuid()->toString(),
+            'company_uuid'           => $event->getCompanyUuid(),
+            'driver_uuid'            => $driver?->uuid,
+            'vehicle_uuid'           => $vehicle?->uuid,
+            'order_uuid'             => $order?->uuid,
+            'subject_uuid'           => $subject?->uuid,
+            'subject_type'           => $event->subjectType,
+            'subject_name'           => $event->subjectType === 'vehicle' ? ($vehicle?->display_name ?? $vehicle?->plate_number) : $driver?->name,
+            'geofence_uuid'          => $event->geofence->uuid,
+            'geofence_type'          => $event->geofenceType,
+            'geofence_name'          => $event->geofence->name,
+            'event_type'             => 'dwelled',
+            'latitude'               => null,
+            'longitude'              => null,
+            'dwell_duration_minutes' => $event->dwellDurationMinutes,
+            'occurred_at'            => $event->timestamp,
+        ]);
+    }
+}

package/server/src/Listeners/HandleGeofenceEntered.php

@@ -0,0 +1,187 @@
+<?php
+
+namespace Fleetbase\FleetOps\Listeners;
+
+use Fleetbase\FleetOps\Events\GeofenceEntered;
+use Fleetbase\FleetOps\Models\GeofenceEventLog;
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Notifications\DriverArrivedAtGeofence;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Str;
+
+/**
+ * HandleGeofenceEntered.
+ *
+ * Handles the business logic triggered when a driver enters a geofence:
+ *   1. Writes a record to the geofence_events_log table.
+ *   2. Checks if the entered geofence corresponds to the driver's current
+ *      order destination and auto-transitions the order to "arrived" status.
+ *   3. Sends a customer notification if the order destination matches.
+ */
+class HandleGeofenceEntered implements ShouldQueue
+{
+    use InteractsWithQueue;
+
+    /**
+     * The number of times the job may be attempted.
+     */
+    public int $tries = 3;
+
+    /**
+     * Handle the event.
+     */
+    public function handle(GeofenceEntered $event): void
+    {
+        $driver   = $event->driver;
+        $vehicle  = $event->vehicle;
+        $geofence = $event->geofence;
+
+        // Set company session context for any subsequent queries
+        session(['company' => $event->getCompanyUuid()]);
+
+        // ----------------------------------------------------------------
+        // 1. Write to the geofence event log
+        // ----------------------------------------------------------------
+        $order   = $driver?->getCurrentOrder();
+        $subject = $event->subjectType === 'vehicle' ? $vehicle : $driver;
+
+        GeofenceEventLog::create([
+            'uuid'          => Str::uuid()->toString(),
+            'company_uuid'  => $event->getCompanyUuid(),
+            'driver_uuid'   => $driver?->uuid,
+            'vehicle_uuid'  => $vehicle?->uuid,
+            'order_uuid'    => $order?->uuid,
+            'subject_uuid'  => $subject?->uuid,
+            'subject_type'  => $event->subjectType,
+            'subject_name'  => $event->subjectType === 'vehicle' ? ($vehicle?->display_name ?? $vehicle?->plate_number) : $driver?->name,
+            'geofence_uuid' => $geofence->uuid,
+            'geofence_type' => $event->geofenceType,
+            'geofence_name' => $geofence->name,
+            'event_type'    => 'entered',
+            'latitude'      => $event->location->getLat(),
+            'longitude'     => $event->location->getLng(),
+            'occurred_at'   => $event->timestamp,
+        ]);
+
+        // ----------------------------------------------------------------
+        // 2. Order status automation
+        //
+        //    If the driver has an active order and the geofence is in
+        //    proximity to the current destination waypoint, auto-transition
+        //    the order to "arrived" status and notify the customer.
+        // ----------------------------------------------------------------
+        if ($driver && $order) {
+            $this->handleOrderArrival($driver, $geofence, $order, $event);
+        }
+    }
+
+    /**
+     * Attempt to auto-transition an order to "arrived" status when the
+     * driver enters a geofence near the order's current destination.
+     */
+    private function handleOrderArrival($driver, $geofence, Order $order, GeofenceEntered $event): void
+    {
+        // Do not re-trigger if the order is already arrived or completed
+        if (in_array($order->status, ['arrived', 'completed', 'canceled'])) {
+            return;
+        }
+
+        // Get the current destination waypoint
+        $destination = null;
+        try {
+            $destination = $order->payload?->getPickupOrCurrentWaypoint();
+        } catch (\Throwable $e) {
+            Log::warning('GeofenceEntered: Could not resolve order destination', [
+                'order_uuid'  => $order->uuid,
+                'driver_uuid' => $driver->uuid,
+                'error'       => $e->getMessage(),
+            ]);
+
+            return;
+        }
+
+        if (!$destination) {
+            return;
+        }
+
+        // Resolve the destination place
+        $place = null;
+        try {
+            $place = $destination->place ?? $destination->getPlace();
+        } catch (\Throwable $e) {
+            return;
+        }
+
+        if (!$place || !$place->location) {
+            return;
+        }
+
+        // Check proximity: is the geofence centroid within 500m of the destination place?
+        try {
+            $geofenceLat = $geofence->getLatitudeAttribute();
+            $geofenceLng = $geofence->getLongitudeAttribute();
+        } catch (\Throwable $e) {
+            return;
+        }
+
+        $placeLat = $place->location->getLat();
+        $placeLng = $place->location->getLng();
+
+        $distanceMeters = $this->haversineDistance($geofenceLat, $geofenceLng, $placeLat, $placeLng);
+
+        // Only trigger if the geofence is within 500m of the destination
+        if ($distanceMeters > 500) {
+            return;
+        }
+
+        // Auto-transition order to "arrived"
+        try {
+            $order->setStatus('arrived');
+            $order->createActivity(
+                [
+                    'status'  => 'arrived',
+                    'details' => sprintf('Driver entered destination geofence "%s".', $geofence->name),
+                ],
+                $event->location
+            );
+        } catch (\Throwable $e) {
+            Log::error('GeofenceEntered: Failed to set order status to arrived', [
+                'order_uuid' => $order->uuid,
+                'error'      => $e->getMessage(),
+            ]);
+
+            return;
+        }
+
+        // Notify the customer
+        if ($order->customer) {
+            try {
+                $order->customer->notify(new DriverArrivedAtGeofence($order, $geofence));
+            } catch (\Throwable $e) {
+                // Notification failure must not interrupt the geofence pipeline
+                Log::warning('GeofenceEntered: Failed to notify customer', [
+                    'order_uuid' => $order->uuid,
+                    'error'      => $e->getMessage(),
+                ]);
+            }
+        }
+    }
+
+    /**
+     * Calculate the haversine distance in metres between two lat/lng points.
+     *
+     * @return float Distance in metres
+     */
+    private 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/Listeners/HandleGeofenceExited.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace Fleetbase\FleetOps\Listeners;
+
+use Fleetbase\FleetOps\Events\GeofenceExited;
+use Fleetbase\FleetOps\Models\GeofenceEventLog;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Support\Str;
+
+/**
+ * HandleGeofenceExited.
+ *
+ * Handles the business logic triggered when a driver exits a geofence:
+ *   1. Writes a record to the geofence_events_log table, including the
+ *      dwell duration calculated from the entry timestamp.
+ */
+class HandleGeofenceExited implements ShouldQueue
+{
+    use InteractsWithQueue;
+
+    /**
+     * The number of times the job may be attempted.
+     */
+    public int $tries = 3;
+
+    /**
+     * Handle the event.
+     */
+    public function handle(GeofenceExited $event): void
+    {
+        $driver  = $event->driver;
+        $vehicle = $event->vehicle;
+        $order   = $driver?->getCurrentOrder();
+        $subject = $event->subjectType === 'vehicle' ? $vehicle : $driver;
+
+        GeofenceEventLog::create([
+            'uuid'                   => Str::uuid()->toString(),
+            'company_uuid'           => $event->getCompanyUuid(),
+            'driver_uuid'            => $driver?->uuid,
+            'vehicle_uuid'           => $vehicle?->uuid,
+            'order_uuid'             => $order?->uuid,
+            'subject_uuid'           => $subject?->uuid,
+            'subject_type'           => $event->subjectType,
+            'subject_name'           => $event->subjectType === 'vehicle' ? ($vehicle?->display_name ?? $vehicle?->plate_number) : $driver?->name,
+            'geofence_uuid'          => $event->geofence->uuid,
+            'geofence_type'          => $event->geofenceType,
+            'geofence_name'          => $event->geofence->name,
+            'event_type'             => 'exited',
+            'latitude'               => $event->location->getLat(),
+            'longitude'              => $event->location->getLng(),
+            'dwell_duration_minutes' => $event->dwellDurationMinutes,
+            'occurred_at'            => $event->timestamp,
+        ]);
+    }
+}