@fleetbase/fleetops-engine 0.6.49 → 0.6.51

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

@@ -3,9 +3,13 @@
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
 use Fleetbase\Exceptions\FleetbaseRequestValidationException;
+use Fleetbase\FleetOps\Events\EntityActivityChanged;
+use Fleetbase\FleetOps\Events\EntityCompleted;
 use Fleetbase\FleetOps\Events\OrderDispatchFailed;
 use Fleetbase\FleetOps\Events\OrderReady;
 use Fleetbase\FleetOps\Events\OrderStarted;
+use Fleetbase\FleetOps\Events\WaypointActivityChanged;
+use Fleetbase\FleetOps\Events\WaypointCompleted;
 use Fleetbase\FleetOps\Exports\OrderExport;
 use Fleetbase\FleetOps\Flow\Activity;
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
@@ -27,6 +31,7 @@ use Fleetbase\FleetOps\Models\ServiceQuote;
 use Fleetbase\FleetOps\Models\TrackingStatus;
 use Fleetbase\FleetOps\Models\Waypoint;
 use Fleetbase\FleetOps\Notifications\OrderPing;
+use Fleetbase\FleetOps\Support\ResolvesOrderServiceStops;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Http\Requests\ExportRequest;
 use Fleetbase\Http\Requests\Internal\BulkActionRequest;
@@ -37,13 +42,17 @@ use Fleetbase\Support\TemplateString;
 use Illuminate\Database\Eloquent\ModelNotFoundException;
 use Illuminate\Database\QueryException;
 use Illuminate\Http\Request;
