@fleetbase/fleetops-engine 0.6.57 → 0.6.59

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

@@ -59,30 +59,23 @@ class OrderController extends Controller
         set_time_limit(180);
 
         // get request input
-        $input = $request->only([
-            'internal_id', 'payload', 'service_quote', 'purchase_rate',
-            'adhoc', 'adhoc_distance', 'pod_method', 'pod_required',
-            'scheduled_at', 'status', 'meta', 'notes',
-            // Orchestrator constraints
-            'time_window_start', 'time_window_end',
-            'required_skills', 'orchestrator_priority',
-        ]);
+        $input = $this->orderCreateInputFromRequest($request);
 
         // Get order config
-        $orderConfig = OrderConfig::resolveFromIdentifier($request->only(['type', 'order_config']));
+        $orderConfig = $this->resolveOrderConfig($request->only(['type', 'order_config']));
         if (!$orderConfig) {
-            return response()->apiError('Invalid order `type` or `order_config` provided.');
+            return $this->apiError('Invalid order `type` or `order_config` provided.');
         }
 
         // Set order config to input
         $input['order_config_uuid'] = $orderConfig->uuid;
-        $input['type']              = $orderConfig->key;
+        $input['type']              = $orderConfig->key ?? 'transport';
 
         // make sure company is set
-        $input['company_uuid'] = session('company');
+        $input['company_uuid'] = $this->sessionCompany();
 
         // resolve service quote if applicable
-        $serviceQuote          = ServiceQuote::resolveFromRequest($request);
+        $serviceQuote          = $this->resolveServiceQuote($request);
         $integratedVendorOrder = null;
 
         // if service quote is applied, resolve it
