@fleetbase/fleetops-engine 0.6.17 → 0.6.18

package/server/src/Models/Payload.php

@@ -308,6 +308,34 @@ class Payload extends Model
         return $this;
     }
 
+    /**
+     * Set waypoints for the current entity by resolving or creating Places and
+     * upserting Waypoint records in order.
+     *
+     * Input supports multiple shapes per item:
+     * - Top-level fields (preferred): 'type', 'place_uuid', 'id' (public_id), 'uuid' (temp search UUID),
+     *   'customer_uuid' (preferred), 'customer_id' (customer public_id), 'customer_type'
+     * - Or wrapped place payload: { type, place: {...} }
+     *
+     * Place resolution order:
+     *   1) attributes.place_uuid (must exist in DB)
+     *   2) attributes.id (public_id) -> resolve to uuid
+     *   3) Place::createFromMixed($attributes)
+     *      - If attributes.uuid is present and differs from created uuid, stores it as meta: search_uuid
+     *
+     * Customer resolution (optional):
+     *   - Uses 'customer_type' (default: 'fleetops:contact') to determine the model via Utils::getMutationType()
+     *   - Tries 'customer_uuid' first (must exist)
+     *   - If not found, tries 'customer_id' (public_id) and resolves to uuid
+     *   - Only sets customer_uuid/customer_type if a valid record is found
+     *
+     * Uniqueness for each waypoint is defined by: (payload_uuid, place_uuid, order).
+     * Updatable fields include: type, customer_uuid, customer_type.
+     *
+     * @param array<int, array<string,mixed>> $waypoints list of waypoint attribute maps
+     *
+     * @return static
+     */
     public function setWaypoints($waypoints = [])
     {
         if (!is_array($waypoints)) {
@@ -315,45 +343,98 @@ class Payload extends Model
         }
 
         foreach ($waypoints as $index => $attributes) {
-            $waypoint = ['payload_uuid' => $this->payload_uuid, 'type' => data_get($attributes, 'type', 'dropoff')];
+            // Keep a copy to safely read top-level fields regardless of { place: {...} } normalization.
+            $raw = $attributes;
 
+            // Read top-level fields BEFORE normalizing the place shape.
+            $type            = data_get($raw, 'type', 'dropoff');
+            $customerUuidIn  = data_get($raw, 'customer_uuid'); // preferred
+            $customerPubIdIn = data_get($raw, 'customer_id');   // public_id fallback
+            $customerType    = data_get($raw, 'customer_type', 'fleetops:contact');
+
+            // Normalize { place: {...} } shape if present.
             if (Utils::isset($attributes, 'place') && is_array(Utils::get($attributes, 'place'))) {
                 $attributes = Utils::get($attributes, 'place');
             }
 
-            if (is_array($attributes) && array_key_exists('place_uuid', $attributes) && Place::where('uuid', $attributes['place_uuid'])->exists()) {
-                $waypoint = [
-                    'place_uuid'   => $attributes['place_uuid'],
-                    'payload_uuid' => $attributes['payload_uuid'] ?? null,
-                    'order'        => $index,
-                ];
+            // -------- Resolve Place (uuid) --------
+            $placeUuid = null;
+
+            // Path 1: explicit place_uuid, ensure it exists
+            if (
+                is_array($attributes)
+                && isset($attributes['place_uuid'])
+                && Place::where('uuid', $attributes['place_uuid'])->exists()
+            ) {
+                $placeUuid = $attributes['place_uuid'];
+
+            // Path 2: public_id under "id" -> resolve to uuid
+            } elseif (
+                is_array($attributes)
+                && isset($attributes['id'])
+                && ($resolvedUuid = Place::where('public_id', $attributes['id'])->value('uuid'))
+            ) {
+                $placeUuid = $resolvedUuid;
+
+            // Path 3: create from mixed payload
             } else {
                 $place = Place::createFromMixed($attributes);
 
-                // if has a temporary uuid from search create meta attr for search_uuid
+                // Store temp search UUID for traceability if present and different
                 if ($place instanceof Place && isset($attributes['uuid']) && $place->uuid !== $attributes['uuid']) {
                     $place->updateMeta('search_uuid', $attributes['uuid']);
                 }
 
-                $waypoint['place_uuid'] = $place->uuid;
+                $placeUuid = $place->uuid;
             }
 
-            // Handle customer assosciation for waypoint
-            $customerId   = data_get($attributes, 'customer_uuid');
-            $customerType = data_get($attributes, 'customer_type', 'fleetops:contact');
-            if ($customerId && $customerType) {
+            // -------- Resolve Customer (uuid) --------
+            $customerUuid          = null;
+            $customerTypeNamespace = null;
+
+            if ($customerType) {
                 $customerTypeNamespace = Utils::getMutationType($customerType);
-                $customerExists        = app($customerTypeNamespace)->where('uuid', $customerId)->exists();
-                if ($customerExists) {
-                    $waypoint['customer_uuid'] = $customerId;
-                    $waypoint['customer_type'] = $customerTypeNamespace;
+                $customerModel         = app($customerTypeNamespace);
+
+                // Try by UUID first (preferred)
+                if ($customerUuidIn && $customerModel->where('uuid', $customerUuidIn)->exists()) {
+                    $customerUuid = $customerUuidIn;
+                }
+                // If not found by UUID, try by public_id
+                if (!$customerUuid && $customerPubIdIn) {
+                    $maybeUuid = $customerModel->where('public_id', $customerPubIdIn)->value('uuid');
+                    if ($maybeUuid) {
+                        $customerUuid = $maybeUuid;
+                    } else {
+                        // If neither lookup succeeds, drop the type namespace to avoid FK/type mismatch
+                        $customerTypeNamespace = null;
+                    }
+                }
+
+                // If no valid uuid after both attempts, clear the type
+                if (!$customerUuid) {
+                    $customerTypeNamespace = null;
                 }
             }
 
-            // set payload
-            $waypoint['payload_uuid'] = $this->uuid;
-            $waypointRecord           = Waypoint::updateOrCreate($waypoint);
+            // -------- Upsert Waypoint --------
+            // Uniqueness: payload + place + order for deterministic row per position.
+            $unique = [
+                'payload_uuid' => $this->payload_uuid,
+                'place_uuid'   => $placeUuid,
+                'order'        => $index,
+            ];
+
+            // Only mutable/updatable fields go here.
+            $values = array_filter([
+                'type'           => $type,
+                'customer_uuid'  => $customerUuid,
+                'customer_type'  => $customerTypeNamespace,
+            ], fn ($v) => !is_null($v));
+
+            $waypointRecord = Waypoint::updateOrCreate($unique, $values);
 
+            // Track it (assumes this is a Collection)
             $this->waypointMarkers->push($waypointRecord);
         }
 

package/server/src/Models/Place.php

@@ -431,12 +431,10 @@ class Place extends Model
 
         $results = \Geocoder\Laravel\Facades\Geocoder::reverse($latitude, $longitude)->get();
 
-        if ($results->isEmpty()) {
-            return null;
+        if (!$results->isEmpty()) {
+            $instance->fillWithGoogleAddress($results->first());
         }
 
-        $instance->fillWithGoogleAddress($results->first());
-
         if ($saveInstance) {
             $instance->save();
         }
@@ -541,6 +539,14 @@ class Place extends Model
                 return $existingPlace;
             }
 
+            // Get public_id if supplied if set
+            $id = data_get($place, 'id') || data_get($place, 'public_id');
+
+            // If $place has a valid uuid and a matching Place object exists, return the uuid
+            if (Utils::isPublicId($id) && $existingPlace = static::where('public_id', $id)->first()) {
+                return $existingPlace;
+            }
+
             // If has $attributes['address']
             if (!empty($place['address'])) {
                 return static::createFromGeocodingLookup($place['address'], $saveInstance);

package/server/src/Models/Sensor.php

@@ -0,0 +1,510 @@
+<?php
+
+namespace Fleetbase\FleetOps\Models;
+
+use Fleetbase\Casts\Json;
+use Fleetbase\Models\Alert;
+use Fleetbase\Models\Model;
+use Fleetbase\Models\User;
+use Fleetbase\Traits\HasApiModelBehavior;
+use Fleetbase\Traits\HasCustomFields;
+use Fleetbase\Traits\HasMetaAttributes;
+use Fleetbase\Traits\HasPublicId;
+use Fleetbase\Traits\HasUuid;
+use Fleetbase\Traits\Searchable;
+use Fleetbase\Traits\TracksApiCredential;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+use Illuminate\Database\Eloquent\Relations\MorphTo;
+use Spatie\Activitylog\LogOptions;
+use Spatie\Activitylog\Traits\LogsActivity;
+use Spatie\Sluggable\HasSlug;
+use Spatie\Sluggable\SlugOptions;
+
+/**
+ * Class Sensor.
+ *
+ * Represents a sensor that can measure and report various metrics like temperature,
+ * door status, fuel level, tire pressure, etc. Sensors can be attached to devices,
+ * assets, or other entities in the fleet management system.
+ */
+class Sensor extends Model
+{
+    use HasUuid;
+    use HasPublicId;
+    use TracksApiCredential;
+    use HasApiModelBehavior;
+    use HasSlug;
+    use LogsActivity;
+    use HasMetaAttributes;
+    use Searchable;
+    use HasCustomFields;
+
+    /**
+     * The database table used by the model.
+     *
+     * @var string
+     */
+    protected $table = 'sensors';
+
+    /**
+     * The type of public Id to generate.
+     *
+     * @var string
+     */
+    protected $publicIdType = 'sensor';
+
+    /**
+     * The attributes that can be queried.
+     *
+     * @var array
+     */
+    protected $searchableColumns = ['name', 'sensor_type', 'unit', 'public_id'];
+
+    /**
+     * The attributes that can be used for filtering.
+     *
+     * @var array
+     */
+    protected $filterParams = ['sensor_type', 'status', 'device_uuid', 'warranty_uuid', 'sensorable_type'];
+
+    /**
+     * The attributes that are mass assignable.
+     *
+     * @var array
+     */
+    protected $fillable = [
+        'company_uuid',
+        'device_uuid',
+        'warranty_uuid',
+        'name',
+        'sensor_type',
+        'unit',
+        'min_threshold',
+        'max_threshold',
+        'threshold_inclusive',
+        'last_reading_at',
+        'last_value',
+        'calibration',
+        'report_frequency_sec',
+        'sensorable_type',
+        'sensorable_uuid',
+        'status',
+        'meta',
+        'slug',
+    ];
+
+    /**
+     * Dynamic attributes that are appended to object.
+     *
+     * @var array
+     */
+    protected $appends = [
+        'device_name',
+        'warranty_name',
+        'attached_to_name',
+        'is_active',
+        'threshold_status',
+        'last_reading_formatted',
+    ];
+
+    /**
+     * The attributes excluded from the model's JSON form.
+     *
+     * @var array
+     */
+    protected $hidden = ['device', 'warranty', 'sensorable'];
+
+    /**
+     * The attributes that should be cast to native types.
+     *
+     * @var array
+     */
+    protected $casts = [
+        'min_threshold'        => 'float',
+        'max_threshold'        => 'float',
+        'threshold_inclusive'  => 'boolean',
+        'last_reading_at'      => 'datetime',
+        'report_frequency_sec' => 'integer',
+        'calibration'          => Json::class,
+        'meta'                 => Json::class,
+    ];
+
+    /**
+     * Properties which activity needs to be logged.
+     *
+     * @var array
+     */
+    protected static $logAttributes = '*';
+
+    /**
+     * Do not log empty changed.
+     *
+     * @var bool
+     */
+    protected static $submitEmptyLogs = false;
+
+    /**
+     * The name of the subject to log.
+     *
+     * @var string
+     */
+    protected static $logName = 'sensor';
+
+    /**
+     * Get the options for generating the slug.
+     */
+    public function getSlugOptions(): SlugOptions
+    {
+        return SlugOptions::create()
+            ->generateSlugsFrom(['name', 'sensor_type'])
+            ->saveSlugsTo('slug');
+    }
+
+    /**
+     * Get the activity log options for the model.
+     */
+    public function getActivitylogOptions(): LogOptions
+    {
+        return LogOptions::defaults()->logAll();
+    }
+
+    public function device(): BelongsTo
+    {
+        return $this->belongsTo(Device::class, 'device_uuid', 'uuid');
+    }
+
+    public function warranty(): BelongsTo
+    {
+        return $this->belongsTo(Warranty::class, 'warranty_uuid', 'uuid');
+    }
+
+    public function createdBy(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'created_by_uuid', 'uuid');
+    }
+
+    public function updatedBy(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'updated_by_uuid', 'uuid');
+    }
+
+    public function sensorable(): MorphTo
+    {
+        return $this->morphTo();
+    }
+
+    public function alerts(): HasMany
+    {
+        return $this->hasMany(Alert::class, 'subject_uuid', 'uuid')
+            ->where('subject_type', static::class);
+    }
+
+    /**
+     * Get the device name.
+     */
+    public function getDeviceNameAttribute(): ?string
+    {
+        return $this->device?->name;
+    }
+
+    /**
+     * Get the warranty name.
+     */
+    public function getWarrantyNameAttribute(): ?string
+    {
+        return $this->warranty?->name;
+    }
+
+    /**
+     * Get the name of what the sensor is attached to.
+     */
+    public function getAttachedToNameAttribute(): ?string
+    {
+        if ($this->sensorable) {
+            return $this->sensorable->name ?? $this->sensorable->display_name ?? null;
+        }
+
+        return null;
+    }
+
+    /**
+     * Check if the sensor is currently active.
+     */
+    public function getIsActiveAttribute(): bool
+    {
+        if ($this->status !== 'active') {
+            return false;
+        }
+
+        // Consider active if we've received a reading within the expected frequency
+        if ($this->last_reading_at && $this->report_frequency_sec) {
+            $expectedNextReading = $this->last_reading_at->addSeconds($this->report_frequency_sec * 2); // Allow 2x frequency
+
+            return now()->lte($expectedNextReading);
+        }
+
+        return $this->status === 'active';
+    }
+
+    /**
+     * Get the threshold status of the last reading.
+     */
+    public function getThresholdStatusAttribute(): string
+    {
+        if (!$this->last_value || (!$this->min_threshold && !$this->max_threshold)) {
+            return 'normal';
+        }
+
+        $value = (float) $this->last_value;
+
+        if ($this->min_threshold && $this->max_threshold) {
+            if ($this->threshold_inclusive) {
+                if ($value < $this->min_threshold || $value > $this->max_threshold) {
+                    return 'out_of_range';
+                }
+            } else {
+                if ($value <= $this->min_threshold || $value >= $this->max_threshold) {
+                    return 'out_of_range';
+                }
+            }
+        } elseif ($this->min_threshold) {
+            if ($this->threshold_inclusive ? $value < $this->min_threshold : $value <= $this->min_threshold) {
+                return 'below_minimum';
+            }
+        } elseif ($this->max_threshold) {
+            if ($this->threshold_inclusive ? $value > $this->max_threshold : $value >= $this->max_threshold) {
+                return 'above_maximum';
+            }
+        }
+
+        return 'normal';
+    }
+
+    /**
+     * Get the last reading with unit formatting.
+     */
+    public function getLastReadingFormattedAttribute(): ?string
+    {
+        if (!$this->last_value) {
+            return null;
+        }
+
+        return $this->last_value . ($this->unit ? ' ' . $this->unit : '');
+    }
+
+    /**
+     * Scope to get sensors by type.
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $query
+     *
+     * @return \Illuminate\Database\Eloquent\Builder
+     */
+    public function scopeByType($query, string $type)
+    {
+        return $query->where('sensor_type', $type);
+    }
+
+    /**
+     * Scope to get active sensors.
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $query
+     *
+     * @return \Illuminate\Database\Eloquent\Builder
+     */
+    public function scopeActive($query)
+    {
+        return $query->where('status', 'active');
+    }
+
+    /**
+     * Scope to get sensors with recent readings.
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $query
+     *
+     * @return \Illuminate\Database\Eloquent\Builder
+     */
+    public function scopeWithRecentReadings($query, int $minutes = 60)
+    {
+        return $query->where('last_reading_at', '>=', now()->subMinutes($minutes));
+    }
+
+    /**
+     * Scope to get sensors that are out of threshold.
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $query
+     *
+     * @return \Illuminate\Database\Eloquent\Builder
+     */
+    public function scopeOutOfThreshold($query)
+    {
+        return $query->where(function ($q) {
+            $q->whereRaw('CAST(last_value AS DECIMAL) < min_threshold')
+              ->orWhereRaw('CAST(last_value AS DECIMAL) > max_threshold');
+        })->whereNotNull('last_value');
+    }
+
+    /**
+     * Record a new sensor reading.
+     */
+    public function recordReading($value, ?\DateTime $timestamp = null): bool
+    {
+        $timestamp = $timestamp ?? now();
+
+        $updated = $this->update([
+            'last_value'      => $value,
+            'last_reading_at' => $timestamp,
+        ]);
+
+        if ($updated) {
+            // Check if the reading is out of threshold and create alert if needed
+            $this->checkThresholdAndCreateAlert($value);
+
+            activity('sensor_reading')
+                ->performedOn($this)
+                ->withProperties([
+                    'value'            => $value,
+                    'unit'             => $this->unit,
+                    'threshold_status' => $this->threshold_status,
+                    'timestamp'        => $timestamp,
+                ])
+                ->log('Sensor reading recorded');
+        }
+
+        return $updated;
+    }
+
+    /**
+     * Check threshold and create alert if needed.
+     */
+    protected function checkThresholdAndCreateAlert($value): void
+    {
+        $thresholdStatus = $this->threshold_status;
+
+        if ($thresholdStatus !== 'normal') {
+            // Check if there's already an open alert for this sensor
+            $existingAlert = $this->alerts()
+                ->where('status', 'open')
+                ->where('type', 'sensor_threshold')
+                ->first();
+
+            if (!$existingAlert) {
+                Alert::create([
+                    'company_uuid' => $this->company_uuid,
+                    'type'         => 'sensor_threshold',
+                    'severity'     => $this->getSeverityForThresholdStatus($thresholdStatus),
+                    'status'       => 'open',
+                    'subject_type' => static::class,
+                    'subject_uuid' => $this->uuid,
+                    'message'      => $this->generateThresholdAlertMessage($value, $thresholdStatus),
+                    'context'      => [
+                        'sensor_name'      => $this->name,
+                        'sensor_type'      => $this->sensor_type,
+                        'value'            => $value,
+                        'unit'             => $this->unit,
+                        'threshold_status' => $thresholdStatus,
+                        'min_threshold'    => $this->min_threshold,
+                        'max_threshold'    => $this->max_threshold,
+                    ],
+                    'triggered_at' => now(),
+                ]);
+            }
+        } else {
+            // Resolve any open threshold alerts for this sensor
+            $this->alerts()
+                ->where('status', 'open')
+                ->where('type', 'sensor_threshold')
+                ->update([
+                    'status'      => 'resolved',
+                    'resolved_at' => now(),
+                ]);
+        }
+    }
+
+    /**
+     * Get severity level for threshold status.
+     */
+    protected function getSeverityForThresholdStatus(string $thresholdStatus): string
+    {
+        switch ($thresholdStatus) {
+            case 'out_of_range':
+                return 'high';
+            case 'above_maximum':
+            case 'below_minimum':
+                return 'medium';
+            default:
+                return 'low';
+        }
+    }
+
+    /**
+     * Generate alert message for threshold violation.
+     */
+    protected function generateThresholdAlertMessage($value, string $thresholdStatus): string
+    {
+        $formattedValue = $value . ($this->unit ? ' ' . $this->unit : '');
+
+        switch ($thresholdStatus) {
+            case 'out_of_range':
+                return "Sensor '{$this->name}' reading ({$formattedValue}) is out of acceptable range ({$this->min_threshold}-{$this->max_threshold} {$this->unit})";
+            case 'above_maximum':
+                return "Sensor '{$this->name}' reading ({$formattedValue}) exceeds maximum threshold ({$this->max_threshold} {$this->unit})";
+            case 'below_minimum':
+                return "Sensor '{$this->name}' reading ({$formattedValue}) is below minimum threshold ({$this->min_threshold} {$this->unit})";
+            default:
+                return "Sensor '{$this->name}' threshold violation detected";
+        }
+    }
+
+    /**
+     * Calibrate the sensor with offset and scale factors.
+     */
+    public function calibrate(float $offset = 0, float $scale = 1): bool
+    {
+        $calibration = [
+            'offset'        => $offset,
+            'scale'         => $scale,
+            'calibrated_at' => now(),
+            'calibrated_by' => auth()->id(),
+        ];
+
+        return $this->update(['calibration' => $calibration]);
+    }
+
+    /**
+     * Apply calibration to a raw sensor value.
+     */
+    public function applyCalibratedValue(float $rawValue): float
+    {
+        $calibration = $this->calibration ?? [];
+        $offset      = $calibration['offset'] ?? 0;
+        $scale       = $calibration['scale'] ?? 1;
+
+        return ($rawValue * $scale) + $offset;
+    }
+
+    /**
+     * Get sensor reading history.
+     */
+    public function getReadingHistory(int $limit = 100, int $hours = 24): array
+    {
+        // This would typically query a separate sensor_readings table
+        // For now, return a placeholder structure
+        return [
+            'sensor_uuid' => $this->uuid,
+            'sensor_name' => $this->name,
+            'period'      => [
+                'start' => now()->subHours($hours),
+                'end'   => now(),
+            ],
+            'readings' => [], // Would contain actual reading data
+            'summary'  => [
+                'count' => 0,
+                'min'   => null,
+                'max'   => null,
+                'avg'   => null,
+                'last'  => $this->last_value,
+            ],
+        ];
+    }
+}