@fleetbase/fleetops-engine 0.6.43 → 0.6.45

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,
+        ]);
+    }
+}

package/server/src/Models/Entity.php

@@ -168,6 +168,13 @@ class Entity extends Model
         ])->render();
     }
 
+    public function setTypeAttribute(?string $type = null): void
+    {
+        $type = is_string($type) ? trim($type) : $type;
+
+        $this->attributes['type'] = filled($type) ? Str::snake($type) : null;
+    }
+
     /**
      * @var BelongsTo
      */

package/server/src/Models/GeofenceEventLog.php

@@ -0,0 +1,155 @@
+<?php
+
+namespace Fleetbase\FleetOps\Models;
+
+use Fleetbase\Traits\HasUuid;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+/**
+ * GeofenceEventLog.
+ *
+ * Persistent audit log of all geofence events (entered, exited, dwelled).
+ * Powers the reporting dashboard, dwell time analytics, and geofence
+ * activity history views.
+ *
+ * @property string         $uuid
+ * @property string         $company_uuid
+ * @property string         $driver_uuid
+ * @property string|null    $vehicle_uuid
+ * @property string|null    $order_uuid
+ * @property string         $geofence_uuid
+ * @property string         $geofence_type
+ * @property string|null    $geofence_name
+ * @property string         $event_type
+ * @property float|null     $latitude
+ * @property float|null     $longitude
+ * @property float|null     $speed_kmh
+ * @property int|null       $dwell_duration_minutes
+ * @property \Carbon\Carbon $occurred_at
+ */
+class GeofenceEventLog extends Model
+{
+    use HasUuid;
+
+    /**
+     * The database table used by the model.
+     *
+     * @var string
+     */
+    protected $table = 'geofence_events_log';
+
+    /**
+     * The primary key for the model.
+     *
+     * @var string
+     */
+    protected $primaryKey = 'uuid';
+
+    /**
+     * The "type" of the primary key ID.
+     *
+     * @var string
+     */
+    protected $keyType = 'string';
+
+    /**
+     * Indicates if the IDs are auto-incrementing.
+     *
+     * @var bool
+     */
+    public $incrementing = false;
+
+    /**
+     * The attributes that are mass assignable.
+     *
+     * @var array
+     */
+    protected $fillable = [
+        'uuid',
+        'company_uuid',
+        'driver_uuid',
+        'vehicle_uuid',
+        'order_uuid',
+        'subject_uuid',
+        'subject_type',
+        'subject_name',
+        'geofence_uuid',
+        'geofence_type',
+        'geofence_name',
+        'event_type',
+        'latitude',
+        'longitude',
+        'speed_kmh',
+        'dwell_duration_minutes',
+        'occurred_at',
+    ];
+
+    /**
+     * The attributes that should be cast to native types.
+     *
+     * @var array
+     */
+    protected $casts = [
+        'occurred_at'            => 'datetime',
+        'latitude'               => 'float',
+        'longitude'              => 'float',
+        'speed_kmh'              => 'float',
+        'dwell_duration_minutes' => 'integer',
+    ];
+
+    /**
+     * The attributes excluded from the model's JSON form.
+     *
+     * @var array
+     */
+    protected $hidden = [];
+
+    /**
+     * Get the driver associated with this event.
+     */
+    public function driver(): BelongsTo
+    {
+        return $this->belongsTo(Driver::class, 'driver_uuid', 'uuid');
+    }
+
+    /**
+     * Get the order associated with this event (if any).
+     */
+    public function order(): BelongsTo
+    {
+        return $this->belongsTo(Order::class, 'order_uuid', 'uuid');
+    }
+
+    /**
+     * Get the vehicle associated with this event (if any).
+     */
+    public function vehicle(): BelongsTo
+    {
+        return $this->belongsTo(Vehicle::class, 'vehicle_uuid', 'uuid');
+    }
+
+    /**
+     * Scope to filter by company.
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $query
+     *
+     * @return \Illuminate\Database\Eloquent\Builder
+     */
+    public function scopeForCompany($query, string $companyUuid)
+    {
+        return $query->where('company_uuid', $companyUuid);
+    }
+
+    /**
+     * Scope to filter by event type.
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $query
+     *
+     * @return \Illuminate\Database\Eloquent\Builder
+     */
+    public function scopeOfType($query, string $type)
+    {
+        return $query->where('event_type', $type);
+    }
+}

package/server/src/Models/Order.php

@@ -1055,9 +1055,7 @@ class Order extends Model
             'meta'               => $meta,
         ]);
 
