@fleetbase/fleetops-engine 0.6.60 → 0.6.62

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

@@ -0,0 +1,250 @@
+<?php
+
+namespace Fleetbase\FleetOps\Http\Controllers\Api\v1;
+
+use Fleetbase\FleetOps\Http\Resources\v1\Manifest as ManifestResource;
+use Fleetbase\FleetOps\Http\Resources\v1\ManifestStop as ManifestStopResource;
+use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Models\Manifest;
+use Fleetbase\FleetOps\Models\ManifestStop;
+use Fleetbase\FleetOps\Support\Utils;
+use Fleetbase\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+
+/**
+ * Driver-facing manifests.
+ *
+ * A manifest is a driver's route: an order-agnostic sequence of stops, which
+ * may span several orders or none the driver has seen as an order. Everything a
+ * driver app needs to *run* a route lived only behind the console's internal
+ * namespace, so a driver could be assigned a route they had no way to read.
+ *
+ * These endpoints are deliberately narrow. A driver may read their own
+ * manifests, update the stops on them, and re-sequence the ones they have not
+ * done yet. They may not create, cancel or delete a manifest — that is dispatch
+ * work, and it stays on the internal namespace.
+ */
+class ManifestController extends Controller
+{
+    /**
+     * GET /v1/drivers/{id}/manifests.
+     *
+     * Defaults to what a driver actually needs on shift — today and anything
+     * still unfinished — rather than their whole history, which on a busy fleet
+     * is thousands of rows nobody asked for.
+     */
+    public function forDriver(Request $request, string $id)
+    {
+        $driver = static::findDriverRecord($id);
+        if (!$driver) {
+            return response()->apiError('Driver resource not found.', 404);
+        }
+
+        $query = static::manifestsFor($driver);
+
+        if ($request->filled('status')) {
+            $query->whereIn('status', Utils::arrayFrom($request->input('status')));
+        }
+
+        if ($request->filled('on')) {
+            $query->whereDate('scheduled_date', $request->input('on'));
+        }
+
+        return ManifestResource::collection($query->limit((int) $request->input('limit', 30))->get());
+    }
+
+    /**
+     * GET /v1/manifests/{id} — the route, with its stops in sequence.
+     */
+    public function show(string $id)
+    {
+        $manifest = static::findManifest($id);
+        if (!$manifest) {
+            return response()->apiError('Manifest resource not found.', 404);
+        }
+
+        $manifest->load(['driver', 'vehicle', 'stops' => fn ($q) => $q->orderBy('sequence')->with(['place', 'order.trackingNumber'])]);
+
+        return new ManifestResource($manifest);
+    }
+
+    /**
+     * PATCH /v1/manifest-stops/{id}.
+     *
+     * Status changes go through the model's own transitions rather than being
+     * written as a column, because arriving and completing carry side effects —
+     * timestamps, and the manifest completing itself once its last stop does.
+     */
+    public function updateStop(Request $request, string $id)
+    {
+        $stop = static::findStop($id);
+        if (!$stop) {
+            return response()->apiError('Manifest stop resource not found.', 404);
+        }
+
+        $status = $request->input('status');
+        if ($status) {
+            // Checked before it is applied: an unknown status must change
+            // nothing, not fall through a match and then be refused.
+            if (!in_array($status, ['arrived', 'completed', 'skipped'], true)) {
+                return response()->apiError('Status must be one of: arrived, completed, skipped.', 422);
+            }
+
+            match ($status) {
+                'arrived'   => $stop->markArrived(),
+                'completed' => $stop->markCompleted(),
+                default     => $stop->markSkipped(),
+            };
+        }
+
+        if ($request->filled('meta')) {
+            $stop->update(['meta' => $request->input('meta')]);
+        }
+
+        $stop->load(['place', 'order.trackingNumber']);
+
+        return new ManifestStopResource($stop);
+    }
+
+    /**
+     * POST /v1/manifests/{id}/optimize — re-sequence the stops still to do.
+     *
+     * This is the *driver's* optimise, not the orchestrator's. The orchestrator
+     * allocates orders across a fleet and produces manifests; this reorders the
+     * stops on one manifest that is already assigned, which is a different job
+     * with a different owner.
+     *
+     * **It is a nearest-neighbour heuristic, not a solved routing problem.** It
+     * walks from the driver's current position to the closest remaining stop,
+     * then to the closest from there, by straight-line distance. That is
+     * typically a large improvement over an arbitrary order and is not
+     * guaranteed optimal; calling it anything stronger would be a claim the
+     * implementation does not support. Completed and skipped stops keep their
+     * place — a route already driven is not re-planned.
+     */
+    public function optimize(Request $request, string $id)
+    {
+        $manifest = static::findManifest($id);
+        if (!$manifest) {
+            return response()->apiError('Manifest resource not found.', 404);
+        }
+
+        $manifest->load(['stops' => fn ($q) => $q->orderBy('sequence')->with('place')]);
+
+        $done    = $manifest->stops->filter(fn ($s) => in_array($s->status, ['completed', 'skipped'], true))->values();
+        $pending = $manifest->stops->reject(fn ($s) => in_array($s->status, ['completed', 'skipped'], true))->values();
+
+        if ($pending->count() < 3) {
+            // Two stops have only one order, and one has none. Re-sequencing
+            // either is work with no possible result.
+            return $this->show($id);
+        }
+
+        $from = $request->filled(['latitude', 'longitude'])
+            ? ['lat' => (float) $request->input('latitude'), 'lon' => (float) $request->input('longitude')]
+            : static::coordinatesOf($pending->first());
+
+        $remaining = $pending->all();
+        $ordered   = [];
+
+        while (count($remaining)) {
+            $closestIndex = 0;
+            $closestCost  = null;
+
+            foreach ($remaining as $index => $stop) {
+                $to = static::coordinatesOf($stop);
+                if (!$from || !$to) {
+                    continue;
+                }
+
+                $cost = static::distanceBetween($from, $to);
+
+                if ($closestCost === null || $cost < $closestCost) {
+                    $closestCost  = $cost;
+                    $closestIndex = $index;
+                }
+            }
+
+            $next      = $remaining[$closestIndex];
+            $ordered[] = $next;
+            $from      = static::coordinatesOf($next) ?? $from;
+            unset($remaining[$closestIndex]);
+            $remaining = array_values($remaining);
+        }
+
+        // Done stops keep the front of the sequence; the rest follow in the new
+        // order. Sequence stays dense so nothing downstream has to cope with
+        // gaps.
+        $sequence = 1;
+        foreach ($done as $stop) {
+            $stop->update(['sequence' => $sequence++]);
+        }
+        foreach ($ordered as $stop) {
+            $stop->update(['sequence' => $sequence++]);
+        }
+
+        return $this->show($id);
+    }
+
+    /** The driver's manifests, newest first. Separated so it can be stubbed. */
+    protected static function manifestsFor(Driver $driver)
+    {
+        return Manifest::where('driver_uuid', $driver->uuid)
+            ->with(['driver', 'vehicle'])
+            ->orderBy('scheduled_date', 'desc');
+    }
+
+    protected static function findDriverRecord(string $id): ?Driver
+    {
+        return Driver::where('public_id', $id)->orWhere('uuid', $id)->first();
+    }
+
+    protected static function findManifest(string $id): ?Manifest
+    {
+        return Manifest::where('public_id', $id)->orWhere('uuid', $id)->first();
+    }
+
+    protected static function findStop(string $id): ?ManifestStop
+    {
+        return ManifestStop::where('public_id', $id)->orWhere('uuid', $id)->first();
+    }
+
+    /**
+     * Straight-line distance between two coordinates, in metres.
+     *
+     * Deliberately not a routing call. A nearest-neighbour walk compares every
+     * remaining stop at every step, so a twenty-stop route asks roughly four
+     * hundred distance questions — as road lookups that is four hundred network
+     * round trips for one tap, which is not a thing to do on a handset waiting
+     * on a driver.
+     *
+     * Straight-line ordering and road ordering rarely disagree about which of
+     * several stops is nearest, and where they do the result is still a valid
+     * route, just not the shortest one. Since the method is a heuristic either
+     * way, the cheap version is the honest choice.
+     */
+    protected static function distanceBetween(array $from, array $to): float
+    {
+        $earthRadius = 6371000.0;
+
+        $lat1 = deg2rad($from['lat']);
+        $lat2 = deg2rad($to['lat']);
+        $dLat = $lat2 - $lat1;
+        $dLon = deg2rad($to['lon'] - $from['lon']);
+
+        $a = sin($dLat / 2) ** 2 + cos($lat1) * cos($lat2) * sin($dLon / 2) ** 2;
+
+        return $earthRadius * 2 * atan2(sqrt($a), sqrt(1 - $a));
+    }
+
+    /** Latitude and longitude of a stop's place, when it has one. */
+    protected static function coordinatesOf(?ManifestStop $stop): ?array
+    {
+        $location = data_get($stop, 'place.location');
+        if (!$location) {
+            return null;
+        }
+
+        return ['lat' => (float) $location->getLat(), 'lon' => (float) $location->getLng()];
+    }
+}

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