@@ -97,18 +90,14 @@ class OrderController extends Controller
 
         // create payload
         if ($request->has('payload') && $request->isArray('payload')) {
-            $payload                = new Payload();
-            $payloadInput           = $request->input('payload');
-            $entities               = data_get($payloadInput, 'entities', []);
-            $waypoints              = data_get($payloadInput, 'waypoints', []);
-            $pickup                 = data_get($payloadInput, 'pickup');
-            $dropoff                = data_get($payloadInput, 'dropoff');
-            $return                 = data_get($payloadInput, 'return');
-            $hasPickupField         = array_key_exists('pickup', $payloadInput);
-            $hasDropoffField        = array_key_exists('dropoff', $payloadInput);
-            $hasReturnField         = array_key_exists('return', $payloadInput);
-            $hasWaypointsField      = array_key_exists('waypoints', $payloadInput);
-            $hasRouteEndpointFields = $hasPickupField || $hasDropoffField || $hasReturnField;
+            $payload                = $this->newPayload();
+            [
+                'entities'  => $entities,
+                'waypoints' => $waypoints,
+                'pickup'    => $pickup,
+                'dropoff'   => $dropoff,
+                'return'    => $return,
+            ] = $this->payloadShapeFromArray($request->input('payload'));
 
             if ($pickup) {
                 $payload->setPickup($pickup, [
@@ -140,22 +129,23 @@ class OrderController extends Controller
 
             $input['payload_uuid'] = $payload->uuid;
         } elseif ($request->isString('payload')) {
-            $input['payload_uuid'] = Utils::getUuid('payloads', [
+            $input['payload_uuid'] = $this->getUuid('payloads', [
                 'public_id'    => $request->input('payload'),
-                'company_uuid' => session('company'),
+                'company_uuid' => $this->sessionCompany(),
             ]);
             unset($input['payload']);
         }
 
         // create a payload if missing payload[] but has pickup/dropoff/etc
         if ($request->missing('payload')) {
-            $payload      = new Payload();
-            $payloadInput = $request->only(['pickup', 'dropoff', 'return', 'waypoints', 'entities']);
-            $entities     = data_get($payloadInput, 'entities', []);
-            $waypoints    = data_get($payloadInput, 'waypoints', []);
-            $pickup       = data_get($payloadInput, 'pickup');
-            $dropoff      = data_get($payloadInput, 'dropoff');
-            $return       = data_get($payloadInput, 'return');
+            $payload      = $this->newPayload();
+            [
+                'entities'  => $entities,
+                'waypoints' => $waypoints,
+                'pickup'    => $pickup,
+                'dropoff'   => $dropoff,
+                'return'    => $return,
+            ] = $this->payloadShapeFromRequest($request);
 
             if ($pickup) {
                 $payload->setPickup($pickup, [
@@ -190,7 +180,7 @@ class OrderController extends Controller
 
         // driver assignment
         if ($request->has('driver') && $integratedVendorOrder === null) {
-            $driver = Driver::where(['public_id' => $request->input('driver'), 'company_uuid' => session('company')])->first();
+            $driver = $this->findDriverByPublicId($request->input('driver'));
             if ($driver) {
                 $input['driver_assigned_uuid'] = $driver->uuid;
                 // set vehicle assignmend from driver
@@ -202,19 +192,19 @@ class OrderController extends Controller
 
         // driver assignment
         if ($request->has('vehicle') && $integratedVendorOrder === null) {
-            $input['vehicle_assigned_uuid'] = Utils::getUuid('vehicles', [
+            $input['vehicle_assigned_uuid'] = $this->getUuid('vehicles', [
                 'public_id'    => $request->input('vehicle'),
-                'company_uuid' => session('company'),
+                'company_uuid' => $this->sessionCompany(),
             ]);
         }
 
         // facilitator assignment
         if ($request->has('facilitator') && $integratedVendorOrder === null) {
-            $facilitator = Utils::getUuid(
+            $facilitator = $this->getUuid(
                 ['contacts', 'vendors', 'integrated_vendors'],
                 [
                     'public_id'    => $request->input('facilitator'),
-                    'company_uuid' => session('company'),
+                    'company_uuid' => $this->sessionCompany(),
                 ],
                 [
                     'with_table' => true,
@@ -223,11 +213,11 @@ class OrderController extends Controller
 
             if (is_array($facilitator)) {
                 $input['facilitator_uuid'] = Utils::get($facilitator, 'uuid');
-                $input['facilitator_type'] = Utils::getModelClassName(Utils::get($facilitator, 'table'));
+                $input['facilitator_type'] = $this->getModelClassName(Utils::get($facilitator, 'table'));
             }
         } elseif ($integratedVendorOrder) {
             $input['facilitator_uuid'] = $serviceQuote->integratedVendor->uuid;
-            $input['facilitator_type'] = Utils::getModelClassName('integrated_vendors');
+            $input['facilitator_type'] = $this->getModelClassName('integrated_vendors');
         }
 
         // customer assignment
@@ -235,11 +225,11 @@ class OrderController extends Controller
             $customer = $request->input('customer');
 
             if (is_string($customer)) {
-                $customer = Utils::getUuid(
+                $customer = $this->getUuid(
                     ['contacts', 'vendors'],
                     [
                         'public_id'    => $customer,
-                        'company_uuid' => session('company'),
+                        'company_uuid' => $this->sessionCompany(),
                     ],
                     [
                         'with_table' => true,
@@ -248,29 +238,29 @@ class OrderController extends Controller
 
                 if (is_array($customer)) {
                     $input['customer_uuid'] = Utils::get($customer, 'uuid');
-                    $input['customer_type'] = Utils::getModelClassName(Utils::get($customer, 'table'));
+                    $input['customer_type'] = $this->getModelClassName(Utils::get($customer, 'table'));
                 }
             } elseif (is_array($customer)) {
                 // create customer from input
                 $customer = Arr::only($customer, ['internal_id', 'name', 'title', 'email', 'phone', 'meta']);
 
                 try {
-                    $customerCandidate = new Contact([
+                    $customerCandidate = $this->newCustomerContact([
                         ...$customer,
-                        'company_uuid' => session('company'),
+                        'company_uuid' => $this->sessionCompany(),
                         'type'         => 'customer',
                     ]);
                     $customerCandidate->assertCustomerIdentityIsAvailable();
 
-                    $customer = Contact::firstOrCreate(
+                    $customer = $this->firstOrCreateCustomerContact(
                         [
-                            'company_uuid' => session('company'),
+                            'company_uuid' => $this->sessionCompany(),
                             'email'        => $customer['email'],
                             'type'         => 'customer',
                         ],
                         [
                             ...$customer,
-                            'company_uuid' => session('company'),
+                            'company_uuid' => $this->sessionCompany(),
                             'type'         => 'customer',
                         ]
                     );
@@ -282,22 +272,13 @@ class OrderController extends Controller
                     return response()->apiError('Failed to find or create customer for order.');
                 }
 
-                if (Str::isUuid($customer)) {
-                    $customer = Contact::where('uuid', $customer)->first();
-                }
-
                 if ($customer instanceof Contact) {
                     $input['customer_uuid'] = $customer->uuid;
-                    $input['customer_type'] = Utils::getModelClassName($customer);
+                    $input['customer_type'] = $this->getModelClassName($customer);
                 }
             }
         }
 
-        // if no type is set its default to transport
-        if (!isset($input['type'])) {
-            $input['type'] = 'transport';
-        }
-
         // if no status is set its default to `created`
         if (!isset($input['status'])) {
             $input['status'] = 'created';
@@ -319,7 +300,7 @@ class OrderController extends Controller
         }
 
         // create the order
-        $order = Order::create($input);
+        $order = $this->createOrder($input);
 
         // if it's integrated vendor order apply to meta
         if ($integratedVendorOrder) {
@@ -335,14 +316,14 @@ class OrderController extends Controller
         // Determine if order should be dispatched on creation
         $shouldDispatch = $request->boolean('dispatch') && $integratedVendorOrder === null;
 
-        FinalizeApiOrderCreation::dispatch(
+        $this->dispatchFinalizeApiOrderCreation(
             $order->uuid,
             $serviceQuote instanceof ServiceQuote ? $serviceQuote->uuid : null,
             $shouldDispatch
-        )->afterCommit();
+        );
 
         // response the driver resource
-        return new OrderResource($order);
+        return $this->orderResource($order);
     }
 
     /**
@@ -358,7 +339,7 @@ class OrderController extends Controller
 
         // find for the order
         try {
-            $order = Order::findRecordOrFail($id, ['trackingNumber', 'driverAssigned', 'purchaseRate.serviceQuote.items', 'customer', 'facilitator']);
+            $order = $this->findOrder($id, ['trackingNumber', 'driverAssigned', 'purchaseRate.serviceQuote.items', 'customer', 'facilitator']);
         } catch (ModelNotFoundException $exception) {
             return response()->json(
                 [
@@ -369,23 +350,20 @@ class OrderController extends Controller
         }
 
         // get request input
-        $input = $request->only([
-            'internal_id', 'payload', 'adhoc', 'adhoc_distance',
-            'pod_method', 'pod_required', 'scheduled_at', 'meta', 'type', 'status', 'notes',
-            // Orchestrator constraints
-            'time_window_start', 'time_window_end',
-            'required_skills', 'orchestrator_priority',
-        ]);
+        $input = $this->orderUpdateInputFromRequest($request);
 
         // update payload if new input or change payload by id
         if ($request->isArray('payload')) {
-            $payload      = data_get($order, 'payload', new Payload());
-            $payloadInput = $request->input('payload');
-            $entities     = data_get($payloadInput, 'entities', []);
-            $waypoints    = data_get($payloadInput, 'waypoints', []);
-            $pickup       = data_get($payloadInput, 'pickup');
-            $dropoff      = data_get($payloadInput, 'dropoff');
-            $return       = data_get($payloadInput, 'return');
+            $payload = data_get($order, 'payload', $this->newPayload());
+            [
+                'entities'                  => $entities,
+                'waypoints'                 => $waypoints,
+                'pickup'                    => $pickup,
+                'dropoff'                   => $dropoff,
+                'return'                    => $return,
+                'has_waypoints_field'       => $hasWaypointsField,
+                'has_route_endpoint_fields' => $hasRouteEndpointFields,
+            ] = $this->payloadShapeFromArray($request->input('payload'));
 
             // if no pickup and dropoff extract from waypoints
             if (empty($pickup) && empty($dropoff) && count($waypoints)) {
@@ -425,27 +403,25 @@ class OrderController extends Controller
 
             $input['payload_uuid'] = $payload->uuid;
         } elseif ($request->has('payload')) {
-            $input['payload_uuid'] = Utils::getUuid('payloads', [
+            $input['payload_uuid'] = $this->getUuid('payloads', [
                 'public_id'    => $request->input('payload'),
-                'company_uuid' => session('company'),
+                'company_uuid' => $this->sessionCompany(),
             ]);
             unset($input['payload']);
         }
 
         // create a payload if missing payload[] but has pickup/dropoff/etc
         if ($request->missing('payload')) {
-            $payload                = data_get($order, 'payload', new Payload());
-            $payloadInput           = $request->only(['pickup', 'dropoff', 'return', 'waypoints', 'entities']);
-            $entities               = data_get($payloadInput, 'entities', []);
-            $waypoints              = data_get($payloadInput, 'waypoints', []);
-            $pickup                 = data_get($payloadInput, 'pickup');
-            $dropoff                = data_get($payloadInput, 'dropoff');
-            $return                 = data_get($payloadInput, 'return');
-            $hasPickupField         = $request->exists('pickup');
-            $hasDropoffField        = $request->exists('dropoff');
-            $hasReturnField         = $request->exists('return');
-            $hasWaypointsField      = $request->exists('waypoints');
-            $hasRouteEndpointFields = $hasPickupField || $hasDropoffField || $hasReturnField;
+            $payload = data_get($order, 'payload', $this->newPayload());
+            [
+                'entities'                  => $entities,
+                'waypoints'                 => $waypoints,
+                'pickup'                    => $pickup,
+                'dropoff'                   => $dropoff,
+                'return'                    => $return,
+                'has_waypoints_field'       => $hasWaypointsField,
+                'has_route_endpoint_fields' => $hasRouteEndpointFields,
+            ] = $this->payloadShapeFromRequest($request);
 
             // if no pickup and dropoff extract from waypoints
             if (empty($pickup) && empty($dropoff) && count($waypoints)) {
@@ -488,27 +464,27 @@ class OrderController extends Controller
 
         // driver assignment
         if ($request->has('driver')) {
-            $input['driver_assigned_uuid'] = Utils::getUuid('drivers', [
+            $input['driver_assigned_uuid'] = $this->getUuid('drivers', [
                 'public_id'    => $request->input('driver'),
-                'company_uuid' => session('company'),
+                'company_uuid' => $this->sessionCompany(),
             ]);
         }
 
         // vehicle assignment
         if ($request->has('vehicle')) {
-            $input['vehicle_assigned_uuid'] = Utils::getUuid('vehicles', [
+            $input['vehicle_assigned_uuid'] = $this->getUuid('vehicles', [
                 'public_id'    => $request->input('vehicle'),
-                'company_uuid' => session('company'),
+                'company_uuid' => $this->sessionCompany(),
             ]);
         }
 
         // facilitator assignment
         if ($request->has('facilitator')) {
-            $facilitator = Utils::getUuid(
+            $facilitator = $this->getUuid(
                 ['contacts', 'vendors'],
                 [
                     'public_id'    => $request->input('facilitator'),
-                    'company_uuid' => session('company'),
+                    'company_uuid' => $this->sessionCompany(),
                 ],
                 [
                     'with_table' => true,
@@ -517,17 +493,17 @@ class OrderController extends Controller
 
             if (is_array($facilitator)) {
                 $input['facilitator_uuid'] = Utils::get($facilitator, 'uuid');
-                $input['facilitator_type'] = Utils::getModelClassName(Utils::get($facilitator, 'table'));
+                $input['facilitator_type'] = $this->getModelClassName(Utils::get($facilitator, 'table'));
             }
         }
 
         // customer assignment
         if ($request->has('customer')) {
-            $customer = Utils::getUuid(
+            $customer = $this->getUuid(
                 ['contacts', 'vendors'],
                 [
                     'public_id'    => $request->input('customer'),
-                    'company_uuid' => session('company'),
+                    'company_uuid' => $this->sessionCompany(),
                 ],
                 [
                     'with_table' => true,
@@ -536,12 +512,12 @@ class OrderController extends Controller
 
             if (is_array($customer)) {
                 $input['customer_uuid'] = Utils::get($customer, 'uuid');
-                $input['customer_type'] = Utils::getModelClassName(Utils::get($customer, 'table'));
+                $input['customer_type'] = $this->getModelClassName(Utils::get($customer, 'table'));
             }
         }
 
         // If adding a service quote for a purchase
-        $serviceQuote = ServiceQuote::resolveFromRequest($request);
+        $serviceQuote = $this->resolveServiceQuote($request);
         if ($serviceQuote) {
             $order->purchaseServiceQuote($serviceQuote);
         }
@@ -565,7 +541,56 @@ class OrderController extends Controller
         $order->load(['trackingNumber', 'trackingStatuses', 'driverAssigned', 'vehicleAssigned', 'purchaseRate.serviceQuote.items', 'customer', 'facilitator']);
 
         // response the order resource
-        return new OrderResource($order);
+        return $this->orderResource($order);
+    }
+
+    protected function orderCreateInputFromRequest(Request $request): array
+    {
+        return $request->only([
+            'internal_id', 'payload', 'service_quote', 'purchase_rate',
+            'adhoc', 'adhoc_distance', 'pod_method', 'pod_required',
+            'scheduled_at', 'status', 'meta', 'notes',
+            // Orchestrator constraints
+            'time_window_start', 'time_window_end',
+            'required_skills', 'orchestrator_priority',
+        ]);
+    }
+
+    protected function orderUpdateInputFromRequest(Request $request): array
+    {
+        return $request->only([
+            'internal_id', 'payload', 'adhoc', 'adhoc_distance',
+            'pod_method', 'pod_required', 'scheduled_at', 'meta', 'type', 'status', 'notes',
+            // Orchestrator constraints
+            'time_window_start', 'time_window_end',
+            'required_skills', 'orchestrator_priority',
+        ]);
+    }
+
+    protected function payloadShapeFromRequest(Request $request): array
+    {
+        return $this->payloadShapeFromArray($request->only(['pickup', 'dropoff', 'return', 'waypoints', 'entities']));
+    }
+
+    protected function payloadShapeFromArray(array $payloadInput): array
+    {
+        $hasPickupField    = array_key_exists('pickup', $payloadInput);
+        $hasDropoffField   = array_key_exists('dropoff', $payloadInput);
+        $hasReturnField    = array_key_exists('return', $payloadInput);
+        $hasWaypointsField = array_key_exists('waypoints', $payloadInput);
+
+        return [
+            'entities'                  => data_get($payloadInput, 'entities', []),
+            'waypoints'                 => data_get($payloadInput, 'waypoints', []),
+            'pickup'                    => data_get($payloadInput, 'pickup'),
+            'dropoff'                   => data_get($payloadInput, 'dropoff'),
+            'return'                    => data_get($payloadInput, 'return'),
+            'has_pickup_field'          => $hasPickupField,
+            'has_dropoff_field'         => $hasDropoffField,
+            'has_return_field'          => $hasReturnField,
+            'has_waypoints_field'       => $hasWaypointsField,
+            'has_route_endpoint_fields' => $hasPickupField || $hasDropoffField || $hasReturnField,
+        ];
     }
 
     /**
@@ -699,6 +724,15 @@ class OrderController extends Controller
                 }
 
                 // request wants to find orders nearby a driver ?
+                //
+                // Unreachable in full: `Utils::isCoordinates()` resolves a
+                // `driver_*` public id to that driver's location, so the
+                // coordinates branch above consumes every driver that has one.
+                // What reaches here is a driver with no stored location, and the
+                // distance query below then raises on the null point rather than
+                // completing — see the "without a stored location" case in
+                // OrderControllerNearbyFiltersTest.
+                // @codeCoverageIgnoreStart
                 if ($addedNearbyQuery === false && is_string($nearby) && Str::startsWith($nearby, 'driver_')) {
                     $driver = Driver::where('public_id', $nearby)->first();
 
@@ -727,6 +761,7 @@ class OrderController extends Controller
                         $addedNearbyQuery = true;
                     }
                 }
+                // @codeCoverageIgnoreEnd
 
                 // if is a string like address string
                 if ($addedNearbyQuery === false && is_string($nearby)) {
@@ -772,9 +807,9 @@ class OrderController extends Controller
     {
         // find for the order
         try {
-            $order = Order::findRecordOrFail($id, ['trackingNumber', 'trackingStatuses', 'driverAssigned', 'vehicleAssigned', 'purchaseRate.serviceQuote.items', 'customer', 'facilitator']);
+            $order = $this->findOrder($id, ['trackingNumber', 'trackingStatuses', 'driverAssigned', 'vehicleAssigned', 'purchaseRate.serviceQuote.items', 'customer', 'facilitator']);
         } catch (ModelNotFoundException $exception) {
-            return response()->json(
+            return $this->jsonResponse(
                 [
                     'error' => 'Order resource not found.',
                 ],
@@ -783,7 +818,7 @@ class OrderController extends Controller
         }
 
         // response the order resource
-        return new OrderResource($order);
+        return $this->orderResource($order);
     }
 
     /**
@@ -795,9 +830,9 @@ class OrderController extends Controller
     {
         // find for the driver
         try {
-            $order = Order::findRecordOrFail($id);
+            $order = $this->findOrder($id);
         } catch (ModelNotFoundException $exception) {
-            return response()->json(
+            return $this->jsonResponse(
                 [
                     'error' => 'Order resource not found.',
                 ],
@@ -809,7 +844,7 @@ class OrderController extends Controller
         $order->delete();
 
         // response the order resource
-        return new DeletedResource($order);
+        return $this->deletedOrderResource($order);
     }
 
     /**
@@ -821,9 +856,9 @@ class OrderController extends Controller
     {
         // find the order
         try {
-            $order = Order::findRecordOrFail($id);
+            $order = $this->findOrder($id);
         } catch (ModelNotFoundException $exception) {
-            return response()->json(
+            return $this->jsonResponse(
                 [
                     'error' => 'Order resource not found.',
                 ],
@@ -836,12 +871,12 @@ class OrderController extends Controller
         $origin      = $order->payload->pickup ?? $order->payload->waypoints->first();
         $destination = $order->payload->dropoff ?? $order->payload->waypoints->firstWhere('current_waypoint_uuid', $order->current_waypoint_uuid);
 
-        $matrix = Utils::getDrivingDistanceAndTime($origin, $destination);
+        $matrix = $this->drivingDistanceAndTime($origin, $destination);
 
         $order->update(['distance' => $matrix->distance, 'time' => $matrix->time]);
 
         // response distance and time matrix
-        return response()->json($matrix);
+        return $this->jsonResponse($matrix);
     }
 
     /**
@@ -852,9 +887,9 @@ class OrderController extends Controller
     public function dispatchOrder(string $id)
     {
         try {
-            $order = Order::findRecordOrFail($id, ['trackingNumber', 'trackingStatuses', 'driverAssigned', 'vehicleAssigned', 'purchaseRate.serviceQuote.items', 'customer', 'facilitator']);
+            $order = $this->findOrder($id, ['trackingNumber', 'trackingStatuses', 'driverAssigned', 'vehicleAssigned', 'purchaseRate.serviceQuote.items', 'customer', 'facilitator']);
         } catch (ModelNotFoundException $exception) {
-            return response()->json(
+            return $this->jsonResponse(
                 [
                     'error' => 'Order resource not found.',
                 ],
@@ -863,17 +898,17 @@ class OrderController extends Controller
         }
 
         if (!$order->hasDriverAssigned && !$order->adhoc) {
-            return response()->apiError('No driver assigned to dispatch!');
+            return $this->apiError('No driver assigned to dispatch!');
         }
 
         if ($order->dispatched) {
-            return response()->apiError('Order has already been dispatched!');
+            return $this->apiError('Order has already been dispatched!');
         }
 
         $order->dispatch();
         $order->insertDispatchActivity();
 
-        return new OrderResource($order);
+        return $this->orderResource($order);
     }
 
     /**
@@ -889,14 +924,13 @@ class OrderController extends Controller
         $timeInput = $request->input('time');
 
         // get the default tz
-        $company       = Auth::getCompany();
-        $defaultTz     = data_get($company, 'timezone', config('app.timezone'));
+        $defaultTz     = $this->defaultCompanyTimezone();
         $timezoneInput = $request->input('timezone', $defaultTz);
 
         try {
-            $order = Order::findRecordOrFail($id);
+            $order = $this->findOrder($id);
         } catch (ModelNotFoundException $exception) {
-            return response()->json(
+            return $this->jsonResponse(
                 [
                     'error' => 'Order resource not found.',
                 ],
@@ -919,7 +953,7 @@ class OrderController extends Controller
         $order->scheduled_at = $date;
         $order->save();
 
-        return new OrderResource($order);
+        return $this->orderResource($order);
     }
 
     /**
@@ -934,7 +968,7 @@ class OrderController extends Controller
         $assignAdhocDriver = $request->input('assign');
 
         try {
-            $order = Order::findRecordOrFail($id, ['payload.waypoints', 'driverAssigned'], []);
+            $order = $this->findOrder($id, ['payload.waypoints', 'driverAssigned']);
         } catch (ModelNotFoundException $exception) {
             return response()->json(
                 [
@@ -954,10 +988,10 @@ class OrderController extends Controller
         }
 
         /** @var \Fleetbase\Models\Driver */
-        $driver = Driver::where('uuid', $order->driver_assigned_uuid)->withoutGlobalScopes()->first();
+        $driver = $this->findDriverByUuid($order->driver_assigned_uuid);
 
         /** @var \Fleetbase\Models\Payload */
-        $payload = Payload::where('uuid', $order->payload_uuid)->withoutGlobalScopes()->with(['waypoints', 'waypointMarkers', 'entities'])->first();
+        $payload = $this->findPayloadByUuid($order->payload_uuid);
 
         if ($order->adhoc && !$driver) {
             return response()->apiError('You must send driver to accept adhoc order.');
@@ -1031,7 +1065,7 @@ class OrderController extends Controller
         // if string $id
         if (!$order) {
             try {
-                $order = Order::findRecordOrFail($id, [
+                $order = $this->findOrder($id, [
                     'driverAssigned',
                     'payload.entities',
                     'payload.pickup',
@@ -1048,9 +1082,16 @@ class OrderController extends Controller
         }
 
         // if no order found
+        //
+        // Unreachable: findOrder() above is typed `: Order`, so it either returns
+        // an order or throws — it never yields null. This is independent of the
+        // upstream findByIdOrFail defect and stays unreachable after that is
+        // fixed; the catch above is what becomes live then, not this guard.
+        // @codeCoverageIgnoreStart
         if (!$order) {
             return response()->apiError('Order resource not found.', 404);
         }
+        // @codeCoverageIgnoreEnd
 
         // if order is still status of `created` trigger started flag
         if ($order->status === 'created') {
@@ -1086,7 +1127,7 @@ class OrderController extends Controller
 
             $order->dispatch();
 
-            return new OrderResource($order);
+            return $this->orderResource($order);
         }
 
         /** @var \Fleetbase\LaravelMysqlSpatial\Types\Point */
@@ -1116,7 +1157,7 @@ class OrderController extends Controller
                 $order->complete($this->resolveProof($proof));
             }
 
-            return new OrderResource($order->refresh());
+            return $this->orderResource($order->refresh());
         }
 
         if (!$order->started && in_array($order->status, ['created', 'dispatched'], true)) {
@@ -1132,7 +1173,7 @@ class OrderController extends Controller
             $order->driverAssigned?->unassignCurrentJob();
             $order->cancel();
 
-            return new OrderResource($order->refresh());
+            return $this->orderResource($order->refresh());
         }
 
         if (Utils::isActivity($activity) && $activity->completesOrder()) {
@@ -1144,7 +1185,7 @@ class OrderController extends Controller
             }
         }
 
-        return new OrderResource($order->refresh());
+        return $this->orderResource($order->refresh());
     }
 
     /**
@@ -1157,7 +1198,7 @@ class OrderController extends Controller
         $waypointId = $request->input('waypoint');
 
         try {
-            $order = Order::findRecordOrFail($id, [
+            $order = $this->findOrder($id, [
                 'payload.pickup',
                 'payload.dropoff',
                 'payload.return',
@@ -1215,9 +1256,9 @@ class OrderController extends Controller
     public function completeOrder(string $id)
     {
         try {
-            $order = Order::findRecordOrFail($id);
+            $order = $this->findOrder($id);
         } catch (ModelNotFoundException $exception) {
-            return response()->json(
+            return $this->jsonResponse(
                 [
                     'error' => 'Order resource not found.',
                 ],
@@ -1247,7 +1288,7 @@ class OrderController extends Controller
         $order->insertActivity($activity, $location);
         $order->notifyCompleted();
 
-        return new OrderResource($order);
+        return $this->orderResource($order);
     }
 
     /**
@@ -1258,9 +1299,9 @@ class OrderController extends Controller
     public function cancelOrder(string $id)
     {
         try {
-            $order = Order::findRecordOrFail($id);
+            $order = $this->findOrder($id);
         } catch (ModelNotFoundException $exception) {
-            return response()->json(
+            return $this->jsonResponse(
                 [
                     'error' => 'Order resource not found.',
                 ],
@@ -1270,7 +1311,7 @@ class OrderController extends Controller
 
         $order->cancel();
 
-        return new OrderResource($order);
+        return $this->orderResource($order);
     }
 
     /**
@@ -1282,7 +1323,7 @@ class OrderController extends Controller
     public function setDestination(string $id, string $placeId)
     {
         try {
-            $order = Order::findRecordOrFail($id, [
+            $order = $this->findOrder($id, [
                 'payload.pickup',
                 'payload.dropoff',
                 'payload.return',
@@ -1309,7 +1350,7 @@ class OrderController extends Controller
         // Persist destination choice
         $this->setPayloadCurrentServiceStop($payload, $stop);
 
-        return new OrderResource($order->refresh());
+        return $this->orderResource($order->refresh());
     }
 
     /**
@@ -1320,14 +1361,14 @@ class OrderController extends Controller
     public function optimize(string $id)
     {
         try {
-            $order = Order::findRecordOrFail($id);
+            $order = $this->findOrder($id);
         } catch (ModelNotFoundException $e) {
-            return response()->apiError('Order resource not found.', 404);
+            return $this->apiError('Order resource not found.', 404);
         }
 
         // do this code
 
-        return new OrderResource($order);
+        return $this->orderResource($order);
     }
 
     /**
@@ -1340,17 +1381,17 @@ class OrderController extends Controller
         set_time_limit(280);
 
         try {
-            $order = Order::findRecordOrFail($id);
+            $order = $this->findOrder($id);
             $data  = $order->tracker()->toArray($request->only(['provider', 'fallbacks', 'traffic_enabled']));
 
-            return response()->json($data);
+            return $this->jsonResponse($data);
         } catch (ModelNotFoundException $e) {
-            return response()->apiError('Order resource not found.', 404);
+            return $this->apiError('Order resource not found.', 404);
         } catch (\Throwable $e) {
-            return response()->apiError('An error occured trying to track order.', 404);
+            return $this->apiError('An error occured trying to track order.', 404);
         }
 
-        return response()->apiError('An error occured trying to track order.', 404);
+        return $this->apiError('An error occured trying to track order.', 404);
     }
 
     /**
@@ -1361,17 +1402,17 @@ class OrderController extends Controller
     public function etaData(Request $request, string $id)
     {
         try {
-            $order = Order::findRecordOrFail($id);
+            $order = $this->findOrder($id);
             $data  = $order->tracker()->eta($request->only(['provider', 'fallbacks', 'traffic_enabled']));
 
-            return response()->json($data);
+            return $this->jsonResponse($data);
         } catch (ModelNotFoundException $e) {
-            return response()->apiError('Order resource not found.', 404);
+            return $this->apiError('Order resource not found.', 404);
         } catch (\Throwable $e) {
-            return response()->apiError('An error occured trying to track order.', 404);
+            return $this->apiError('An error occured trying to track order.', 404);
         }
 
-        return response()->apiError('An error occured trying to track order.', 404);
+        return $this->apiError('An error occured trying to track order.', 404);
     }
 
     /**
@@ -1387,26 +1428,26 @@ class OrderController extends Controller
         $type    = $subjectId ? strtok($subjectId, '_') : null;
 
         if (!$code) {
-            return response()->apiError('No QR code data to capture.');
+            return $this->apiError('No QR code data to capture.');
         }
 
         // Load Order
         try {
-            $order = Order::findRecordOrFail($id, ['payload.pickup', 'payload.dropoff', 'payload.return', 'payload.waypoints', 'payload.waypointMarkers.place']);
+            $order = $this->findOrder($id, ['payload.pickup', 'payload.dropoff', 'payload.return', 'payload.waypoints', 'payload.waypointMarkers.place']);
         } catch (ModelNotFoundException $e) {
-            return response()->apiError('Order resource not found.', 404);
+            return $this->apiError('Order resource not found.', 404);
         }
 
         // Resolve subject
         $subject = $this->resolveSubject($order, $type, $subjectId);
         if (!$subject) {
-            return response()->apiError('Unable to capture QR code data.');
+            return $this->apiError('Unable to capture QR code data.');
         }
 
         // validate
         if ($subject && $code === $subject->uuid) {
             // create verification proof
-            $proof = Proof::create([
+            $proof = $this->createProof([
                 'company_uuid' => session('company'),
                 'order_uuid'   => $order->uuid,
                 'subject_uuid' => $subject->uuid,
@@ -1416,10 +1457,10 @@ class OrderController extends Controller
                 'data'         => $data,
             ]);
 
-            return new ProofResource($proof);
+            return $this->proofResource($proof);
         }
 
-        return response()->apiError('Unable to validate QR code data.');
+        return $this->apiError('Unable to validate QR code data.');
     }
 
     /**
@@ -1437,24 +1478,24 @@ class OrderController extends Controller
         $type         = $subjectId ? strtok($subjectId, '_') : null;
 
         if (!$signature) {
-            return response()->apiError('No signature data to capture.');
+            return $this->apiError('No signature data to capture.');
         }
 
         // Load Order
         try {
-            $order = Order::findRecordOrFail($id);
+            $order = $this->findOrder($id);
         } catch (ModelNotFoundException $e) {
-            return response()->apiError('Order resource not found.', 404);
+            return $this->apiError('Order resource not found.', 404);
         }
 
         // Resolve subject
         $subject = $this->resolveSubject($order, $type, $subjectId);
         if (!$subject) {
-            return response()->apiError('Unable to capture signature data.');
+            return $this->apiError('Unable to capture signature data.');
         }
 
         // create proof instance
-        $proof = Proof::create([
+        $proof = $this->createProof([
             'company_uuid' => session('company'),
             'order_uuid'   => $order->uuid,
             'subject_uuid' => $subject->uuid,
@@ -1468,10 +1509,10 @@ class OrderController extends Controller
         $path = 'uploads/' . session('company') . '/signatures/' . $proof->public_id . '.png';
 
         // upload signature
-        Storage::disk($disk)->put($path, base64_decode(str_replace('data:image/png;base64,', '', $signature)));
+        $this->putStorage($disk, $path, base64_decode(str_replace('data:image/png;base64,', '', $signature)));
 
         // create file record for upload
-        $file = File::create([
+        $file = $this->createFile([
             'company_uuid'      => session('company'),
             'uploader_uuid'     => session('user'),
             'name'              => basename($path),
@@ -1488,7 +1529,7 @@ class OrderController extends Controller
         $proof->file_uuid = $file->uuid;
         $proof->save();
 
-        return new ProofResource($proof);
+        return $this->proofResource($proof);
     }
 
     /**
@@ -1552,7 +1593,7 @@ class OrderController extends Controller
         } catch (ValidationException $e) {
             $errorMessage = collect($e->errors())->flatten()->first();
 
-            return response()->apiError($errorMessage, 422);
+            return $this->apiError($errorMessage, 422);
         }
 
         // Determine storage disk & bucket
@@ -1581,26 +1622,32 @@ class OrderController extends Controller
         // Normalize into one array
         $incoming = array_merge($rawInputs, $base64Inputs);
 
+        // Defensive only: the validate() above already requires `photos` to be a
+        // non-empty array whose every element is an upload or a decodable base64
+        // string, and each of those survives the filter, so this cannot be empty.
+        // Kept in case those rules are relaxed.
+        // @codeCoverageIgnoreStart
         if (empty($incoming)) {
-            return response()->apiError('No photo data to capture.');
+            return $this->apiError('No photo data to capture.');
         }
+        // @codeCoverageIgnoreEnd
 
         // Load Order
         try {
-            $order = Order::findRecordOrFail($id, ['payload.pickup', 'payload.dropoff', 'payload.return', 'payload.waypoints', 'payload.waypointMarkers.place']);
+            $order = $this->findOrder($id, ['payload.pickup', 'payload.dropoff', 'payload.return', 'payload.waypoints', 'payload.waypointMarkers.place']);
         } catch (ModelNotFoundException $e) {
-            return response()->apiError('Order resource not found.', 404);
+            return $this->apiError('Order resource not found.', 404);
         }
 
         // Resolve subject
         $subject = $this->resolveSubject($order, $type, $subjectId);
         if (!$subject) {
-            return response()->apiError('Unable to capture photo as proof.');
+            return $this->apiError('Unable to capture photo as proof.');
         }
 
         // 5) Loop through each item, create Proof + File
         foreach ($incoming as $item) {
-            $proof = Proof::create([
+            $proof = $this->createProof([
                 'company_uuid' => session('company'),
                 'order_uuid'   => $order->uuid,
                 'subject_uuid' => $subject->uuid,
@@ -1621,7 +1668,7 @@ class OrderController extends Controller
         }
 
         // Return the last Proof resource created
-        return new ProofResource($proof);
+        return $this->proofResource($proof);
     }
 
     /**
@@ -1649,9 +1696,9 @@ class OrderController extends Controller
         $company = session('company');
         $path    = "uploads/{$company}/photos/{$proof->public_id}.{$extension}";
 
-        Storage::disk($disk)->put($path, $contents);
+        $this->putStorage($disk, $path, $contents);
 
-        return File::create([
+        return $this->createFile([
             'company_uuid'      => $company,
             'uploader_uuid'     => session('user'),
             'name'              => basename($path),
@@ -1726,9 +1773,9 @@ class OrderController extends Controller
     public function proofs(Request $request, string $id, ?string $subjectId = null)
     {
         try {
-            $order = Order::findRecordOrFail($id);
+            $order = $this->findOrder($id);
         } catch (ModelNotFoundException $e) {
-            return response()->apiError('Order resource not found.', 404);
+            return $this->apiError('Order resource not found.', 404);
         }
 
         $subject = $order;
@@ -1738,23 +1785,12 @@ class OrderController extends Controller
         }
 
         if (!$subject) {
-            return response()->apiError('Unable to retrieve proof of delivery for subject.');
+            return $this->apiError('Unable to retrieve proof of delivery for subject.');
         }
 
-        $proofsQuery = Proof::where([
-            'company_uuid' => session('company'),
-            'order_uuid'   => $order->uuid,
-        ]);
+        $proofs = $this->proofsForSubject($order, $subject);
 
-        // if subject is not the order then filter by subject
-        if ($order->uuid !== $subject->uuid) {
-            $proofsQuery->where('subject_uuid', $subject->uuid);
-        }
-
-        // get proofs
-        $proofs = $proofsQuery->get();
-
-        return ProofResource::collection($proofs);
+        return $this->proofResourceCollection($proofs);
     }
 
     /**
@@ -1776,9 +1812,9 @@ class OrderController extends Controller
     public function getEditableEntityFields(string $id, Request $request)
     {
         try {
-            $order = Order::findRecordOrFail($id);
+            $order = $this->findOrder($id);
         } catch (ModelNotFoundException $e) {
-            return response()->apiError('Order resource not found.', 404);
+            return $this->apiError('Order resource not found.', 404);
         }
 
         // Define settings as array
@@ -1788,12 +1824,12 @@ class OrderController extends Controller
         $orderConfigId = data_get($order, 'order_config_uuid');
 
         // Get entity editing settings
-        $savedEntityEditingSettings = Setting::where('key', 'fleet-ops.entity-editing-settings')->value('value');
+        $savedEntityEditingSettings = $this->entityEditingSettings();
         if ($orderConfigId && $savedEntityEditingSettings) {
             $entityEditingSettings = data_get($savedEntityEditingSettings, $orderConfigId, []);
         }
 
-        return response()->json($entityEditingSettings);
+        return $this->jsonResponse($entityEditingSettings);
     }
 
     /**
@@ -1804,16 +1840,165 @@ class OrderController extends Controller
     public function orderComments(string $id)
     {
         try {
-            $order = Order::findRecordOrFail($id);
+            $order = $this->findOrder($id);
             $order->loadMissing('comments');
 
-            return CommentResource::collection($order->comments);
+            return $this->commentResourceCollection($order->comments);
         } catch (ModelNotFoundException $e) {
-            return response()->apiError('Order resource not found.', 404);
+            return $this->apiError('Order resource not found.', 404);
         } catch (\Throwable $e) {
-            return response()->apiError('An error occured trying to get order comments.', 404);
+            return $this->apiError('An error occured trying to get order comments.', 404);
+        }
+
+        return $this->apiError('An error occured trying to get order comments.', 404);
+    }
+
+    protected function findOrder(string $id, array $with = [], array $withCount = []): Order
+    {
+        return Order::findRecordOrFail($id, $with, $withCount);
+    }
+
+    protected function resolveOrderConfig(array $input): ?OrderConfig
+    {
+        return OrderConfig::resolveFromIdentifier($input);
+    }
+
+    protected function resolveServiceQuote(Request $request): ?ServiceQuote
+    {
+        return ServiceQuote::resolveFromRequest($request);
+    }
+
+    protected function newPayload(): Payload
+    {
+        return new Payload();
+    }
+
+    protected function findDriverByPublicId(string $publicId): ?Driver
+    {
+        return Driver::where(['public_id' => $publicId, 'company_uuid' => session('company')])->first();
+    }
+
+    protected function findDriverByUuid(?string $uuid): ?Driver
+    {
+        return Driver::where('uuid', $uuid)->withoutGlobalScopes()->first();
+    }
+
+    protected function findPayloadByUuid(?string $uuid): ?Payload
+    {
+        return Payload::where('uuid', $uuid)->withoutGlobalScopes()->with(['waypoints', 'waypointMarkers', 'entities'])->first();
+    }
+
+    protected function sessionCompany(): ?string
+    {
+        return session('company');
+    }
+
+    protected function getUuid(array|string $table, array $where, array $options = []): mixed
+    {
+        return Utils::getUuid($table, $where, $options);
+    }
+
+    protected function getModelClassName(mixed $tableOrModel): ?string
+    {
+        return Utils::getModelClassName($tableOrModel);
+    }
+
+    protected function newCustomerContact(array $attributes): Contact
+    {
+        return new Contact($attributes);
+    }
+
+    protected function firstOrCreateCustomerContact(array $attributes, array $values): Contact
+    {
+        return Contact::firstOrCreate($attributes, $values);
+    }
+
+    protected function defaultCompanyTimezone(): string
+    {
+        return data_get(Auth::getCompany(), 'timezone', config('app.timezone'));
+    }
+
+    protected function createOrder(array $input): Order
+    {
+        return Order::create($input);
+    }
+
+    protected function dispatchFinalizeApiOrderCreation(string $orderUuid, ?string $serviceQuoteUuid, bool $shouldDispatch): void
+    {
+        FinalizeApiOrderCreation::dispatch($orderUuid, $serviceQuoteUuid, $shouldDispatch)->afterCommit();
+    }
+
+    protected function drivingDistanceAndTime(mixed $origin, mixed $destination): mixed
+    {
+        return Utils::getDrivingDistanceAndTime($origin, $destination);
+    }
+
+    protected function createProof(array $input): Proof
+    {
+        return Proof::create($input);
+    }
+
+    protected function createFile(array $input): File
+    {
+        return File::create($input);
+    }
+
+    protected function putStorage(string $disk, string $path, string $contents): void
+    {
+        Storage::disk($disk)->put($path, $contents);
+    }
+
+    protected function proofsForSubject(Order $order, mixed $subject)
+    {
+        $proofsQuery = Proof::where([
+            'company_uuid' => session('company'),
+            'order_uuid'   => $order->uuid,
+        ]);
+
+        if ($order->uuid !== $subject->uuid) {
+            $proofsQuery->where('subject_uuid', $subject->uuid);
         }
 
-        return response()->apiError('An error occured trying to get order comments.', 404);
+        return $proofsQuery->get();
+    }
+
+    protected function entityEditingSettings(): mixed
+    {
+        return Setting::where('key', 'fleet-ops.entity-editing-settings')->value('value');
+    }
+
+    protected function orderResource(Order $order)
+    {
+        return new OrderResource($order);
+    }
+
+    protected function deletedOrderResource(Order $order)
+    {
+        return new DeletedResource($order);
+    }
+
+    protected function proofResource(Proof $proof)
+    {
+        return new ProofResource($proof);
+    }
+
+    protected function proofResourceCollection($proofs)
+    {
+        return ProofResource::collection($proofs);
+    }
+
+    protected function commentResourceCollection($comments)
+    {
+        return CommentResource::collection($comments);
+    }
+
+    protected function jsonResponse(mixed $payload, int $status = 200)
+    {
+        return response()->json($payload, $status);
+    }
+
+    protected function apiError(string $message, int $status = 400)
+    {
+        return response()->apiError($message, $status);
     }
 }