@fleetbase/fleetops-engine 0.6.57 → 0.6.59

package/server/tests/Feature/Http/Api/OrderControllerStartActivityTest.php

@@ -0,0 +1,663 @@
+<?php
+
+use Fleetbase\FleetOps\Http\Controllers\Api\v1\OrderController;
+use Fleetbase\FleetOps\Http\Requests\CreateOrderRequest;
+use Fleetbase\FleetOps\Http\Requests\UpdateOrderRequest;
+use Fleetbase\FleetOps\Models\Order;
+use Illuminate\Database\ConnectionResolver;
+use Illuminate\Database\Eloquent\Model as EloquentModel;
+use Illuminate\Database\SQLiteConnection;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Str;
+
+/**
+ * Covers the API OrderController startOrder and updateActivity flows against
+ * SQLite with a real transport order config: the not-found/already-started/
+ * missing-driver/not-dispatched error branches, the skip-dispatch success
+ * path delegating into updateActivity, and the updateActivity completed and
+ * dispatch-failed branches.
+ */
+if (!function_exists('Fleetbase\Support\session')) {
+    eval('namespace Fleetbase\Support; function session($key = null, $default = null) { if ($key === null) { return new class { public function has($k) { return \session($k) !== null; } public function get($k, $d = null) { return \session($k, $d); } }; } return \session($key, $default); }');
+}
+
+if (!function_exists('Fleetbase\Support\auth')) {
+    eval('namespace Fleetbase\Support; function auth() { return new class { public function user() { return null; } public function id() { return null; } }; }');
+}
+
+if (!function_exists('Fleetbase\FleetOps\Http\Controllers\Api\v1\event')) {
+    eval('namespace Fleetbase\FleetOps\Http\Controllers\Api\v1; function event($event = null) { if (\FleetOpsOrderStartRecorder::$throwOnEvent) { throw new \RuntimeException(\'event listener blew up\'); } \FleetOpsOrderStartRecorder::$events[] = $event; return $event; }');
+}
+
+if (!function_exists('Fleetbase\Observers\event')) {
+    eval('namespace Fleetbase\Observers; function event($event = null, $payload = []) { return []; }');
+}
+
+if (!function_exists('Fleetbase\FleetOps\Models\dispatch')) {
+    eval('namespace Fleetbase\FleetOps\Models; function dispatch($job = null) { $GLOBALS["fleetopsOrderStartDispatches"][] = $job; return new class { public function afterCommit() { return $this; } public function __call($m, $a) { return $this; } }; }');
+}
+
+if (!function_exists('Fleetbase\FleetOps\Models\event')) {
+    eval('namespace Fleetbase\FleetOps\Models; function event($event = null) { \FleetOpsOrderStartRecorder::$events[] = $event; return $event; }');
+}
+
+if (!Request::hasMacro('or')) {
+    Request::macro('or', function (array $params = [], $default = null) {
+        foreach ($params as $param) {
+            if ($this->has($param)) {
+                return $this->input($param);
+            }
+        }
+
+        return $default;
+    });
+}
+
+if (!Request::hasMacro('isString')) {
+    Request::macro('isString', function ($key) {
+        return is_string($this->input($key));
+    });
+}
+
+if (!Request::hasMacro('isArray')) {
+    Request::macro('isArray', function ($key) {
+        return is_array($this->input($key));
+    });
+}
+
+class FleetOpsOrderStartRecorder
+{
+    public static array $events = [];
+
+    /** When set, the event() shim throws so failure branches can be reached. */
+    public static bool $throwOnEvent = false;
+}
+
+function fleetopsOrderStartBoot(): SQLiteConnection
+{
+    if (!Str::hasMacro('humanize')) {
+        Str::macro('humanize', fn ($value, $uppercase = true) => str_replace('_', ' ', Str::snake((string) $value)));
+    }
+
+    $pdo = new PDO('sqlite::memory:');
+    $pdo->sqliteCreateFunction('ST_PointFromText', fn ($wkt, $srid = 0, $axisOrder = null) => $wkt);
+    $pdo->sqliteCreateFunction('ST_GeomFromText', fn ($wkt, $srid = 0, $axisOrder = null) => $wkt);
+    $connection = new SQLiteConnection($pdo);
+    $resolver   = new ConnectionResolver(['default' => $connection, 'mysql' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    EloquentModel::setConnectionResolver($resolver);
+    if (!EloquentModel::getEventDispatcher()) {
+        EloquentModel::setEventDispatcher(new Illuminate\Events\Dispatcher());
+    }
+    app()->instance('db', new class($connection) {
+        public function __construct(public SQLiteConnection $c)
+        {
+        }
+
+        public function connection($name = null): SQLiteConnection
+        {
+            return $this->c;
+        }
+
+        public function __call($method, $arguments)
+        {
+            return $this->c->{$method}(...$arguments);
+        }
+    });
+    Illuminate\Support\Facades\DB::clearResolvedInstance('db');
+
+    app()->instance('geocoder', new class {
+        public function geocode($query)
+        {
+            return $this;
+        }
+
+        public function reverse($lat, $lng)
+        {
+            return $this;
+        }
+
+        public function get()
+        {
+            return collect();
+        }
+
+        public function __call($method, $arguments)
+        {
+            return $this;
+        }
+    });
+    app()->instance('responsecache', new class {
+        public function __call($method, $arguments)
+        {
+            return null;
+        }
+    });
+    config()->set('activitylog.enabled', false);
+    config()->set('activitylog.default_auth_driver', 'web');
+    app()->bind(Illuminate\Contracts\Config\Repository::class, fn () => config());
+
+    $barcodeFake = new class {
+        public function __call($method, $arguments)
+        {
+            return 'barcode';
+        }
+    };
+    app()->instance('DNS2D', $barcodeFake);
+    app()->instance('DNS1D', $barcodeFake);
+
+    $schema = $connection->getSchemaBuilder();
+    app()->instance('db.schema', $schema);
+    $tables = [
+        'orders'              => ['uuid', 'public_id', 'internal_id', 'company_uuid', 'payload_uuid', 'order_config_uuid', 'tracking_number_uuid', 'driver_assigned_uuid', 'status', 'type', 'adhoc', 'dispatched', 'dispatched_at', 'started', 'started_at', 'scheduled_at', 'meta', 'distance', 'time', 'pod_required', 'pod_method', 'orchestrator_priority', 'adhoc_distance', 'notes', 'customer_uuid', 'customer_type', 'facilitator_uuid', 'facilitator_type', 'vehicle_assigned_uuid', 'route_uuid', 'purchase_rate_uuid', 'transaction_uuid', 'time_window_start', 'time_window_end', 'required_skills', '_key'],
+        'payloads'            => ['uuid', 'public_id', 'company_uuid', 'pickup_uuid', 'dropoff_uuid', 'return_uuid', 'current_waypoint_uuid', 'pickup_tracking_number_uuid', 'dropoff_tracking_number_uuid', 'meta', 'type', 'payment_method', 'cod_amount', 'cod_currency', '_key'],
+        'places'              => ['uuid', 'public_id', 'company_uuid', 'name', 'street1', 'city', 'country', 'location', 'meta', 'street2', 'province', 'postal_code', 'phone', 'type', 'owner_uuid', 'owner_type', '_key', '_import_id'],
+        'waypoints'           => ['uuid', 'public_id', 'company_uuid', 'payload_uuid', 'place_uuid', 'tracking_number_uuid', 'customer_uuid', 'customer_type', 'order', 'type', '_key', '_import_id'],
+        'drivers'             => ['uuid', 'public_id', 'company_uuid', 'user_uuid', 'vehicle_uuid', 'status', 'online', 'location', 'current_job_uuid'],
+        'users'               => ['uuid', 'public_id', 'company_uuid', 'name', 'status', 'type', 'email', 'phone', 'password', 'slug', 'username', 'meta', '_key'],
+        'order_configs'       => ['uuid', 'public_id', 'company_uuid', 'name', 'key', 'namespace', 'description', 'flow', 'entities', 'meta', 'version', 'core_service', 'status', 'type', '_key'],
+        'tracking_numbers'    => ['uuid', 'public_id', 'company_uuid', 'tracking_number', 'region', 'location', 'status_uuid', 'owner_uuid', 'owner_type', 'qr_code', 'barcode', '_key'],
+        'tracking_statuses'   => ['uuid', 'public_id', 'company_uuid', 'tracking_number_uuid', 'proof_uuid', 'status', 'details', 'location', 'code', 'complete', '_key'],
+        'entities'            => ['uuid', 'public_id', 'company_uuid', 'payload_uuid', 'destination_uuid', 'tracking_number_uuid', 'customer_uuid', 'customer_type', 'name', 'type', 'meta', 'internal_id', 'qr_code', 'barcode', 'photo_uuid', '_key', '_import_id'],
+        'proofs'              => ['uuid', 'public_id', 'company_uuid', 'subject_uuid', 'subject_type', 'remarks', 'raw_data', 'data'],
+        'companies'           => ['uuid', 'public_id', 'name', 'country'],
+        'positions'           => ['uuid', 'public_id', 'company_uuid', 'subject_uuid', 'subject_type', 'destination_uuid', 'coordinates', 'heading', 'bearing', 'speed', 'altitude', 'order_uuid', '_key'],
+        'purchase_rates'      => ['uuid', 'public_id', 'company_uuid', 'customer_uuid', 'customer_type', 'service_quote_uuid', 'payload_uuid', 'order_uuid', 'status', 'amount', 'currency', '_key'],
+        'service_quotes'      => ['uuid', 'public_id', 'company_uuid', 'request_id', 'service_rate_uuid', 'payload_uuid', 'amount', 'currency', 'meta', '_key'],
+        'service_quote_items' => ['uuid', 'service_quote_uuid', 'amount', 'details', 'code'],
+        'vehicles'            => ['uuid', 'public_id', 'company_uuid', 'name', 'plate_number', 'location', 'online'],
+        'contacts'            => ['uuid', 'public_id', 'company_uuid', 'name', 'type', 'email', 'phone'],
+        'vendors'             => ['uuid', 'public_id', 'company_uuid', 'name', 'email', 'phone'],
+    ];
+    foreach ($tables as $table => $columns) {
+        $schema->create($table, function ($blueprint) use ($columns) {
+            $blueprint->increments('id');
+            foreach ($columns as $column) {
+                if (in_array($column, ['core_service', 'started', 'adhoc', 'dispatched'], true)) {
+                    $blueprint->integer($column)->nullable();
+                    continue;
+                }
+                $blueprint->string($column)->nullable();
+            }
+            $blueprint->timestamps();
+            $blueprint->timestamp('deleted_at')->nullable();
+        });
+    }
+
+    session(['company' => 'company-1']);
+    $connection->table('companies')->insert(['uuid' => 'company-1', 'name' => 'Acme', 'country' => 'SG']);
+    $connection->table('order_configs')->insert([
+        'uuid'         => 'config-1',
+        'public_id'    => 'order_config_transport',
+        'company_uuid' => 'company-1',
+        'name'         => 'Transport',
+        'key'          => 'transport',
+        'namespace'    => 'system:order-config:transport',
+        'core_service' => 1,
+        'status'       => 'active',
+        'version'      => '0.0.1',
+        'flow'         => json_encode([
+            'order_created' => [
+                'key'        => 'order_created',
+                'code'       => 'created',
+                'status'     => 'Created',
+                'details'    => 'Order created',
+                'activities' => ['order_dispatched'],
+            ],
+            'order_dispatched' => [
+                'key'        => 'order_dispatched',
+                'code'       => 'dispatched',
+                'status'     => 'Dispatched',
+                'details'    => 'Order dispatched',
+                'activities' => ['order_started'],
+            ],
+            'order_started' => [
+                'key'        => 'order_started',
+                'code'       => 'started',
+                'status'     => 'Started',
+                'details'    => 'Order started',
+                'activities' => ['order_completed'],
+            ],
+            'order_completed' => [
+                'key'        => 'order_completed',
+                'code'       => 'completed',
+                'status'     => 'Completed',
+                'details'    => 'Order completed',
+                'complete'   => true,
+                'activities' => [],
+            ],
+        ]),
+    ]);
+    FleetOpsOrderStartRecorder::$events = [];
+
+    return $connection;
+}
+
+function fleetopsOrderStartSeedOrder(SQLiteConnection $connection, array $attributes = []): void
+{
+    $connection->table('users')->insert(['uuid' => 'user-1', 'company_uuid' => 'company-1', 'name' => 'Driver One']);
+    $connection->table('drivers')->insert(['uuid' => 'driver-1', 'public_id' => 'driver_one', 'company_uuid' => 'company-1', 'user_uuid' => 'user-1']);
+    $connection->table('places')->insert([
+        ['uuid' => 'place-p', 'company_uuid' => 'company-1', 'name' => 'Pickup'],
+        ['uuid' => 'place-d', 'company_uuid' => 'company-1', 'name' => 'Dropoff'],
+    ]);
+    $connection->table('payloads')->insert(['uuid' => 'payload-1', 'company_uuid' => 'company-1', 'pickup_uuid' => 'place-p', 'dropoff_uuid' => 'place-d']);
+    $connection->table('tracking_numbers')->insert(['uuid' => 'tn-1', 'company_uuid' => 'company-1', 'tracking_number' => 'TRK-1', 'owner_uuid' => 'order-1']);
+    $connection->table('orders')->insert(array_merge([
+        'uuid'                 => 'order-1',
+        'public_id'            => 'order_start',
+        'company_uuid'         => 'company-1',
+        'payload_uuid'         => 'payload-1',
+        'order_config_uuid'    => 'config-1',
+        'tracking_number_uuid' => 'tn-1',
+        'status'               => 'created',
+        'type'                 => 'transport',
+        'adhoc'                => 0,
+        'dispatched'           => 0,
+        'started'              => 0,
+    ], $attributes));
+}
+
+test('start order rejects unknown started missing driver and undispatched orders', function () {
+    $connection = fleetopsOrderStartBoot();
+    $controller = new OrderController();
+
+    // Unknown order
+    $missing = $controller->startOrder('order_missing', Request::create('/x', 'POST', []));
+    expect($missing)->toBeInstanceOf(JsonResponse::class)
+        ->and($missing->getStatusCode())->toBe(404);
+
+    // Already started
+    fleetopsOrderStartSeedOrder($connection, ['started' => 1]);
+    $started = $controller->startOrder('order_start', Request::create('/x', 'POST', []));
+    expect($started->getData(true)['error'])->toContain('already started');
+
+    // No driver assigned
+    $connection->table('orders')->where('uuid', 'order-1')->update(['started' => 0, 'driver_assigned_uuid' => null]);
+    $noDriver = $controller->startOrder('order_start', Request::create('/x', 'POST', []));
+    expect($noDriver->getData(true)['error'])->toContain('No driver assigned');
+
+    // Adhoc without driver
+    $connection->table('orders')->where('uuid', 'order-1')->update(['adhoc' => 1]);
+    $adhoc = $controller->startOrder('order_start', Request::create('/x', 'POST', []));
+    expect($adhoc->getData(true)['error'])->toContain('driver to accept adhoc');
+
+    // Driver assigned but not dispatched
+    $connection->table('orders')->where('uuid', 'order-1')->update(['adhoc' => 0, 'driver_assigned_uuid' => 'driver-1']);
+    $undispatched = $controller->startOrder('order_start', Request::create('/x', 'POST', []));
+    expect($undispatched->getData(true)['error'])->toContain('not been dispatched');
+});
+
+test('start order with skip dispatch starts the order and assigns the job', function () {
+    $connection = fleetopsOrderStartBoot();
+    fleetopsOrderStartSeedOrder($connection, ['driver_assigned_uuid' => 'driver-1']);
+
+    $result = (new OrderController())->startOrder('order_start', Request::create('/x', 'POST', ['skip_dispatch' => 1]));
+
+    expect($connection->table('orders')->value('started'))->toBe(1)
+        ->and($connection->table('drivers')->value('current_job_uuid'))->toBe('order-1')
+        ->and(collect(FleetOpsOrderStartRecorder::$events)->first(fn ($event) => $event instanceof Fleetbase\FleetOps\Events\OrderStarted))->not->toBeNull();
+});
+
+test('update activity rejects unknown and completed orders', function () {
+    $connection = fleetopsOrderStartBoot();
+    $controller = new OrderController();
+
+    $missing = $controller->updateActivity('order_missing', Request::create('/x', 'POST', []));
+    expect($missing->getStatusCode())->toBe(404);
+
+    fleetopsOrderStartSeedOrder($connection, ['status' => 'completed']);
+    $completed = $controller->updateActivity('order_start', Request::create('/x', 'POST', []));
+    expect($completed->getData(true)['error'])->toContain('already completed');
+});
+
+test('dispatched activity without driver raises dispatch failed', function () {
+    $connection = fleetopsOrderStartBoot();
+    fleetopsOrderStartSeedOrder($connection, ['status' => 'dispatched']);
+
+    $request = Request::create('/x', 'POST', ['activity' => [
+        'key'     => 'order_dispatched',
+        'code'    => 'dispatched',
+        'status'  => 'Dispatched',
+        'details' => 'Order dispatched',
+    ]]);
+
+    $response = (new OrderController())->updateActivity('order_start', $request);
+
+    expect($response->getData(true)['error'])->toContain('No driver assigned')
+        ->and(collect(FleetOpsOrderStartRecorder::$events)->first(fn ($event) => $event instanceof Fleetbase\FleetOps\Events\OrderDispatchFailed))->not->toBeNull();
+});
+
+function fleetopsOrderStartSeedWaypoints(SQLiteConnection $connection): void
+{
+    $connection->table('places')->insert([
+        ['uuid' => 'place-w1', 'company_uuid' => 'company-1', 'name' => 'Stop One'],
+        ['uuid' => 'place-w2', 'company_uuid' => 'company-1', 'name' => 'Stop Two'],
+    ]);
+    $connection->table('tracking_numbers')->insert([
+        ['uuid' => 'tn-w1', 'company_uuid' => 'company-1', 'tracking_number' => 'TRKW1', 'owner_uuid' => 'wp-1'],
+        ['uuid' => 'tn-w2', 'company_uuid' => 'company-1', 'tracking_number' => 'TRKW2', 'owner_uuid' => 'wp-2'],
+    ]);
+    $connection->table('waypoints')->insert([
+        ['uuid' => 'wp-1', 'public_id' => 'waypoint_apistop1', 'company_uuid' => 'company-1', 'payload_uuid' => 'payload-1', 'place_uuid' => 'place-w1', 'tracking_number_uuid' => 'tn-w1', 'order' => '0'],
+        ['uuid' => 'wp-2', 'public_id' => 'waypoint_apistop2', 'company_uuid' => 'company-1', 'payload_uuid' => 'payload-1', 'place_uuid' => 'place-w2', 'tracking_number_uuid' => 'tn-w2', 'order' => '1'],
+    ]);
+    $connection->table('payloads')->where('uuid', 'payload-1')->update(['pickup_uuid' => null, 'dropoff_uuid' => null]);
+}
+
+test('lifecycle activities update classic orders through to completion', function () {
+    $connection = fleetopsOrderStartBoot();
+    fleetopsOrderStartSeedOrder($connection, ['status' => 'dispatched', 'driver_assigned_uuid' => 'driver-1']);
+    $controller = new OrderController();
+
+    // Started lifecycle activity updates order and entity activities
+    $started = $controller->updateActivity('order_start', Request::create('/x', 'POST', ['activity' => [
+        'key' => 'order_started', 'code' => 'started', 'status' => 'Started', 'details' => 'Order started',
+    ]]));
+    expect($connection->table('tracking_statuses')->where('code', 'STARTED')->count())->toBeGreaterThanOrEqual(1);
+
+    // Completing activity completes the order and frees the driver
+    $controller->updateActivity('order_start', Request::create('/x', 'POST', ['activity' => [
+        'key' => 'order_completed', 'code' => 'completed', 'status' => 'Completed', 'details' => 'Order completed', 'complete' => true,
+    ]]));
+    expect($connection->table('tracking_statuses')->where('code', 'COMPLETED')->count())->toBeGreaterThanOrEqual(1);
+});
+
+test('waypoint activities gate on started and advance service stops', function () {
+    $connection = fleetopsOrderStartBoot();
+    fleetopsOrderStartSeedOrder($connection, ['status' => 'created', 'driver_assigned_uuid' => 'driver-1']);
+    fleetopsOrderStartSeedWaypoints($connection);
+    $controller = new OrderController();
+
+    $activity = ['key' => 'order_completed', 'code' => 'completed', 'status' => 'Completed', 'details' => 'Stop completed', 'complete' => true];
+
+    // Waypoint routes on created orders auto-start then advance stop by stop
+    $controller->updateActivity('order_start', Request::create('/x', 'POST', ['activity' => $activity]));
+    expect($connection->table('payloads')->value('current_waypoint_uuid'))->not->toBeNull();
+
+    $controller->updateActivity('order_start', Request::create('/x', 'POST', ['activity' => $activity]));
+    expect($connection->table('tracking_statuses')->where('code', 'COMPLETED')->count())->toBeGreaterThanOrEqual(1);
+});
+
+test('next activity and complete order resolve service stop flows', function () {
+    $connection = fleetopsOrderStartBoot();
+    fleetopsOrderStartSeedOrder($connection, ['status' => 'started', 'started' => 1, 'driver_assigned_uuid' => 'driver-1']);
+    fleetopsOrderStartSeedWaypoints($connection);
+    $controller = new OrderController();
+
+    $next = $controller->getNextActivity('order_start', Request::create('/x', 'GET'));
+    expect($next)->not->toBeNull();
+
+    $scoped = $controller->getNextActivity('order_start', Request::create('/x', 'GET', ['waypoint' => 'waypoint_apistop1']));
+    expect($scoped)->not->toBeNull();
+
+    // Completing with incomplete waypoints errors
+    $incomplete = $controller->completeOrder('order_start');
+    expect($incomplete->getData(true)['error'])->toContain('Not all waypoints');
+
+    // With every waypoint completed the order completes
+    $connection->table('tracking_statuses')->insert([
+        ['uuid' => 'ts-done1', 'company_uuid' => 'company-1', 'tracking_number_uuid' => 'tn-w1', 'code' => 'COMPLETED', 'status' => 'Completed'],
+        ['uuid' => 'ts-done2', 'company_uuid' => 'company-1', 'tracking_number_uuid' => 'tn-w2', 'code' => 'COMPLETED', 'status' => 'Completed'],
+    ]);
+    $completed = $controller->completeOrder('order_start');
+    expect(method_exists($completed, 'getData') ? $completed->getData(true) : [])->not->toHaveKey('error')
+        ->and($connection->table('orders')->value('status'))->toBe('completed');
+});
+
+test('update responds 404 for unknown orders and builds payloads from route fields', function () {
+    $connection = fleetopsOrderStartBoot();
+    fleetopsOrderStartSeedOrder($connection);
+    fleetopsOrderStartSeedWaypoints($connection);
+    Illuminate\Support\Facades\Cache::swap(new class {
+        public function tags($tags = null)
+        {
+            return $this;
+        }
+
+        public function flush()
+        {
+            return true;
+        }
+
+        public function remember($key, $ttl, $callback)
+        {
+            return $callback();
+        }
+
+        public function __call($method, $arguments)
+        {
+            return null;
+        }
+    });
+    // Waypoint customer resolution mutates 'fleetops:contact' into a miscased FQCN
+    app()->bind('Fleetbase\Fleetops\Models\Contact', fn () => new Fleetbase\FleetOps\Models\Contact());
+    $connection->table('places')->insert([
+        ['uuid' => '33333333-3333-4333-8333-333333333331', 'company_uuid' => 'company-1', 'name' => 'Route A'],
+        ['uuid' => '33333333-3333-4333-8333-333333333332', 'company_uuid' => 'company-1', 'name' => 'Route B'],
+        ['uuid' => '33333333-3333-4333-8333-333333333333', 'company_uuid' => 'company-1', 'name' => 'Route C'],
+    ]);
+    $controller = new OrderController();
+
+    $missing = $controller->update('order_missing', UpdateOrderRequest::create('/v1/orders/order_missing', 'PUT', []));
+    expect($missing->getStatusCode())->toBe(404);
+
+    // Waypoint-only route fields: first and last become pickup/dropoff, the middle stays a waypoint
+    $fromWaypoints = $controller->update('order_start', UpdateOrderRequest::create('/v1/orders/order_start', 'PUT', [
+        'waypoints' => ['33333333-3333-4333-8333-333333333331', '33333333-3333-4333-8333-333333333332', '33333333-3333-4333-8333-333333333333'],
+    ]));
+    expect($fromWaypoints)->not->toBeNull()
+        ->and($connection->table('payloads')->value('pickup_uuid'))->toBe('33333333-3333-4333-8333-333333333331')
+        ->and($connection->table('payloads')->value('dropoff_uuid'))->toBe('33333333-3333-4333-8333-333333333333')
+        ->and($connection->table('waypoints')->where('place_uuid', '33333333-3333-4333-8333-333333333332')->whereNull('deleted_at')->count())->toBe(1);
+
+    // Explicit pickup/dropoff/return with entities but no waypoints clears existing waypoints
+    $fromEndpoints = $controller->update('order_start', UpdateOrderRequest::create('/v1/orders/order_start', 'PUT', [
+        'pickup'   => '33333333-3333-4333-8333-333333333331',
+        'dropoff'  => '33333333-3333-4333-8333-333333333332',
+        'return'   => '33333333-3333-4333-8333-333333333333',
+        'entities' => [['name' => 'Box', 'type' => 'parcel']],
+    ]));
+    expect($fromEndpoints)->not->toBeNull()
+        ->and($connection->table('payloads')->value('pickup_uuid'))->toBe('33333333-3333-4333-8333-333333333331')
+        ->and($connection->table('payloads')->value('return_uuid'))->toBe('33333333-3333-4333-8333-333333333333')
+        ->and($connection->table('waypoints')->whereNull('deleted_at')->count())->toBe(0)
+        ->and($connection->table('entities')->where('name', 'Box')->count())->toBe(1);
+
+    // A payload[] array update flows through the same shape including the return stop
+    $fromPayloadArray = $controller->update('order_start', UpdateOrderRequest::create('/v1/orders/order_start', 'PUT', [
+        'payload' => ['pickup' => '33333333-3333-4333-8333-333333333332', 'dropoff' => '33333333-3333-4333-8333-333333333331', 'return' => '33333333-3333-4333-8333-333333333331'],
+    ]));
+    expect($fromPayloadArray)->not->toBeNull()
+        ->and($connection->table('payloads')->value('pickup_uuid'))->toBe('33333333-3333-4333-8333-333333333332')
+        ->and($connection->table('payloads')->value('return_uuid'))->toBe('33333333-3333-4333-8333-333333333331');
+});
+
+test('create rejects invalid configs and orders missing payloads', function () {
+    fleetopsOrderStartBoot();
+    $controller = new OrderController();
+
+    $invalidType = $controller->create(CreateOrderRequest::create('/v1/orders', 'POST', ['type' => 'bogus-type']));
+    expect($invalidType->getData(true)['error'] ?? '')->toContain('Invalid order');
+
+    // Adhoc flags convert to integers and orchestrator priority defaults
+    $adhoc = $controller->create(CreateOrderRequest::create('/v1/orders', 'POST', ['type' => 'transport', 'adhoc' => '1']));
+    expect($adhoc)->not->toBeNull();
+    $connection = app('db')->connection();
+    expect($connection->table('orders')->value('adhoc'))->toBe(1)
+        ->and((string) $connection->table('orders')->value('orchestrator_priority'))->toBe('50');
+});
+
+test('create builds payloads with waypoints and resolves customer uuids', function () {
+    $connection = fleetopsOrderStartBoot();
+    fleetopsOrderStartSeedOrder($connection);
+    fleetopsOrderStartSeedWaypoints($connection);
+    $connection->table('places')->insert(['uuid' => '33333333-3333-4333-8333-333333333334', 'company_uuid' => 'company-1', 'name' => 'Middle Stop']);
+    $connection->table('contacts')->insert(['uuid' => '33333333-3333-4333-8333-333333333335', 'public_id' => 'contact_ordcust1', 'company_uuid' => 'company-1', 'name' => 'Order Customer', 'type' => 'customer']);
+    app()->bind('Fleetbase\Fleetops\Models\Contact', fn () => new Fleetbase\FleetOps\Models\Contact());
+    $controller = new OrderController();
+
+    $created = $controller->create(CreateOrderRequest::create('/v1/orders', 'POST', [
+        'type'       => 'transport',
+        'customer'   => ['name' => 'Created Customer', 'email' => 'ordcust2@example.com'],
+        'dispatched' => false,
+        'payload'    => [
+            'pickup'    => 'place-p',
+            'dropoff'   => 'place-d',
+            'waypoints' => [['place_uuid' => '33333333-3333-4333-8333-333333333334']],
+            'entities'  => [],
+        ],
+    ]));
+
+    // Customer contact creation is attempted; the harness user-provisioning
+    // gap surfaces through the generic customer failure response
+    expect($created->getData(true)['error'] ?? '')->toContain('customer');
+
+    // Staff identities conflict before any contact is created
+    $connection->table('users')->insert(['uuid' => 'user-staff', 'company_uuid' => 'company-1', 'name' => 'Staff', 'type' => 'user', 'email' => 'staff@example.com']);
+    $connection->table('users')->where('uuid', 'user-staff')->update(['status' => 'active']);
+    $connection->table('contacts')->delete();
+    $conflicted = $controller->create(CreateOrderRequest::create('/v1/orders', 'POST', [
+        'type'     => 'transport',
+        'customer' => ['name' => 'Conflicted', 'email' => 'staff@example.com'],
+        'payload'  => ['pickup' => 'place-p', 'dropoff' => 'place-d'],
+    ]));
+    expect($conflicted->getData(true)['error'] ?? '')->not->toBeEmpty();
+});
+
+test('create builds a payload from top level places and defaults the order type', function () {
+    $connection = fleetopsOrderStartBoot();
+    fleetopsOrderStartSeedOrder($connection);
+    $connection->table('places')->insert(['uuid' => 'place-r', 'company_uuid' => 'company-1', 'name' => 'Return Depot']);
+    $connection->table('orders')->delete();
+    $connection->table('payloads')->delete();
+
+    // With no `payload` key the pickup/dropoff/return are read off the request
+    // root, and an order with no explicit type falls back to transport
+    (new OrderController())->create(CreateOrderRequest::create('/v1/orders', 'POST', [
+        'pickup'  => 'place-p',
+        'dropoff' => 'place-d',
+        'return'  => 'place-r',
+    ]));
+
+    // Each key is resolved through Place::createFromMixed, so the payload ends up
+    // pointing at three distinct places rather than the raw keys
+    $payload = $connection->table('payloads')->first();
+    expect($payload)->not->toBeNull()
+        ->and($payload->pickup_uuid)->not->toBeNull()
+        ->and($payload->dropoff_uuid)->not->toBeNull()
+        ->and($payload->return_uuid)->not->toBeNull()
+        ->and([$payload->pickup_uuid, $payload->dropoff_uuid, $payload->return_uuid])
+            ->toHaveCount(count(array_unique([$payload->pickup_uuid, $payload->dropoff_uuid, $payload->return_uuid])))
+        // the pickup callback also primes the payload's current waypoint
+        ->and($payload->current_waypoint_uuid)->toBe($payload->pickup_uuid)
+        ->and($connection->table('orders')->value('type'))->toBe('transport');
+});
+
+test('adhoc start assigns the driver and primes multi-stop payloads', function () {
+    $connection = fleetopsOrderStartBoot();
+    fleetopsOrderStartSeedOrder($connection, ['adhoc' => 1, 'driver_assigned_uuid' => 'driver-1']);
+    fleetopsOrderStartSeedWaypoints($connection);
+
+    $result = (new OrderController())->startOrder('order_start', Request::create('/x', 'POST', [
+        'skip_dispatch' => 1,
+        'assign'        => 'driver_one',
+    ]));
+
+    expect($connection->table('orders')->value('started'))->toBe(1)
+        ->and($connection->table('drivers')->value('current_job_uuid'))->toBe('order-1')
+        ->and($connection->table('payloads')->value('current_waypoint_uuid'))->not->toBeNull();
+});
+
+test('dispatch entity and waypoint gating branches update activities', function () {
+    $connection = fleetopsOrderStartBoot();
+    fleetopsOrderStartSeedOrder($connection, ['status' => 'created', 'driver_assigned_uuid' => 'driver-1']);
+    $controller = new OrderController();
+
+    // Dispatched activity with an assigned driver dispatches the order
+    $dispatched = $controller->updateActivity('order_start', Request::create('/x', 'POST', ['activity' => [
+        'key' => 'order_dispatched', 'code' => 'dispatched', 'status' => 'Dispatched', 'details' => 'Order dispatched',
+    ]]));
+    expect($dispatched)->not->toBeNull()
+        ->and((int) $connection->table('orders')->value('dispatched'))->toBe(1);
+});
+
+test('waypoint activities require started orders before advancing stops', function () {
+    $connection = fleetopsOrderStartBoot();
+    fleetopsOrderStartSeedOrder($connection, ['status' => 'dispatched', 'started' => 0, 'driver_assigned_uuid' => 'driver-1']);
+    fleetopsOrderStartSeedWaypoints($connection);
+    $controller = new OrderController();
+
+    $gated = $controller->updateActivity('order_start', Request::create('/x', 'POST', ['activity' => [
+        'key' => 'custom_stop_activity', 'code' => 'at_stop', 'status' => 'At stop', 'details' => 'Arrived at stop',
+    ]]));
+    expect($gated->getStatusCode())->toBe(422);
+});
+
+test('dispatched activity with skip dispatch advances to the started activity', function () {
+    $connection = fleetopsOrderStartBoot();
+    fleetopsOrderStartSeedOrder($connection, ['status' => 'created', 'driver_assigned_uuid' => 'driver-1']);
+
+    // Asking to skip dispatch swaps the dispatched activity for the started one
+    (new OrderController())->updateActivity('order_start', Request::create('/x', 'POST', [
+        'skip_dispatch' => 1,
+        'activity'      => ['key' => 'order_dispatched', 'code' => 'dispatched', 'status' => 'Dispatched', 'details' => 'Order dispatched'],
+    ]));
+
+    expect($connection->table('tracking_statuses')->where('code', 'STARTED')->count())->toBeGreaterThanOrEqual(1);
+});
+
+test('a failing order started listener does not block the order from starting', function () {
+    $connection = fleetopsOrderStartBoot();
+    fleetopsOrderStartSeedOrder($connection, ['driver_assigned_uuid' => 'driver-1']);
+
+    FleetOpsOrderStartRecorder::$throwOnEvent = true;
+
+    try {
+        (new OrderController())->startOrder('order_start', Request::create('/x', 'POST', ['skip_dispatch' => 1]));
+    } finally {
+        FleetOpsOrderStartRecorder::$throwOnEvent = false;
+    }
+
+    // The listener failure is logged and swallowed, so the order is still
+    // started and the job still assigned to the driver
+    expect($connection->table('orders')->value('started'))->toBe(1)
+        ->and($connection->table('drivers')->value('current_job_uuid'))->toBe('order-1');
+});
+
+test('canceling a waypoint activity unassigns the driver and cancels the order', function () {
+    $connection = fleetopsOrderStartBoot();
+    fleetopsOrderStartSeedOrder($connection, ['status' => 'started', 'started' => 1, 'driver_assigned_uuid' => 'driver-1']);
+    fleetopsOrderStartSeedWaypoints($connection);
+    $connection->table('drivers')->where('uuid', 'driver-1')->update(['current_job_uuid' => 'order-1']);
+
+    $response = (new OrderController())->updateActivity('order_start', Request::create('/x', 'POST', ['activity' => [
+        'key' => 'order_canceled', 'code' => 'canceled', 'status' => 'Canceled', 'details' => 'Customer canceled',
+    ]]));
+
+    expect($response)->not->toBeNull()
+        ->and($connection->table('orders')->value('status'))->toBe('canceled')
+        ->and($connection->table('drivers')->value('current_job_uuid'))->toBeNull();
+});
+
+test('classic lifecycle activities record activity against payload entities', function () {
+    $connection = fleetopsOrderStartBoot();
+    fleetopsOrderStartSeedOrder($connection, ['status' => 'dispatched', 'driver_assigned_uuid' => 'driver-1']);
+    $connection->table('entities')->insert([
+        'uuid'         => 'entity-activity-1',
+        'public_id'    => 'entity_activityone',
+        'company_uuid' => 'company-1',
+        'payload_uuid' => 'payload-1',
+        'name'         => 'Crate',
+    ]);
+    $connection->table('tracking_numbers')->insert(['uuid' => 'tn-entity-1', 'company_uuid' => 'company-1', 'tracking_number' => 'TRK-E1', 'owner_uuid' => 'entity-activity-1']);
+    $connection->table('entities')->where('uuid', 'entity-activity-1')->update(['tracking_number_uuid' => 'tn-entity-1']);
+
+    (new OrderController())->updateActivity('order_start', Request::create('/x', 'POST', ['activity' => [
+        'key' => 'order_started', 'code' => 'started', 'status' => 'Started', 'details' => 'Order started',
+    ]]));
+
+    // The entity receives its own tracking status alongside the order
+    expect($connection->table('tracking_statuses')->where('tracking_number_uuid', 'tn-entity-1')->count())->toBeGreaterThanOrEqual(1);
+});