@@ -1873,7 +1873,7 @@ class OrderController extends Controller
         return new Payload();
     }
 
-    protected function findDriverByPublicId(string $publicId): ?Driver
+    protected function findDriverByPublicId(?string $publicId): ?Driver
     {
         return Driver::where(['public_id' => $publicId, 'company_uuid' => session('company')])->first();
     }

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

@@ -218,7 +218,7 @@ class ServiceAreaController extends Controller
         return ServiceArea::createMultiPolygonFromPoint($point, $radius);
     }
 
-    protected function serviceAreaUuid(string $publicId, array $where): ?string
+    protected function serviceAreaUuid(?string $publicId, array $where): ?string
     {
         return Utils::getUuid('service_areas', $where);
     }

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

@@ -187,7 +187,7 @@ class TrackingStatusController extends Controller
         return Utils::getUuid($table, $where);
     }
 
-    protected function getOrderTrackingNumberUuid(string $orderId): ?string
+    protected function getOrderTrackingNumberUuid(?string $orderId): ?string
     {
         return Order::where('public_id', $orderId)->value('tracking_number_uuid');
     }

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

@@ -5,6 +5,9 @@ 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\Exceptions\PublicRelationNotFoundException;
+use Fleetbase\FleetOps\Http\Controllers\Api\v1\Concerns\ResolvesFleetOpsApiResources;
+use Fleetbase\FleetOps\Http\Controllers\Api\v1\Concerns\ResolvesPublicExpansions;
 use Fleetbase\FleetOps\Http\Requests\CreateVehicleRequest;
 use Fleetbase\FleetOps\Http\Requests\UpdateVehicleRequest;
 use Fleetbase\FleetOps\Http\Resources\v1\DeletedResource;