+use Illuminate\Http\UploadedFile;
 use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Storage;
 use Illuminate\Support\Facades\Validator;
 use Illuminate\Support\Str;
 use Maatwebsite\Excel\Facades\Excel;
 
 class OrderController extends FleetOpsController
 {
+    use ResolvesOrderServiceStops;
+
     /**
      * The resource to query.
      *
@@ -63,6 +72,11 @@ class OrderController extends FleetOpsController
      */
     public function onAfterUpdate($request, $order)
     {
+        $uploads = $request->array('order.files');
+        if ($uploads) {
+            $order->attachFiles($uploads);
+        }
+
         $waypoints = $request->array('order.payload.waypoints');
         if ($waypoints) {
             $order->loadMissing('payload');
@@ -165,14 +179,7 @@ class OrderController extends FleetOpsController
                         ->insertEntities($entities);
 
                     // If order creation includes files assosciate each to this order
-                    if ($uploads) {
-                        $ids   = collect($uploads)->pluck('uuid');
-                        $files = File::whereIn('uuid', $ids)->get();
-
-                        foreach ($files as $file) {
-                            $file->setKey($order);
-                        }
-                    }
+                    $order->attachFiles($uploads);
 
                     // save custom field values
                     if (is_array($customFieldValues)) {
@@ -668,28 +675,9 @@ class OrderController extends FleetOpsController
         // get the next order activity
         $flow = $activity = $order->config()->nextFirstActivity();
 
-        /**
-         * @var \Fleetbase\LaravelMysqlSpatial\Types\Point
-         */
-        $location = $order->getLastLocation();
-
-        // if multi drop order set first destination
-        if ($payload->isMultipleDropOrder) {
-            $firstDestination = $payload->waypoints->first();
-
-            if ($firstDestination) {
-                $payload->current_waypoint_uuid = $firstDestination->uuid;
-                $payload->save();
-            }
-
-            // update activity for each waypoint and entity
-            foreach ($payload->waypointMarkers as $waypointMarker) {
-                $waypointMarker->insertActivity($activity, $location);
-            }
-
-            foreach ($payload->entities as $entity) {
-                $entity->insertActivity($activity, $location);
-            }
+        // if multi-stop route set first service stop destination
+        if ($this->payloadUsesServiceStopActivity($payload)) {
+            $this->ensurePayloadCurrentServiceStop($payload);
         }
 
         // update order activity
@@ -706,13 +694,31 @@ class OrderController extends FleetOpsController
      */
     public function updateActivity(string $id, Request $request)
     {
-        $order = Order::findById($id, ['driverAssigned', 'payload.entities']);
+        $order = Order::findById($id, [
+            'driverAssigned',
+            'payload.entities',
+            'payload.pickup',
+            'payload.dropoff',
+            'payload.return',
+            'payload.currentWaypoint',
+            'payload.waypoints',
+            'payload.waypointMarkers.place',
+            'payload.waypointMarkers.trackingNumber.status',
+        ]);
         if (!$order) {
             return response()->error('No order found.');
         }
 
-        $activity = $request->array('activity');
-        $activity = new Activity($activity, $order->getConfigFlow());
+        $proof       = $request->input('proof');
+        $bypassProof = $request->boolean('bypass_proof');
+        $activity    = $request->array('activity');
+        $activity    = new Activity($activity, $order->getConfigFlow());
+
+        $requiresProof = Utils::isActivity($activity)
+            && ($activity->get('require_pod') || ($activity->completesOrder() && $order->pod_required));
+        if ($requiresProof && !$proof && !$bypassProof) {
+            return response()->error('Proof of delivery is required for this activity or must be explicitly bypassed.', 422);
+        }
 
         // Handle pickup/dropoff order activity update as normal
         if (Utils::isActivity($activity) && $activity->is('dispatched')) {
@@ -731,29 +737,65 @@ class OrderController extends FleetOpsController
         /**
          * @var \Fleetbase\LaravelMysqlSpatial\Types\Point
          */
-        $location = $order->getLastLocation();
-        $order->setStatus($activity->code);
-        $order->insertActivity($activity, $location);
-
-        // also update for each order entities if not multiple drop order
-        // all entities will share the same activity status as is one drop order
-        if (!$order->payload->isMultipleDropOrder) {
-            foreach ($order->payload->entities as $entity) {
-                $entity->insertActivity($activity, $location);
+        $location                = $order->getLastLocation();
+        $usesServiceStopActivity = $this->payloadUsesServiceStopActivity($order->payload);
+        $isLifecycleActivity     = Utils::isActivity($activity) && in_array($activity->code, ['created', 'dispatched', 'started'], true);
+
+        if (!$usesServiceStopActivity || $isLifecycleActivity) {
+            $order->updateActivity($activity, $proof);
+
+            if (!$usesServiceStopActivity) {
+                foreach ($order->payload->entities as $entity) {
+                    $entity->insertActivity($activity, $location, $proof);
+                }
             }
+
+            if ($usesServiceStopActivity && $activity->is('started')) {
+                $this->ensurePayloadCurrentServiceStop($order->payload);
+            }
+
+            // Handle order completed
+            if (Utils::isActivity($activity) && $activity->completesOrder() && $order->driverAssigned) {
+                // unset from driver current job
+                $order->driverAssigned->unassignCurrentOrder();
+                $order->complete($this->resolveProof($proof));
+            }
+
+            return new OrderResource($order->refresh());
         }
 
-        // Handle order completed
-        if (Utils::isActivity($activity) && $activity->completesOrder() && $order->driverAssigned) {
-            // unset from driver current job
-            $order->driverAssigned->unassignCurrentOrder();
-            $order->complete();
+        if (!$order->started && in_array($order->status, ['created', 'dispatched'])) {
+            return response()->error('Order must be started before waypoint activity can be updated.', 422);
         }
 
-        // Fire activity events
-        $activity->fireEvents($order);
+        $currentStop               = $this->ensurePayloadCurrentServiceStop($order->payload);
+        $isCompletingCurrentStop   = Utils::isActivity($activity) && $activity->complete();
+
+        $this->updateCurrentServiceStopActivity($order, $activity, $location, $proof);
+
+        if (Utils::isActivity($activity) && $activity->is('canceled')) {
+            if ($order->driverAssigned) {
+                $order->driverAssigned->unassignCurrentOrder();
+            }
 
-        return response()->json(['status' => 'ok']);
+            $order->cancel();
+
+            return new OrderResource($order->refresh());
+        }
+
+        if (Utils::isActivity($activity) && $activity->completesOrder()) {
+            $nextStop = $isCompletingCurrentStop ? $this->advanceCurrentServiceStopDestination($order, $order->payload) : null;
+
+            if (!$nextStop || !$currentStop) {
+                if ($order->driverAssigned) {
+                    $order->driverAssigned->unassignCurrentOrder();
+                }
+
+                $order->complete($this->resolveProof($proof));
+            }
+        }
+
+        return new OrderResource($order->refresh());
     }
 
     /**
@@ -769,12 +811,27 @@ class OrderController extends FleetOpsController
             return response()->error('No order found.');
         }
 
-        $waypoint    = $request->filled('waypoint') ? Waypoint::findByPlace($request->input('waypoint'), $order) : null;
+        $order->loadMissing([
+            'payload.pickup',
+            'payload.dropoff',
+            'payload.waypoints',
+            'payload.waypointMarkers.place',
+            'payload.waypointMarkers.trackingNumber.status',
+        ]);
+
+        $canUpdateWaypointActivity = $this->payloadUsesServiceStopActivity($order->payload)
+            && ($order->started || $order->started_at || !in_array($order->status, ['created', 'dispatched']));
+        $stop                      = null;
+        if ($canUpdateWaypointActivity) {
+            $stop = $request->filled('waypoint')
+                ? $this->resolveServiceStopFromKey($order->payload, $request->input('waypoint'))
+                : $this->payloadCurrentServiceStop($order->payload);
+        }
         $orderConfig = $order->ensureOrderConfig();
         if (!$orderConfig) {
             return response()->error('No order config found for order.');
         }
-        $activities = $orderConfig->nextActivity($waypoint);
+        $activities = $stop ? $this->nextActivitiesForServiceStop($order, $order->payload, $stop) : $orderConfig->nextActivity();
 
         // If activity is to complete order add proof of delivery properties if required
         // This is a temporary fix until activity is updated to handle POD on it's own
@@ -794,6 +851,427 @@ class OrderController extends FleetOpsController
         return response()->json($activities);
     }
 
+    /**
+     * Mark a waypoint as the current destination for a multi-waypoint order.
+     *
+     * @return \Fleetbase\Http\Resources\v1\Order
+     */
+    public function setDestination(string $id, string $placeId)
+    {
+        $order = Order::findById($id, [
+            'payload.pickup',
+            'payload.dropoff',
+            'payload.return',
+            'payload.waypoints',
+            'payload.waypointMarkers.place',
+            'payload.waypointMarkers.trackingNumber.status',
+            'driverAssigned',
+            'vehicleAssigned',
+            'customer',
+            'facilitator',
+        ]);
+        if (!$order) {
+            return response()->error('No order found.');
+        }
+
+        if (!$this->payloadUsesServiceStopActivity($order->payload)) {
+            return response()->error('Destination can only be changed for multi-waypoint orders.', 422);
+        }
+
+        $stop = $this->resolveServiceStopFromKey($order->payload, $placeId);
+        if (!$stop) {
+            return response()->error('Place resource is not a valid route destination.', 422);
+        }
+
+        $this->setPayloadCurrentServiceStop($order->payload, $stop);
+
+        return new OrderResource($order->refresh());
+    }
+
+    /**
+     * Capture one or more photos for order/waypoint proof of delivery.
+     *
+     * @return ProofResource|\Illuminate\Http\Response
+     */
+    public function capturePhoto(Request $request, string $id, ?string $subjectId = null)
+    {
+        $incoming  = $this->collectProofPhotoInputs($request);
+        $metadata  = $request->input('data', []);
+        $metadata  = is_array($metadata) ? $metadata : [];
+        $validator = Validator::make([
+            'photos'  => $incoming,
+            'remarks' => $request->input('remarks'),
+            'data'    => $metadata,
+        ], [
+            'photos'   => 'required|array|min:1',
+            'photos.*' => [
+                function ($attribute, $value, $fail) {
+                    if ($value instanceof UploadedFile) {
+                        $extension = strtolower($value->getClientOriginalExtension() ?: $value->extension());
+                        if (
+                            !$value->isValid()
+                            || !in_array($extension, ['jpg', 'jpeg', 'png', 'gif', 'webp'])
+                            || $value->getSize() > 10 * 1024 * 1024
+                        ) {
+                            $fail("{$attribute} must be a valid image file <= 10 MB.");
+                        }
+
+                        return;
+                    }
+
+                    if ($this->isValidBase64ProofPhoto($value)) {
+                        return;
+                    }
+
+                    $fail("{$attribute} must be an image file or a valid Base64 string.");
+                },
+            ],
+            'remarks'  => 'sometimes|string|max:255',
+            'data'     => 'sometimes|array',
+        ]);
+
+        if ($validator->fails()) {
+            $errorMessage = collect($validator->errors()->all())->first();
+
+            return response()->error($errorMessage, 422);
+        }
+
+        $order = Order::findById($id, ['payload.pickup', 'payload.dropoff', 'payload.return', 'payload.waypoints', 'payload.waypointMarkers.place']);
+        if (!$order) {
+            return response()->error('No order found.');
+        }
+
+        $subject = $this->resolveProofSubject($order, $subjectId);
+        if (!$subject) {
+            return response()->error('Unable to capture photo as proof.', 422);
+        }
+
+        $disk    = $request->input('disk', config('filesystems.default'));
+        $bucket  = $request->input("filesystems.disks.{$disk}.bucket", config('filesystems.disks.s3.bucket'));
+        $remarks = $request->input('remarks', 'Verified by Photo');
+        $data    = $metadata;
+
+        if (empty($incoming)) {
+            return response()->error('No photo data to capture.', 422);
+        }
+
+        foreach ($incoming as $item) {
+            $proof = Proof::create([
+                'company_uuid' => session('company'),
+                'order_uuid'   => $order->uuid,
+                'subject_uuid' => $subject->uuid,
+                'subject_type' => Utils::getModelClassName($subject),
+                'remarks'      => $remarks,
+                'raw_data'     => $item instanceof UploadedFile ? null : $item,
+                'data'         => $data,
+            ]);
+
+            $file = $this->storeProofPhoto($proof, $item, $disk, $bucket);
+            $proof->update(['file_uuid' => $file->uuid]);
+        }
+
+        return new ProofResource($proof);
+    }
+
+    /**
+     * Normalize console proof upload payloads into one photo list before validation.
+     */
+    protected function collectProofPhotoInputs(Request $request): array
+    {
+        $incoming = [];
+        foreach (['photos', 'photo', 'files', 'file'] as $key) {
+            $this->appendProofPhotoInputs($incoming, $request->file($key));
+            $this->appendProofPhotoInputs($incoming, $request->input($key));
+        }
+
+        $incoming = array_values(array_filter($incoming, function ($value) {
+            return $value instanceof UploadedFile || is_string($value);
+        }));
+
+        return $this->dedupeProofPhotoInputs($incoming);
+    }
+
+    /**
+     * Append a nested file/input value to the proof input list.
+     */
+    protected function appendProofPhotoInputs(array &$incoming, mixed $value): void
+    {
+        if ($value === null) {
+            return;
+        }
+
+        if (is_array($value)) {
+            foreach ($value as $nested) {
+                $this->appendProofPhotoInputs($incoming, $nested);
+            }
+
+            return;
+        }
+
+        $incoming[] = $value;
+    }
+
+    /**
+     * Remove duplicate photo inputs exposed under multiple multipart aliases.
+     */
+    protected function dedupeProofPhotoInputs(array $incoming): array
+    {
+        $seen = [];
+
+        return array_values(array_filter($incoming, function ($value) use (&$seen) {
+            $fingerprint = $this->proofPhotoInputFingerprint($value);
+            if ($fingerprint === null || isset($seen[$fingerprint])) {
+                return false;
+            }
+
+            $seen[$fingerprint] = true;
+
+            return true;
+        }));
+    }
+
+    /**
+     * Build a stable fingerprint for an uploaded file or Base64 proof payload.
+     */
+    protected function proofPhotoInputFingerprint(mixed $value): ?string
+    {
+        if ($value instanceof UploadedFile) {
+            return hash('sha256', implode('|', [
+                $value->getRealPath(),
+                $value->getSize(),
+                $value->getClientOriginalName(),
+                $value->getClientMimeType(),
+            ]));
+        }
+
+        if (is_string($value)) {
+            $payload = Str::contains($value, 'base64,') ? Str::after($value, 'base64,') : $value;
+
+            return hash('sha256', $payload);
+        }
+
+        return null;
+    }
+
+    /**
+     * Determine whether a proof input is a usable Base64 image payload.
+     */
+    protected function isValidBase64ProofPhoto(mixed $value): bool
+    {
+        if (!is_string($value)) {
+            return false;
+        }
+
+        $payload = Str::contains($value, 'base64,') ? Str::after($value, 'base64,') : $value;
+
+        return base64_decode($payload, true) !== false;
+    }
+
+    /**
+     * Store a proof photo and create its file record.
+     */
+    protected function storeProofPhoto(Proof $proof, UploadedFile|string $photo, string $disk, string $bucket): File
+    {
+        $isFile      = $photo instanceof UploadedFile;
+        $contents    = $isFile ? file_get_contents($photo->getRealPath()) : base64_decode(Str::contains($photo, 'base64,') ? Str::after($photo, 'base64,') : $photo);
+        $extension   = $isFile ? $photo->getClientOriginalExtension() : 'png';
+        $contentType = $isFile ? $photo->getClientMimeType() : 'image/png';
+        $company     = session('company');
+        $path        = "uploads/{$company}/photos/{$proof->public_id}.{$extension}";
+
+        Storage::disk($disk)->put($path, $contents);
+
+        return File::create([
+            'company_uuid'      => $company,
+            'uploader_uuid'     => session('user'),
+            'name'              => basename($path),
+            'original_filename' => basename($path),
+            'extension'         => $extension,
+            'content_type'      => $contentType,
+            'path'              => $path,
+            'bucket'            => $bucket,
+            'type'              => 'photo',
+            'size'              => strlen($contents),
+        ])->setKey($proof);
+    }
+
+    /**
+     * Resolve the subject that proof belongs to.
+     */
+    protected function resolveProofSubject(Order $order, ?string $subjectId = null): Order|Waypoint|Place|null
+    {
+        if (!$subjectId) {
+            return $order;
+        }
+
+        $stop = $this->resolveServiceStopFromKey($order->payload, $subjectId);
+        if ($stop) {
+            return ($stop['waypoint'] ?? null) instanceof Waypoint ? $stop['waypoint'] : ($stop['place'] ?? $order);
+        }
+
+        return Waypoint::withoutGlobalScopes()
+            ->where('payload_uuid', $order->payload_uuid)
+            ->where(function ($query) use ($subjectId) {
+                $query
+                    ->where('public_id', $subjectId)
+                    ->orWhere('uuid', $subjectId)
+                    ->orWhereHas('place', function ($query) use ($subjectId) {
+                        $query->where('public_id', $subjectId)->orWhere('uuid', $subjectId);
+                    });
+            })
+            ->first();
+    }
+
+    /**
+     * Resolve proof to the model expected by order completion.
+     */
+    protected function resolveProof($proof): ?Proof
+    {
+        if ($proof instanceof Proof) {
+            return $proof;
+        }
+
+        if (is_string($proof)) {
+            return Proof::where('public_id', $proof)->orWhere('uuid', $proof)->first();
+        }
+
+        return null;
+    }
+
+    /**
+     * Determine whether the payload should use waypoint-scoped activity.
+     */
+    protected function payloadHasWaypoints(?Payload $payload): bool
+    {
+        if (!$payload) {
+            return false;
+        }
+
+        $payload->loadMissing('waypoints');
+
+        return $payload->waypoints->isNotEmpty();
+    }
+
+    /**
+     * Insert an activity on the payload's current waypoint and its destination entities.
+     */
+    protected function updateCurrentWaypointActivity(?Payload $payload, Activity $activity, $location = null, $proof = null): ?Waypoint
+    {
+        if (!$payload || !Utils::isActivity($activity) || !$location) {
+            return null;
+        }
+
+        $payload->loadMissing(['order', 'waypointMarkers', 'entities']);
+        $currentWaypoint = $payload->waypointMarkers->firstWhere('place_uuid', $payload->current_waypoint_uuid);
+        if (!$currentWaypoint) {
+            return null;
+        }
+
+        $currentWaypoint->insertActivity($activity, $location, $proof);
+        $activity->fireEvents($payload->order, $currentWaypoint);
+
+        $entities = $payload->entities->where('destination_uuid', $payload->current_waypoint_uuid);
+        foreach ($entities as $entity) {
+            $entity->insertActivity($activity, $location, $proof);
+            if ($activity->complete()) {
+                event(new EntityCompleted($entity, $activity));
+            } else {
+                event(new EntityActivityChanged($entity, $activity));
+            }
+        }
+
+        if ($activity->complete()) {
+            event(new WaypointCompleted($currentWaypoint, $activity));
+        } else {
+            event(new WaypointActivityChanged($currentWaypoint, $activity));
+        }
+
+        return $currentWaypoint;
+    }
+
+    /**
+     * Reload waypoint marker status and decide whether every stop is complete.
+     */
+    protected function allWaypointMarkersComplete(?Payload $payload): bool
+    {
+        if (!$payload) {
+            return false;
+        }
+
+        $waypointMarkers = $this->freshWaypointMarkers($payload);
+
+        return $waypointMarkers->isNotEmpty() && $waypointMarkers->every(fn (Waypoint $waypoint) => $this->waypointMarkerIsComplete($waypoint));
+    }
+
+    /**
+     * Move the current destination to the next incomplete waypoint.
+     */
+    protected function advanceCurrentWaypointDestination(?Payload $payload): ?Waypoint
+    {
+        if (!$payload) {
+            return null;
+        }
+
+        $nextWaypoint = $this->freshWaypointMarkers($payload)
+            ->sortBy('order')
+            ->first(function (Waypoint $waypoint) use ($payload) {
+                return !$this->waypointMarkerIsComplete($waypoint) && $waypoint->place_uuid !== $payload->current_waypoint_uuid;
+            });
+
+        if (!$nextWaypoint) {
+            return null;
+        }
+
+        $payload->setCurrentWaypoint($nextWaypoint);
+        $payload->setRelation('currentWaypoint', $nextWaypoint->getPlace());
+        $payload->setRelation('currentWaypointMarker', $nextWaypoint);
+
+        return $nextWaypoint;
+    }
+
+    /**
+     * Reload waypoint markers with current tracking status.
+     */
+    protected function freshWaypointMarkers(Payload $payload)
+    {
+        $payload->unsetRelation('waypointMarkers');
+        $payload->load(['waypointMarkers.trackingNumber.status']);
+
+        return $payload->waypointMarkers;
+    }
+
+    /**
+     * Determine whether a waypoint marker's latest status is complete.
+     */
+    protected function waypointMarkerIsComplete(Waypoint $waypoint): bool
+    {
+        if (!$waypoint->tracking_number_uuid) {
+            return false;
+        }
+
+        return (bool) data_get($this->trackingNumberStatus($waypoint->tracking_number_uuid), 'complete', false);
+    }
+
+    /**
+     * Determine whether the payload's current waypoint already has an activity row.
+     */
+    protected function payloadHasCurrentWaypointActivity(?Payload $payload, Activity $activity): bool
+    {
+        if (!$payload || !$payload->current_waypoint_uuid) {
+            return false;
+        }
+
+        $payload->loadMissing('waypointMarkers');
+        $currentWaypoint = $payload->waypointMarkers->firstWhere('place_uuid', $payload->current_waypoint_uuid);
+        if (!$currentWaypoint || !$currentWaypoint->tracking_number_uuid) {
+            return false;
+        }
+
+        return TrackingStatus::where('tracking_number_uuid', $currentWaypoint->tracking_number_uuid)
+            ->where('code', TrackingStatus::prepareCode($activity->code))
+            ->exists();
+    }
+
     /**
      * Finds and responds with the orders next activity update based on the orders configuration.
      *