-        $this->purchase_rate_uuid = $purchasedRate->uuid;
-
-        return $this->save();
+        return $this->attachPurchaseRate($purchasedRate);
     }
 
     /**
@@ -1096,14 +1094,48 @@ class Order extends Model
                 'meta'               => $meta,
             ]);
 
-            return $this->updateQuietly([
-                'purchase_rate_uuid' => $purchasedRate->uuid,
-            ]);
+            return $this->attachPurchaseRate($purchasedRate);
         }
 
         return false;
     }
 
+    /**
+     * Attach a purchase rate to the order and void any superseded transaction.
+     */
+    public function attachPurchaseRate(PurchaseRate $purchaseRate): bool
+    {
+        $oldTransaction = $this->transaction_uuid
+            ? Transaction::where('uuid', $this->transaction_uuid)->first()
+            : null;
+
+        $attached = (bool) $this->updateQuietly([
+            'purchase_rate_uuid' => $purchaseRate->uuid,
+            'transaction_uuid'   => $purchaseRate->transaction_uuid,
+        ]);
+
+        if ($attached) {
+            $this->setRelation('purchaseRate', $purchaseRate);
+
+            if ($purchaseRate->transaction_uuid) {
+                $this->setRelation('transaction', Transaction::where('uuid', $purchaseRate->transaction_uuid)->first());
+            }
+
+            if (
+                $oldTransaction instanceof Transaction
+                && $oldTransaction->uuid !== $purchaseRate->transaction_uuid
+                && !$oldTransaction->trashed()
+            ) {
+                $oldTransaction->update([
+                    'status'    => Transaction::STATUS_VOIDED,
+                    'voided_at' => now(),
+                ]);
+            }
+        }
+
+        return $attached;
+    }
+
     /**
      * Creates a transaction for the order without a service quote.
      * This method is used when an order is made without selecting a specific service quote.
@@ -1122,7 +1154,7 @@ class Order extends Model
                 'gateway_transaction_id' => Transaction::generateNumber(),
                 'gateway'                => 'internal',
                 'amount'                 => 0,
-                'currency'               => data_get($this->company, 'country') ? Utils::getCurrenyFromCountryCode(data_get($this->company, 'country')) : 'SGD',
+                'currency'               => Utils::getCompanyTransactionCurrency($this->company ?? $this->company_uuid),
                 'description'            => 'Dispatch order',
                 'type'                   => 'dispatch',
                 'status'                 => 'success',

package/server/src/Models/ServiceArea.php

@@ -60,7 +60,22 @@ class ServiceArea extends Model
      *
      * @var array
      */
-    protected $fillable = ['_key', 'company_uuid', 'name', 'type', 'parent_uuid', 'border', 'color', 'stroke_color', 'status', 'country'];
+    protected $fillable = [
+        '_key',
+        'company_uuid',
+        'name',
+        'type',
+        'parent_uuid',
+        'border',
+        'color',
+        'stroke_color',
+        'status',
+        'country',
+        'trigger_on_entry',
+        'trigger_on_exit',
+        'dwell_threshold_minutes',
+        'speed_limit_kmh',
+    ];
 
     /**
      * The attributes that are spatial columns.
@@ -96,7 +111,11 @@ class ServiceArea extends Model
      * @var array
      */
     protected $casts = [
-        'border' => MultiPolygonCast::class,
+        'border'                  => MultiPolygonCast::class,
+        'trigger_on_entry'        => 'boolean',
+        'trigger_on_exit'         => 'boolean',
+        'dwell_threshold_minutes' => 'integer',
+        'speed_limit_kmh'         => 'integer',
     ];
 
     /**

package/server/src/Models/ServiceQuote.php

@@ -3,6 +3,8 @@
 namespace Fleetbase\FleetOps\Models;
 
 use Fleetbase\Casts\Json;
+use Fleetbase\FleetOps\Http\Requests\CreateOrderRequest;
+use Fleetbase\FleetOps\Http\Requests\UpdateOrderRequest;
 use Fleetbase\FleetOps\Integrations\Lalamove\Lalamove;
 use Fleetbase\FleetOps\Support\Payment;
 use Fleetbase\FleetOps\Support\Utils;
@@ -136,7 +138,7 @@ class ServiceQuote extends Model
         return Lalamove::serviceQuoteFromQuotation($quotation);
     }
 
-    public static function resolveFromRequest(Request $request): ?ServiceQuote
+    public static function resolveFromRequest(Request|CreateOrderRequest|UpdateOrderRequest $request): ?ServiceQuote
     {
         $serviceQuote = $request->or(['order.service_quote_uuid', 'service_quote', 'service_quote_id', 'order.service_quote']);