@@ -12,16 +15,45 @@ 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\Models\Vendor;
+use Fleetbase\FleetOps\Models\Warranty;
 use Fleetbase\FleetOps\Support\GeofenceIntersectionService;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Http\Controllers\Controller;
 use Fleetbase\LaravelMysqlSpatial\Types\Point;
+use Fleetbase\Models\Category;
+use Fleetbase\Models\File;
 use Illuminate\Http\Request;
 use Illuminate\Support\Carbon;
 use Illuminate\Support\Facades\DB;
 
 class VehicleController extends Controller
 {
+    use ResolvesFleetOpsApiResources;
+    use ResolvesPublicExpansions;
+
+    /**
+     * Relationships eager loaded so the public resource can report each
+     * assignment as a public id without a query per vehicle.
+     *
+     * Loading them does not expand them: the nested object is returned only for
+     * a relation the caller named in `with`, which is the shape the endpoint has
+     * always had.
+     */
+    protected const PUBLIC_RELATIONS = ['vendor', 'category', 'warranty', 'driver', 'photo'];
+
+    /**
+     * Public expansion name => Eloquent relation name.
+     */
+    public const EXPANDABLE = [
+        'driver'   => 'driver',
+        'vendor'   => 'vendor',
+        'category' => 'category',
+        'warranty' => 'warranty',
+        'photo'    => 'photo',
+        'devices'  => 'devices',
+    ];
+
     /**
      * Creates a new Fleetbase Vehicle resource.
      *
@@ -31,8 +63,14 @@ class VehicleController extends Controller
      */
     public function create(CreateVehicleRequest $request)
     {
+        $this->applyPublicExpansions($request, static::EXPANDABLE);
+
         // get request input
-        $input = $this->vehicleInputFromRequest($request);
+        try {
+            $input = $this->vehicleInputFromRequest($request);
+        } catch (PublicRelationNotFoundException $exception) {
+            return $this->jsonResponse(['error' => $exception->getMessage()], 404);
+        }
 
         // make sure company is set
         $input['company_uuid'] = session('company');
@@ -40,14 +78,6 @@ class VehicleController extends Controller
         // set default online
         $input = $this->withDefaultOnline($input);
 
-        // vendor assignment
-        if ($request->has('vendor')) {
-            $input['vendor_uuid'] = $this->getVendorUuid('vendors', [
-                'public_id'    => $request->input('vendor'),
-                'company_uuid' => session('company'),
-            ]);
-        }
-
         // latitude / longitude
         $input = $this->withCoordinateLocation($input, $request);
 
@@ -85,6 +115,8 @@ class VehicleController extends Controller
      */
     public function update($id, UpdateVehicleRequest $request)
     {
+        $this->applyPublicExpansions($request, static::EXPANDABLE);
+
         // find for the vehicle
         try {
             $vehicle = $this->findVehicle($id);
@@ -98,19 +130,12 @@ class VehicleController extends Controller
         }
 
         // get request input
-        $input = $this->vehicleInputFromRequest($request);
-
-        // vendor assignment
-        if ($request->has('vendor')) {
-            $input['vendor_uuid'] = $this->getVendorUuid('vendors', [
-                'public_id'    => $request->input('vendor'),
-                'company_uuid' => session('company'),
-            ]);
+        try {
+            $input = $this->vehicleInputFromRequest($request);
+        } catch (PublicRelationNotFoundException $exception) {
+            return $this->jsonResponse(['error' => $exception->getMessage()], 404);
         }
 
-        // set default online
-        $input = $this->withDefaultOnline($input);
-
         // latitude / longitude
         $input = $this->withCoordinateLocation($input, $request);
 
@@ -157,6 +182,8 @@ class VehicleController extends Controller
      */
     public function query(Request $request)
     {
+        $this->applyPublicExpansions($request, static::EXPANDABLE);
+
         $results = $this->queryVehicles($request);
 
         return $this->vehicleResourceCollection($results);
@@ -169,8 +196,17 @@ class VehicleController extends Controller
      *
      * @return \Fleetbase\Http\Resources\VehicleCollection
      */
-    public function find($id)
+    public function find($id, ?Request $request = null)
     {
+        // Falls back to the container's request rather than trusting injection:
+        // the parameter carries a default, and Laravel's controller dispatcher
+        // skips resolving a type-hinted dependency that has one. It arrives null,
+        // the expansions are never mapped, and an unsupported name reaches
+        // Eloquent — a 500 for a typo, on the one endpoint most likely to be
+        // handed one.
+        $request = $request instanceof Request ? $request : request();
+        $this->applyPublicExpansions($request, static::EXPANDABLE);
+
         // find for the vehicle
         try {
             $vehicle = $this->findVehicle($id);
@@ -347,17 +383,75 @@ class VehicleController extends Controller
         }
     }
 
+    /**
+     * The explicit public input allowlist for a vehicle.
+     *
+     * Mirrors every safe business field the model and the Fleet-Ops vehicle form
+     * expose. Deliberately absent: `company_uuid` and the raw `*_uuid` relation
+     * columns (resolved from public ids below), `public_id` / `uuid` / `_key` /
+     * `slug` (generated), `avatar_url` when given as a uuid, `vin_data` (written
+     * by the VIN decoder) and `telematics` (written by telematics ingestion).
+     *
+     * @throws PublicRelationNotFoundException
+     */
     protected function vehicleInputFromRequest(Request $request): array
     {
-        return $request->only([
-            'status', 'make', 'model', 'year', 'trim', 'type', 'plate_number', 'vin',
-            'meta', 'online', 'location', 'altitude', 'heading', 'speed',
-            'payload_capacity', 'payload_capacity_volume',
-            'payload_capacity_pallets', 'payload_capacity_parcels',
+        $input = $request->only([
+            // Identity and description
+            'internal_id', 'name', 'description', 'make', 'model', 'model_type', 'year',
+            'trim', 'color', 'type', 'class', 'plate_number', 'vin', 'serial_number',
+            'call_sign', 'fuel_card_number',
+            // Measurement and operation.
+            //
+            // Odometer is fillable on the model and unrestricted by the request
+            // rules, but was absent here — so a caller sending one received a
+            // 200 and a response body that looked correct while the reading was
+            // discarded. Recording mileage is the single most common write a
+            // driver app makes against a vehicle.
+            'odometer', 'odometer_unit', 'odometer_at_purchase', 'measurement_system',
+            'fuel_type', 'fuel_volume_unit', 'online', 'status',
+            'location', 'altitude', 'heading', 'speed',
+            // Body, capacity and dimensions
+            'transmission', 'body_type', 'body_sub_type', 'usage_type', 'ownership_type',
+            'cargo_volume', 'passenger_volume', 'interior_volume', 'weight', 'width',
+            'length', 'height', 'towing_capacity', 'payload_capacity', 'seating_capacity',
+            'ground_clearance', 'bed_length', 'fuel_capacity',
+            // Lifecycle and financing
+            'financing_status', 'loan_number_of_payments', 'loan_first_payment', 'loan_amount',
+            'estimated_service_life_distance_unit', 'estimated_service_life_distance',
+            'estimated_service_life_months', 'insurance_value', 'depreciation_rate',
+            'current_value', 'acquisition_cost', 'currency', 'purchased_at', 'lease_expires_at',
+            // Regulatory and engine specifications
+            'emission_standard', 'dpf_equipped', 'scr_equipped', 'gvwr', 'gcwr',
+            'engine_number', 'engine_model', 'engine_make', 'engine_family',
+            'engine_configuration', 'engine_displacement', 'engine_size', 'horsepower',
+            'horsepower_rpm', 'torque', 'torque_rpm', 'number_of_cylinders',
+            'cylinder_arrangement',
+            // Structured and descriptive fields
+            'specs', 'details', 'notes', 'meta',
+            // Orchestrator
+            'payload_capacity_volume', 'payload_capacity_pallets', 'payload_capacity_parcels',
             'skills', 'max_tasks', 'time_window_start', 'time_window_end', 'return_to_depot',
         ]);
+
+        $this->applyPublicIdRelations($input, [
+            'vendor'   => ['vendor_uuid', Vendor::class],
+            'category' => ['category_uuid', Category::class],
+            'warranty' => ['warranty_uuid', Warranty::class],
+            'photo'    => ['photo_uuid', File::class],
+        ], $request);
+
+        return $input;
     }
 
+    /**
+     * A vehicle that does not say otherwise starts offline.
+     *
+     * Applied on create only. Applying it on update too meant any partial write —
+     * a plate correction, an odometer reading — silently knocked the vehicle
+     * offline, because the absent key was read as "set it to false" rather than
+     * "leave it alone".
+     */
     protected function withDefaultOnline(array $input): array
     {
         if (!isset($input['online'])) {
@@ -388,11 +482,6 @@ class VehicleController extends Controller
         ];
     }
 
-    protected function getVendorUuid(string $table, array $where): ?string
-    {
-        return Utils::getUuid($table, $where);
-    }
-
     protected function createVehicle(array $input): Vehicle
     {
         return Vehicle::create($input);
@@ -403,19 +492,35 @@ class VehicleController extends Controller
         return Vehicle::findRecordOrFail($id);
     }
 
-    protected function findDriver(string $id): Driver
+    protected function findDriver(?string $id): Driver
     {
         return Driver::findRecordOrFail($id);
     }
 
     protected function queryVehicles(Request $request)
     {
-        return Vehicle::queryWithRequest($request);
+        return Vehicle::queryWithRequest($request, function (&$query) {
+            $query->with(static::PUBLIC_RELATIONS);
+        });
     }
 
     protected function vehicleResource(Vehicle $vehicle)
     {
-        return new VehicleResource($vehicle);
+        return new VehicleResource($this->withPublicRelations($vehicle));
+    }
+
+    /**
+     * Load the relations the public resource reports as identifiers.
+     *
+     * One query per relation instead of one per relation per read, and it makes
+     * an assignment made moments earlier in the same request readable back
+     * immediately.
+     */
+    protected function withPublicRelations(Vehicle $vehicle): Vehicle
+    {
+        $vehicle->loadMissing(static::PUBLIC_RELATIONS);
+
+        return $vehicle;
     }
 
     protected function vehicleResourceCollection($results)

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

@@ -212,7 +212,7 @@ class ZoneController extends Controller
         return (int) $request->input('radius', 500);
     }
 
-    protected function serviceAreaUuid(string $publicId, array $where): ?string
+    protected function serviceAreaUuid(?string $publicId, array $where): ?string
     {
         return Utils::getUuid('service_areas', $where);
     }

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

@@ -328,6 +328,8 @@ class SettingController extends Controller
     {
         $defaults = [
             'mapProvider'                 => 'leaflet',
+            'leafletTileUrl'              => '',
+            'leafletDarkTileUrl'          => '',
             'googleMapsMapType'           => 'roadmap',
             'showGoogleMapsTrafficLayer'  => false,
             'showGoogleMapsTransitLayer'  => false,
@@ -418,12 +420,32 @@ class SettingController extends Controller
         return [
             ...$settings,
             'mapProvider'                => $mapProvider,
+            'leafletTileUrl'             => $this->sanitizeTileUrl(data_get($settings, 'leafletTileUrl', '')),
+            'leafletDarkTileUrl'         => $this->sanitizeTileUrl(data_get($settings, 'leafletDarkTileUrl', '')),
             'googleMapsMapType'          => $googleMapsMapType,
             'showGoogleMapsTrafficLayer' => filter_var(data_get($settings, 'showGoogleMapsTrafficLayer', false), FILTER_VALIDATE_BOOLEAN),
             'showGoogleMapsTransitLayer' => filter_var(data_get($settings, 'showGoogleMapsTransitLayer', false), FILTER_VALIDATE_BOOLEAN),
         ];
     }
 
+    /**
+     * Sanitize a Leaflet XYZ tile URL template — only http(s) URLs are accepted,
+     * anything else is discarded so the frontend falls back to the default tiles.
+     */
+    protected function sanitizeTileUrl($url): string
+    {
+        if (!is_string($url)) {
+            return '';
+        }
+
+        $url = trim($url);
+        if ($url === '' || !preg_match('/^https?:\/\//i', $url)) {
+            return '';
+        }
+
+        return $url;
+    }
+
     /**
      * Retrieve driver scheduling settings for the current company.
      *

package/server/src/Http/Filter/Concerns/ResolvesPublicRelationUuids.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace Fleetbase\FleetOps\Http\Filter\Concerns;
+
+use Fleetbase\FleetOps\Support\Utils;
+use Fleetbase\Support\Http;
+
+/**
+ * Resolves a relationship filter value expressed as a public identifier into the
+ * internal uuids the column actually stores.
+ *
+ * The public API never hands out uuids, so `?vendor=vendor_abc` has to be
+ * translated before it can be compared against `vendor_uuid`. Internal console
+ * requests deliberately keep passing uuids straight through, so the uuid arm is
+ * gated on the request kind rather than on the shape of the value.
+ */
+trait ResolvesPublicRelationUuids
+{
+    /**
+     * Resolve one or more public identifiers to uuids within the session company.
+     *
+     * @param class-string              $modelClass  the model the identifiers belong to
+     * @param string|array<int, string> $identifiers public_id / internal_id values (uuid when internal)
+     *
+     * @return array<int, string>
+     */
+    protected function resolvePublicRelationUuids(string $modelClass, string|array $identifiers, ?bool $allowUuid = null): array
+    {
+        $identifiers = array_values(array_filter(Utils::arrayFrom($identifiers), static fn ($identifier) => filled($identifier)));
+
+        if ($identifiers === []) {
+            return [];
+        }
+
+        $allowUuid = $allowUuid ?? Http::isInternalRequest($this->request);
+        $instance  = new $modelClass();
+
+        return $modelClass::query()
+            ->where('company_uuid', $this->session->get('company'))
+            ->where(function ($query) use ($identifiers, $instance, $allowUuid) {
+                $query->whereIn('public_id', $identifiers);
+
+                if (in_array('internal_id', $instance->getFillable())) {
+                    $query->orWhereIn('internal_id', $identifiers);
+                }
+
+                if ($allowUuid) {
+                    $query->orWhereIn('uuid', $identifiers);
+                }
+            })
+            ->pluck('uuid')
+            ->all();
+    }
+}