@fleetbase/fleetops-engine 0.6.70 → 0.6.71

package/server/src/Models/OrderConfig.php

@@ -380,6 +380,125 @@ class OrderConfig extends Model
         return $this->activities()->firstWhere('code', $code);
     }
 
+    /**
+     * Returns the configured lifecycle semantics stored under `meta.lifecycle`.
+     *
+     * A configured lifecycle is opt-in. When absent the default dispatch lifecycle
+     * (created -> dispatched -> ... -> completed / canceled) applies unchanged.
+     *
+     * Supported keys:
+     * - `initial` (string)            activity code new orders start at
+     * - `completed` (string)          activity code that completes an order
+     * - `canceled` (string)           activity code used when an order is canceled
+     * - `terminal` (string[])         activity codes after which no transition is allowed
+     * - `dispatch` (bool)             false disables dispatch for orders using this config
+     * - `strict_transitions` (bool)   true only allows moving to a configured child activity
+     */
+    public function lifecycle(): array
+    {
+        $lifecycle = data_get($this->meta, 'lifecycle');
+
+        return is_array($lifecycle) ? $lifecycle : [];
+    }
+
+    /**
+     * Determines if this config defines its own lifecycle semantics.
+     */
+    public function hasConfiguredLifecycle(): bool
+    {
+        return !empty($this->lifecycle());
+    }
+
+    /**
+     * Returns the activity new orders using this config start at.
+     *
+     * Without a configured lifecycle this is the `created` activity, if present in the flow.
+     */
+    public function getInitialActivity(): ?Activity
+    {
+        $initialCode = data_get($this->lifecycle(), 'initial');
+        if ($initialCode) {
+            return $this->getActivityByCode($initialCode);
+        }
+
+        return $this->getCreatedActivity();
+    }
+
+    /**
+     * Returns the status code new orders using this config start at.
+     */
+    public function getInitialStatusCode(): string
+    {
+        return data_get($this->lifecycle(), 'initial') ?: 'created';
+    }
+
+    /**
+     * Determines if orders using this config may be dispatched.
+     */
+    public function allowsDispatch(): bool
+    {
+        $dispatch = data_get($this->lifecycle(), 'dispatch', true);
+
+        return !in_array($dispatch, [false, 'false', 0, '0'], true);
+    }
+
+    /**
+     * Determines if activity updates must follow the configured flow graph.
+     */
+    public function hasStrictTransitions(): bool
+    {
+        return (bool) data_get($this->lifecycle(), 'strict_transitions', false);
+    }
+
+    /**
+     * Returns the terminal activity codes of this config.
+     */
+    public function getTerminalActivityCodes(): array
+    {
+        if (!$this->hasConfiguredLifecycle()) {
+            return ['completed', 'canceled'];
+        }
+
+        $terminal = data_get($this->lifecycle(), 'terminal', []);
+        $terminal = is_array($terminal) ? $terminal : [];
+        foreach (['completed', 'canceled'] as $semantic) {
+            $code = data_get($this->lifecycle(), $semantic);
+            if ($code) {
+                $terminal[] = $code;
+            }
+        }
+
+        return array_values(array_unique($terminal));
+    }
+
+    /**
+     * Determines if the given activity code is terminal for this config.
+     */
+    public function isTerminalActivityCode(?string $code): bool
+    {
+        return $code !== null && in_array($code, $this->getTerminalActivityCodes(), true);
+    }
+
+    /**
+     * Determines if the configured flow permits moving from one activity code to another.
+     *
+     * Only the configured graph is consulted: the target must be listed as a child of the
+     * source activity, and terminal activities permit no further transition.
+     */
+    public function canTransition(?string $fromCode, string $toCode): bool
+    {
+        if ($fromCode === null || $this->isTerminalActivityCode($fromCode)) {
+            return false;
+        }
+
+        $from = $this->getActivityByCode($fromCode);
+        if (!$from) {
+            return false;
+        }
+
+        return $from->children()->contains(fn ($activity) => $activity->code === $toCode);
+    }
+
     /**
      * Creates an Activity instance representing a canceled order.
      *
@@ -391,6 +510,11 @@ class OrderConfig extends Model
      */
     public function getCanceledActivity()
     {
+        $configuredCode = data_get($this->lifecycle(), 'canceled');
+        if ($configuredCode && ($configuredActivity = $this->getActivityByCode($configuredCode))) {
+            return $configuredActivity;
+        }
+
         $canceledActivity = $this->activities()->firstWhere('code', 'canceled');
         if ($canceledActivity) {
             return $canceledActivity;
@@ -416,6 +540,11 @@ class OrderConfig extends Model
      */
     public function getCompletedActivity()
     {
+        $configuredCode = data_get($this->lifecycle(), 'completed');
+        if ($configuredCode && ($configuredActivity = $this->getActivityByCode($configuredCode))) {
+            return $configuredActivity;
+        }
+
         $completedActivity = $this->activities()->firstWhere('code', 'completed');
         if ($completedActivity) {
             return $completedActivity;

package/server/src/Models/TrackingNumber.php

@@ -291,13 +291,17 @@ class TrackingNumber extends Model
 
         $ownerTypeName = class_basename($values['owner_type']);
 
+        // owners may define their own initial status (e.g. orders with a configured lifecycle)
+        $initialStatus = $owner && method_exists($owner, 'getInitialTrackingStatus') ? $owner->getInitialTrackingStatus() : null;
+        $initialCode   = is_array($initialStatus) && !empty($initialStatus['code']) ? $initialStatus['code'] : null;
+
         // create initial status
         $trackingStatusId = static::createInitialTrackingStatus([
             'tracking_number_uuid' => $uuid,
-            'status'               => Str::title($ownerTypeName . ' created'),
-            'details'              => 'New ' . Str::lower($ownerTypeName) . ' created.',
+            'status'               => $initialCode ? $initialStatus['status'] : Str::title($ownerTypeName . ' created'),
+            'details'              => $initialCode ? $initialStatus['details'] : 'New ' . Str::lower($ownerTypeName) . ' created.',
             'location'             => $values['location'] ?? Utils::parsePointToWkt(new Point(0, 0)),
-            'code'                 => 'CREATED',
+            'code'                 => $initialCode ? TrackingStatus::prepareCode($initialCode) : 'CREATED',
         ]);
 
         // update status of tracking number
@@ -309,7 +313,7 @@ class TrackingNumber extends Model
             // $model->update([ 'status' => 'created' ]);
 
             // silent update
-            static::updateOwnerStatusColumn($owner, 'created');
+            static::updateOwnerStatusColumn($owner, $initialCode ?? 'created');
         }
 
         return $uuid;

package/server/tests/Feature/Http/Internal/OrderControllerActivityFlowsTest.php

@@ -661,3 +661,75 @@ test('set destination and next activity guard missing orders and configs', funct
     $noConfig = $controller->nextActivity('order_internal', Request::create('/x', 'GET'));
     expect($noConfig->getData(true)['error'] ?? '')->toBe('No order config found for order.');
 });
+
+function fleetopsInternalActivityUseLifecycle(SQLiteConnection $connection, array $lifecycle = []): void
+{
+    $activity = fn (string $code, array $children = []) => ['key' => $code, 'code' => $code, 'status' => ucfirst($code), 'details' => ucfirst($code) . ' loan', 'activities' => $children, 'logic' => [], 'events' => [], 'complete' => $code === 'completed'];
+
+    $connection->table('order_configs')->where('uuid', 'config-1')->update([
+        'flow' => json_encode([
+            'requested' => $activity('requested', ['assigned', 'cancelled']),
+            'assigned'  => $activity('assigned', ['completed']),
+            'completed' => $activity('completed'),
+            'cancelled' => $activity('cancelled'),
+        ]),
+        'meta' => json_encode(['lifecycle' => array_replace([
+            'initial'            => 'requested',
+            'completed'          => 'completed',
+            'canceled'           => 'cancelled',
+            'dispatch'           => false,
+            'strict_transitions' => true,
+        ], $lifecycle)]),
+    ]);
+}
+
+test('strict transitions reject activities outside the configured flow and use the configured definition', function () {
+    $connection = fleetopsInternalActivityBoot();
+    $controller = new OrderController();
+
+    fleetopsInternalActivityUseLifecycle($connection);
+    fleetopsInternalActivitySeedOrder($connection, ['status' => 'requested']);
+
+    // Not a child of the current activity
+    $skipped = $controller->updateActivity('order_internal', Request::create('/x', 'POST', ['activity' => ['key' => 'completed', 'code' => 'completed', 'status' => 'Completed'], 'bypass_proof' => 1]));
+    expect($skipped->getStatusCode())->toBe(422)
+        ->and($skipped->getData(true)['error'])->toContain('not a permitted next step');
+
+    // Not in the flow at all
+    $unknown = $controller->updateActivity('order_internal', Request::create('/x', 'POST', ['activity' => ['key' => 'started', 'code' => 'started', 'status' => 'Started'], 'bypass_proof' => 1]));
+    expect($unknown->getStatusCode())->toBe(422);
+
+    // A configured child is accepted, with the server-side definition replacing the client's
+    $assigned = $controller->updateActivity('order_internal', Request::create('/x', 'POST', ['activity' => ['key' => 'assigned', 'code' => 'assigned', 'status' => 'Tampered'], 'bypass_proof' => 1]));
+    expect($assigned)->toBeInstanceOf(Fleetbase\FleetOps\Http\Resources\v1\Order::class)
+        ->and($connection->table('tracking_statuses')->where('code', 'ASSIGNED')->value('status'))->toBe('Assigned');
+});
+
+test('dispatch order refuses orders whose lifecycle disables dispatch', function () {
+    $connection = fleetopsInternalActivityBoot();
+    $controller = new OrderController();
+
+    fleetopsInternalActivityUseLifecycle($connection);
+    fleetopsInternalActivitySeedOrder($connection, ['status' => 'requested', 'driver_assigned_uuid' => 'driver-1']);
+
+    $response = $controller->dispatchOrder(Request::create('/x', 'POST', ['order' => 'order_internal']));
+    expect($response->getData(true)['error'] ?? '')->toContain('not dispatched')
+        ->and($connection->table('orders')->value('dispatched'))->toBe(0);
+});
+
+test('orders with a configured lifecycle start their tracking at the initial activity', function () {
+    $connection = fleetopsInternalActivityBoot();
+
+    // No config, or a config without a lifecycle, keeps the default created status
+    expect((new Fleetbase\FleetOps\Models\Order())->getInitialTrackingStatus())->toBeNull();
+    $order                    = new Fleetbase\FleetOps\Models\Order();
+    $order->order_config_uuid = 'config-1';
+    expect($order->getInitialTrackingStatus())->toBeNull();
+
+    fleetopsInternalActivityUseLifecycle($connection);
+    expect($order->getInitialTrackingStatus())->toBe(['code' => 'requested', 'status' => 'Requested', 'details' => 'Requested loan']);
+
+    // An initial activity missing from the flow falls back to the default
+    fleetopsInternalActivityUseLifecycle($connection, ['initial' => 'nowhere']);
+    expect($order->getInitialTrackingStatus())->toBeNull();
+});

package/server/tests/Feature/Http/Internal/OrderControllerCreateRecordTest.php

@@ -486,3 +486,29 @@ test('create record dispatches orders when the dispatch flag is not disabled', f
     expect($result)->toBeArray()->toHaveKey('order')
         ->and($connection->table('orders')->value('dispatched'))->not->toBeNull();
 });
+
+test('create record starts configured lifecycles at their initial activity and never dispatches them', function () {
+    $connection = fleetopsInternalOrderCreateBoot();
+    $connection->table('order_configs')->where('uuid', 'config-1')->update([
+        'flow' => json_encode([
+            'requested' => ['key' => 'requested', 'code' => 'requested', 'status' => 'Requested', 'details' => 'Loan requested', 'activities' => ['completed']],
+            'completed' => ['key' => 'completed', 'code' => 'completed', 'status' => 'Completed', 'details' => 'Loan completed', 'activities' => []],
+        ]),
+        'meta' => json_encode(['lifecycle' => ['initial' => 'requested', 'completed' => 'completed', 'dispatch' => false]]),
+    ]);
+
+    // Asks to be dispatched; the lifecycle overrides both the status and the dispatch flag
+    $result = (new OrderController())->createRecord(Request::create('/int/v1/orders', 'POST', [
+        'order' => [
+            'status'     => 'created',
+            'dispatched' => true,
+            'adhoc'      => true,
+            'payload'    => ['type' => 'transport'],
+        ],
+    ]));
+
+    expect($result)->toBeArray()->toHaveKey('order')
+        ->and($connection->table('orders')->value('status'))->toBe('requested')
+        ->and((bool) $connection->table('orders')->value('dispatched'))->toBeFalse()
+        ->and((bool) $connection->table('orders')->value('adhoc'))->toBeFalse();
+});

package/server/tests/OrderConfigLifecycleTest.php

@@ -0,0 +1,120 @@
+<?php
+
+use Fleetbase\FleetOps\Models\OrderConfig;
+
+/**
+ * Opt-in configured lifecycles (`meta.lifecycle`): a config can define its own initial, completed,
+ * canceled and terminal activities, disable dispatch and require configured transitions, without
+ * changing the default dispatch lifecycle of configs that do not opt in.
+ */
+function lifecycleActivity(string $code, array $children = [], bool $complete = false): array
+{
+    return ['key' => $code, 'code' => $code, 'status' => ucfirst(str_replace('_', ' ', $code)), 'details' => '', 'activities' => $children, 'logic' => [], 'events' => [], 'complete' => $complete];
+}
+
+function customLifecycleConfig(array $lifecycle = []): OrderConfig
+{
+    $config = new OrderConfig();
+    $config->setRawAttributes([
+        'flow' => json_encode([
+            'requested'   => lifecycleActivity('requested', ['assigned', 'cancelled']),
+            'assigned'    => lifecycleActivity('assigned', ['handed_over', 'cancelled']),
+            'handed_over' => lifecycleActivity('handed_over', ['active']),
+            'active'      => lifecycleActivity('active', ['extended', 'returned']),
+            'extended'    => lifecycleActivity('extended', ['active']),
+            'returned'    => lifecycleActivity('returned', ['completed']),
+            'completed'   => lifecycleActivity('completed', [], true),
+            'cancelled'   => lifecycleActivity('cancelled'),
+        ]),
+        'meta' => json_encode(['lifecycle' => array_replace([
+            'initial'            => 'requested',
+            'completed'          => 'completed',
+            'canceled'           => 'cancelled',
+            'terminal'           => ['completed', 'cancelled'],
+            'dispatch'           => false,
+            'strict_transitions' => true,
+        ], $lifecycle)]),
+    ]);
+
+    return $config;
+}
+
+function defaultLifecycleConfig(): OrderConfig
+{
+    $config = new OrderConfig();
+    $config->setRawAttributes([
+        'flow' => json_encode([
+            'created'    => lifecycleActivity('created', ['dispatched']),
+            'dispatched' => lifecycleActivity('dispatched', ['started']),
+            'started'    => lifecycleActivity('started', ['completed']),
+            'completed'  => lifecycleActivity('completed', [], true),
+        ]),
+        'meta' => json_encode([]),
+    ]);
+
+    return $config;
+}
+
+test('configs without meta.lifecycle keep the default dispatch semantics', function () {
+    $config = defaultLifecycleConfig();
+
+    expect($config->hasConfiguredLifecycle())->toBeFalse()
+        ->and($config->getInitialStatusCode())->toBe('created')
+        ->and($config->allowsDispatch())->toBeTrue()
+        ->and($config->hasStrictTransitions())->toBeFalse()
+        ->and($config->getTerminalActivityCodes())->toBe(['completed', 'canceled'])
+        ->and($config->getCanceledActivity()->code)->toBe('canceled')
+        ->and($config->getInitialActivity()->code)->toBe('created');
+});
+
+test('a configured lifecycle names its own initial, cancel and completion activities', function () {
+    $config = customLifecycleConfig();
+
+    expect($config->hasConfiguredLifecycle())->toBeTrue()
+        ->and($config->getInitialStatusCode())->toBe('requested')
+        ->and($config->getInitialActivity()->code)->toBe('requested')
+        ->and($config->getCanceledActivity()->code)->toBe('cancelled')
+        ->and($config->getCompletedActivity()->code)->toBe('completed')
+        ->and($config->allowsDispatch())->toBeFalse()
+        ->and($config->hasStrictTransitions())->toBeTrue()
+        ->and($config->isTerminalActivityCode('cancelled'))->toBeTrue()
+        ->and($config->isTerminalActivityCode('canceled'))->toBeFalse();
+});
+
+test('transitions follow only the configured graph', function () {
+    $config = customLifecycleConfig();
+
+    expect($config->canTransition('requested', 'assigned'))->toBeTrue()
+        ->and($config->canTransition('handed_over', 'active'))->toBeTrue()
+        ->and($config->canTransition('active', 'extended'))->toBeTrue()
+        ->and($config->canTransition('extended', 'active'))->toBeTrue()
+        ->and($config->canTransition('returned', 'completed'))->toBeTrue()
+        // skipped or foreign steps
+        ->and($config->canTransition('requested', 'handed_over'))->toBeFalse()
+        ->and($config->canTransition('requested', 'dispatched'))->toBeFalse()
+        ->and($config->canTransition('active', 'cancelled'))->toBeFalse()
+        // terminal and unknown sources
+        ->and($config->canTransition('completed', 'requested'))->toBeFalse()
+        ->and($config->canTransition('cancelled', 'assigned'))->toBeFalse()
+        ->and($config->canTransition(null, 'requested'))->toBeFalse()
+        ->and($config->canTransition('nope', 'assigned'))->toBeFalse();
+});
+
+test('a configuration-only change (added activity) is honoured without code changes', function () {
+    $config = customLifecycleConfig();
+    $flow   = json_decode($config->getAttributes()['flow'], true);
+    $flow['active']['activities'][] = 'inspection';
+    $flow['inspection']             = lifecycleActivity('inspection', ['returned']);
+    $config->setRawAttributes(['flow' => json_encode($flow), 'meta' => $config->getAttributes()['meta']]);
+
+    expect($config->canTransition('active', 'inspection'))->toBeTrue()
+        ->and($config->canTransition('inspection', 'returned'))->toBeTrue()
+        ->and($config->canTransition('inspection', 'completed'))->toBeFalse();
+});
+
+test('dispatch can be disabled with string or numeric falsy values', function () {
+    foreach ([false, 'false', 0, '0'] as $value) {
+        expect(customLifecycleConfig(['dispatch' => $value])->allowsDispatch())->toBeFalse();
+    }
+    expect(customLifecycleConfig(['dispatch' => true])->allowsDispatch())->toBeTrue();
+});

package/server/tests/Unit/Events/OrderDispatchFailedTest.php

@@ -6,7 +6,8 @@ use Illuminate\Support\Str;
 
 class FleetOpsOrderDispatchFailedUnitProbe extends OrderDispatchFailed
 {
-    public function getEventData(): array
+    // core-api 1.6.68 adds an optional $channel parameter; the literal keeps this probe loadable on earlier versions too.
+    public function getEventData(string $channel = 'webhook'): array
     {
         return [];
     }

package/translations/en-us.yaml

@@ -1256,6 +1256,7 @@ order-config-manager:
         details: Details
         custom-fields: Custom Fields
         activity-flow: Activity Flow
+        lifecycle: Lifecycle
         entities: Entities
     details:
         details: Details
@@ -1272,6 +1273,65 @@ order-config-manager:
             delete-title: Delete this order config?
             delete-body-message: Once this order config is deleted it will not be recoverable and you will lose all configurations.
             confirm-delete: Delete
+    lifecycle:
+        title: Lifecycle
+        description: A configured lifecycle lets this order type start, complete and cancel at its own activities instead of the default dispatch lifecycle (created, dispatched, started, completed, canceled).
+        default-lifecycle: This order type uses the default dispatch lifecycle. Orders start at "created", can be dispatched to drivers and complete or cancel through the standard activities.
+        enable: Use a configured lifecycle
+        enable-help: Orders of this type start at the initial activity you choose and follow the activity flow instead of the dispatch lifecycle.
+        initial: Initial activity
+        initial-help: New orders of this type start here. Must be an activity in the flow.
+        completed: Completed activity
+        completed-help: Reaching this activity completes the order.
+        canceled: Canceled activity
+        canceled-help: Canceling an order moves it to this activity.
+        terminal: Terminal activities
+        terminal-help: No further transition is allowed after these. The completed and canceled activities are always terminal.
+        dispatch: Allow dispatch
+        dispatch-help: When off, orders of this type are never dispatched to drivers and the dispatch actions are refused.
+        strict-transitions: Strict transitions
+        strict-transitions-help: When on, an activity can only move to one of its configured next activities in the flow.
+        select-activity: Select activity
+        select-activities: Select activities
+        problems-title: Fix before saving
+        problem-initial-required: Choose the initial activity.
+        problem-no-activities: Add at least one activity.
+        problem-duplicate-code: 'An activity with the code "{code}" already exists.'
+        activities: Activities
+        activities-help: The statuses an order of this type can be in. Each activity lists the activities it can move to; the graph on the Activity Flow tab shows the same flow. Changes here are saved with the lifecycle.
+        activity-label: Label
+        activity-label-placeholder: e.g. Vehicle Assigned
+        activity-code: Code
+        activity-code-help: Stored status value. Derived from the label when left empty; cannot change once added.
+        activity-code-placeholder: e.g. vehicle_assigned
+        activity-details: Details
+        activity-details-placeholder: Shown with the activity in the timeline
+        activity-color: Colour
+        activity-next: Can move to
+        add-activity: Add activity
+        remove-activity: Remove activity
+        no-activities: No activities yet. Add the first one below; it becomes the initial activity.
+        blank-flow: Start from a blank flow
+        blank-flow-title: Remove all activities?
+        blank-flow-body: The default dispatch activities (created, dispatched, started, …) are removed so you can define your own. Nothing is saved until you click Save changes.
+        blank-flow-confirm: Remove activities
+        initial-short: initial
+        problem-missing-activity: '"{code}" is not an activity in the flow.'
+        summary: Summary
+        summary-initial: Orders start at
+        summary-completed: Completed at
+        summary-canceled: Canceled at
+        summary-terminal: Terminal
+        summary-dispatch: Dispatch
+        summary-strict: Strict transitions
+        'yes': 'Yes'
+        'no': 'No'
+        none: None
+        remove: Remove configured lifecycle
+        remove-title: Remove the configured lifecycle?
+        remove-body: Orders of this type will use the default dispatch lifecycle again. Existing orders keep their current status.
+        remove-confirm: Remove
+        saved: Lifecycle saved for {orderConfigName}.
     activity-flow:
         save-activity-flow: Save Activity Flow
         edit-activity-unique-code-warning: Activity code must be unique!