@fleetbase/fleetops-engine 0.6.64 → 0.6.66

package/docs/TELEMETRY_ARCHITECTURE.md

@@ -0,0 +1,115 @@
+# Provider-neutral telemetry infrastructure
+
+## Context and correction
+
+Fleet-Ops consumes third-party telematics through `TelematicProviderRegistry`,
+`TelematicProviderDescriptor`, and `TelematicProviderInterface`. Provider identity
+belongs at registration and adapter boundaries. Commit 9f561352 incorrectly
+extended AFAQY identity into shared resource components, map processing, and
+persistence. The performance requirement did not justify those dependencies.
+
+## Boundaries
+
+- Keep the existing provider interface compatible. Add an optional telemetry
+  interface for adapters opting into durable position ingestion and reconciliation.
+- Adapters interpret external identities, payload envelopes, timestamps, sensors,
+  authentication, rate limits, and reporting configuration. They return normalized
+  device/event/sensor samples. Shared workers never inspect vendor payload fields.
+- Use shared `telematic_sync_runs`, `telematic_deliveries`, and
+  `telematic_webhook_credentials` tables, scoped by `telematic_uuid`; the existing
+  connection identifies the provider and company. Do not create per-provider tables.
+- Shared services implement durable receipt, retries, replay, retention, ordering,
+  and diagnostics. Resolve adapters through the existing registry. Existing
+  providers retain their existing path until they implement the optional interface.
+- Declare UI capabilities in the existing provider descriptor. Shared connection
+  components render a reusable telemetry panel only when that capability is present.
+  Registration instructions and provider names are descriptor data, not template
+  branches. A registry of provider-specific components is unnecessary for the
+  currently identical diagnostics and registration UI.
+- Devices expose a normalized `meta.telemetry` snapshot. Maps consume a normalized
+  source timestamp from location events; neither knows which adapter produced it.
+- Keep provider configuration and public webhook URLs compatible. The original
+  migration has not been deployed or applied, as confirmed by the maintainer.
+  Replace it directly with the generic migration; no compatibility tables, rename
+  migration, or old job aliases are required. Existing pre-feature device metadata
+  remains readable through its established position timestamp fallback.
+
+## Review checks
+
+1. No provider-name branches in shared frontend components or movement tracking.
+2. Shared workers and ingestion accept a second registered adapter without edits.
+3. Unsupported providers expose no new telemetry UI or receiver capabilities.
+4. Storage, secret lookup, replay, and broadcasts remain connection/tenant scoped.
+5. Fresh installs create only generic infrastructure tables; rollback preserves
+   core device and integration tables.
+6. Polling/push deduplication, UTC timing, partial updates, ordering, and recovery
+   remain covered independently of the AFAQY adapter contract tests.
+
+## Tradeoffs
+
+Three shared tables separate run-level diagnostics, high-volume delivery retention,
+and connection-level secrets with different lifetimes. Provider-specific protocol
+classes remain appropriate. Capability opt-in avoids silently changing every
+existing integration's ingestion or webhook behavior. Production throughput and
+real AFAQY payload verification remain separate deployment gates.
+
+## Adding an adapter
+
+Implement `TelemetryProviderInterface` alongside the existing provider contract.
+`telemetryUnits()` recognizes the adapter's inbound envelope; it must also accept
+arrays of its raw samples for queued poll batches and failed-item retries.
+`normalizeTelemetrySnapshot()` returns `device`, `event`, and `sensors` using the
+existing normalization fields. `event.occurred_at` is device time,
+`event.last_seen_at` is provider contact time, and
+`event.meta.telemetry.provider_at` preserves the provider timestamp. No adapter
+normalization method may authenticate or perform network I/O.
+
+Register the driver with `TelematicProviderRegistry`, and declare
+`metadata.telemetry.durable_ingestion`, `secure_webhooks`, and `reconciliation`
+as appropriate. Optional `registration_instructions` and `contract_status`
+control explanatory UI copy. `telemetryOptions()` supplies adapter overrides for
+the shared `telematics.telemetry` configuration. Enabling an adapter does not
+require new tables, jobs, frontend components, or map branches.
+
+The example adapter in the database tests uses `tracker`, `measured`, `received`,
+and `point` fields and a `signals` envelope. It exercises shared poll and webhook
+processing, connection-scoped authentication, deduplication, and independent
+freshness settings without inheriting the AFAQY adapter.
+
+
+## Review and validation — 2026-09-16
+
+The refactor was checked against the boundaries above, then exercised through a
+second adapter. That feedback exposed numeric-cursor assumptions in the polling
+worker, provider registration failures interrupting shared inbox maintenance, and
+UI monitoring failing to start when capabilities arrived after the initial render.
+The shared paths now handle opaque cursors, isolate unavailable registrations
+while continuing recovery/retention, and restart monitoring on capability changes.
+
+Selected backend checks cover existing provider contracts and lifecycle behavior,
+database ingestion, poll/push deduplication, reversed delivery order, partial
+sensor values, tenant scoping, recovery, and migration up/down. The second adapter
+uses the same jobs, storage, receiver, and ingestion service without AFAQY
+inheritance or authentication during normalization. Source checks find no AFAQY
+identity in shared frontend components, map processing, telemetry workers,
+telemetry controllers, or the shared ingestion service.
+
+The location broadcast's additive `position_at` field is now asserted for a legacy
+provider too. It allows every adapter's map updates to use source time. The
+existing provider interface and legacy ingestion path remain available.
+
+Current functional checks: 105 selected backend tests pass; PHP syntax, ESLint,
+and template lint pass. The test-environment build succeeds. Five focused browser
+cases pass all 19 assertions against that build. Browser cases ran in fresh Chrome
+pages because the linked dummy host cannot recreate its universe registry across
+rendering tests; the standard launcher also has a Testem/execa module mismatch.
+These results do not establish a clean full browser suite or production socket
+latency.
+
+The opt-in local SQLite load gate remains open. The refactored path processed
+5,000 signals plus 5,000 duplicate reconciliation observations in 66.5 seconds,
+above its 60-second assertion. An earlier concurrent-build run took 109.2 seconds;
+the original commit, loaded from a temporary checkout with the same dependencies,
+took 83.4 seconds. Varying machine/build load prevents treating these runs as a
+controlled speed comparison. Each run retained exactly 5,000 events. Do not claim
+production throughput or the polling/webhook latency targets from these results.

package/extension.json

@@ -1,6 +1,6 @@
 {
     "name": "Fleet-Ops",
-    "version": "0.6.64",
+    "version": "0.6.66",
     "description": "Fleet & Transport Management Extension for Fleetbase",
     "repository": "https://github.com/fleetbase/fleetops",
     "license": "AGPL-3.0-or-later",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@fleetbase/fleetops-engine",
-    "version": "0.6.64",
+    "version": "0.6.66",
     "description": "Fleet & Transport Management Extension for Fleetbase",
     "fleetbase": {
         "route": "fleet-ops"
@@ -45,8 +45,8 @@
     "dependencies": {
         "@babel/core": "^7.23.2",
         "@fleetbase/ember-core": "^0.3.24",
-        "@fleetbase/ember-ui": "^0.3.41",
-        "@fleetbase/fleetops-data": "^0.1.40",
+        "@fleetbase/ember-ui": "^0.4.1",
+        "@fleetbase/fleetops-data": "^0.2.1",
         "@fleetbase/leaflet-routing-machine": "^3.2.17",
         "@fortawesome/ember-fontawesome": "^2.0.0",
         "@fortawesome/fontawesome-svg-core": "6.4.0",

package/scripts/coverage-summary.php

@@ -84,6 +84,13 @@ foreach ($project->xpath('.//file') ?: [] as $file) {
         continue;
     }
 
+    $uncoveredLines = [];
+    foreach ($file->line as $line) {
+        if ((string) $line['type'] === 'stmt' && (int) $line['count'] === 0) {
+            $uncoveredLines[] = (int) $line['num'];
+        }
+    }
+
     $files[] = [
         'path'            => $path,
         'covered'         => $coveredFileLines,
@@ -91,6 +98,7 @@ foreach ($project->xpath('.//file') ?: [] as $file) {
         'methods'         => $fileMethods,
         'covered_methods' => $coveredFileMethod,
         'percent'         => coveragePercent($coveredFileLines, $fileStatements),
+        'uncovered_lines' => $uncoveredLines,
     ];
 
     $relativePath = preg_replace('#^' . preg_quote(getcwd(), '#') . '/?#', '', $path);
@@ -141,6 +149,9 @@ echo "\nLowest covered files:\n";
 foreach (array_slice($files, 0, 20) as $file) {
     $relativePath = preg_replace('#^' . preg_quote(getcwd(), '#') . '/?#', '', $file['path']);
     printf("  %6.2f%%  %5d/%-5d  %s\n", $file['percent'], $file['covered'], $file['statements'], $relativePath ?: $file['path']);
+    if ($file['uncovered_lines']) {
+        printf("            Uncovered lines: %s\n", implode(', ', $file['uncovered_lines']));
+    }
 }
 
 if ($failUnder !== null && coveragePercent($coveredStatements, $statements) < $failUnder) {

package/scripts/pest-bootstrap.php

@@ -328,7 +328,7 @@ if (!class_exists('Fleetbase\TestSupport\PendingDispatch')) {
 }
 
 if (!class_exists('Fleetbase\TestSupport\DispatchRecorder')) {
-    eval('namespace Fleetbase\TestSupport; class DispatchRecorder { public static array $dispatched = []; public static function record(string $job, array $arguments): void { self::$dispatched[] = [\'job\' => $job, \'arguments\' => $arguments]; } }');
+    eval('namespace Fleetbase\TestSupport; class DispatchRecorder { public static array $dispatched = []; public static ?\Throwable $failure = null; public static function record(string $job, array $arguments): void { if (self::$failure) { throw self::$failure; } self::$dispatched[] = [\'job\' => $job, \'arguments\' => $arguments]; } }');
 }
 
 if (!trait_exists('Illuminate\Foundation\Bus\Dispatchable')) {

package/server/config/afaqy.php

@@ -0,0 +1,8 @@
+<?php
+
+return [
+    'polling_enabled'           => env('AFAQY_POLLING_ENABLED', false),
+    'webhooks_enabled'          => env('AFAQY_WEBHOOKS_ENABLED', false),
+    'poll_queue'                => env('AFAQY_POLL_QUEUE', env('TELEMATICS_POLL_QUEUE', 'default')),
+    'ingestion_queue'           => env('AFAQY_INGESTION_QUEUE', env('TELEMATICS_INGESTION_QUEUE', 'default')),
+];

package/server/config/fuel-providers.php

@@ -14,11 +14,30 @@ return [
             'required_fields' => [
                 [
                     'name' => 'api_token',
-                    'label' => 'API Token',
+                    'label' => 'Integration Token (WS-SK) or API Token',
                     'type' => 'password',
-                    'help_text' => 'Bearer API token from PetroApp.',
+                    'help_text' => 'Use the test token for Sandbox, or your company token for Production. Select the matching authentication method.',
                     'required' => true,
                 ],
+                [
+                    'name' => 'auth_type',
+                    'label' => 'Authentication method',
+                    'type' => 'select',
+                    'default' => 'ws_sk_header',
+                    'options' => [
+                        ['value' => 'ws_sk_header', 'label' => 'Integration Token (WS-SK)'],
+                        ['value' => 'bearer_token', 'label' => 'Bearer API Token'],
+                    ],
+                    'help_text' => 'Choose WS-SK for an integration token, or Bearer for a token returned by get_apiKey.',
+                    'required' => false,
+                ],
+                [
+                    'name' => 'base_url',
+                    'label' => 'Base URL override (optional)',
+                    'type' => 'url',
+                    'help_text' => 'Leave blank to use the selected environment. A custom URL overrides the environment selection.',
+                    'required' => false,
+                ],
             ],
             'capabilities' => ['vehicles', 'transactions', 'stations', 'trips'],
             'sync_defaults' => [
@@ -27,13 +46,15 @@ return [
                 'auto_create_fuel_reports' => true,
             ],
             'setup_instructions' => [
-                'Create or request a PetroApp API token.',
-                'Enter the token, then run Test Connection.',
-                'Run a date-window sync to import bills into Fuel Transactions.',
+                'Select Sandbox for PetroApp staging and enter the test integration token using WS-SK authentication.',
+                'Run Test Connection, then sync a small date window to verify imported bills and vehicle matches.',
+                'For Production, use your company integration token from the PetroApp API token profile page.',
+                'Alternatively, exchange company username and password at get_apiKey and use the returned Bearer API token.',
             ],
             'metadata' => [
-                'auth_type' => 'bearer_token',
-                'legacy_auth_type' => 'ws_sk_header',
+                'auth_type' => 'ws_sk_header',
+                'supported_auth_types' => ['ws_sk_header', 'bearer_token'],
+                'base_urls' => \Fleetbase\FleetOps\Support\FuelProviders\Providers\PetroAppFuelProvider::BASE_URLS,
                 'pagination' => 'page',
                 'default_currency' => 'SAR',
             ],

package/server/config/telematics.php

@@ -153,9 +153,16 @@ return [
                     'validation'  => 'required_without:username|string',
                 ],
             ],
-            'supports_webhooks'  => false,
+            'supports_webhooks'  => true,
             'supports_discovery' => true,
             'metadata'           => [
+                'telemetry' => [
+                    'durable_ingestion'         => true,
+                    'secure_webhooks'           => true,
+                    'reconciliation'            => true,
+                    'registration_instructions' => 'Provide the secure URL to AFAQY to register Device Signals / Positions. Polling continues after registration.',
+                    'contract_status'           => 'provisional',
+                ],
                 'rate_limit'   => 60,
                 'pagination'   => 'offset',
                 'capabilities' => ['tracking', 'speed', 'heading', 'odometer', 'fuel_level', 'ignition'],

package/server/config/telemetry.php

@@ -0,0 +1,17 @@
+<?php
+
+return [
+    'polling_enabled'           => false,
+    'webhooks_enabled'          => false,
+    'poll_queue'                => env('TELEMATICS_POLL_QUEUE', 'default'),
+    'ingestion_queue'           => env('TELEMATICS_INGESTION_QUEUE', 'default'),
+    'page_size'                 => 1000,
+    'max_pages'                 => 100,
+    'batch_size'                => 100,
+    'max_payload_bytes'         => 2097152,
+    'max_pending_deliveries'    => 10000,
+    'processed_retention_hours' => 24,
+    'quarantine_retention_days' => 7,
+    'stale_engine_on_seconds'   => 120,
+    'stale_engine_off_seconds'  => 600,
+];

package/server/migrations/2026_09_03_000001_add_first_class_trailer_columns_to_assets_table.php

@@ -0,0 +1,58 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    public function up(): void
+    {
+        Schema::table('assets', function (Blueprint $table) {
+            // Existing Asset rows predate public identifiers. Keep this nullable so
+            // Trailer support does not rewrite unrelated historical Asset data.
+            $table->string('public_id')->nullable()->after('uuid')->unique();
+            $table->string('asset_class')->nullable()->after('type')->index();
+            $table->foreignUuid('photo_uuid')->nullable()->after('current_place_uuid')->constrained('files', 'uuid')->nullOnDelete();
+            $table->boolean('online')->nullable()->after('altitude')->index();
+            $table->timestamp('last_online_at')->nullable()->after('online')->index();
+            $table->json('telematics')->nullable()->after('attributes');
+            $table->date('purchased_at')->nullable()->after('lease_expires_at');
+            $table->decimal('length', 12, 3)->nullable();
+            $table->decimal('width', 12, 3)->nullable();
+            $table->decimal('height', 12, 3)->nullable();
+            $table->decimal('tare_weight', 12, 3)->nullable();
+            $table->decimal('gvwr', 12, 3)->nullable();
+            $table->decimal('payload_capacity', 12, 3)->nullable();
+            $table->decimal('cargo_volume', 12, 3)->nullable();
+            $table->unsignedSmallInteger('axle_count')->nullable();
+            $table->unsignedSmallInteger('tire_count')->nullable();
+            $table->unsignedSmallInteger('door_count')->nullable();
+            $table->string('body_type')->nullable()->index();
+            $table->string('coupling_type')->nullable();
+            $table->string('brake_type')->nullable();
+            $table->boolean('abs_equipped')->nullable();
+            $table->boolean('ebs_equipped')->nullable();
+            $table->boolean('refrigerated')->nullable()->index();
+            $table->decimal('temperature_min', 8, 3)->nullable();
+            $table->decimal('temperature_max', 8, 3)->nullable();
+            $table->decimal('reefer_engine_hours', 14, 2)->nullable();
+            $table->index(['company_uuid', 'asset_class', 'status'], 'assets_company_class_status_index');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('assets', function (Blueprint $table) {
+            $table->dropIndex('assets_company_class_status_index');
+            $table->dropForeign(['photo_uuid']);
+            $table->dropUnique(['public_id']);
+            $table->dropColumn([
+                'public_id', 'asset_class', 'photo_uuid', 'online', 'last_online_at', 'telematics', 'purchased_at',
+                'length', 'width', 'height', 'tare_weight', 'gvwr', 'payload_capacity', 'cargo_volume',
+                'axle_count', 'tire_count', 'door_count', 'body_type', 'coupling_type', 'brake_type',
+                'abs_equipped', 'ebs_equipped', 'refrigerated', 'temperature_min', 'temperature_max',
+                'reefer_engine_hours',
+            ]);
+        });
+    }
+};

package/server/migrations/2026_09_03_000002_create_asset_connections_table.php

@@ -0,0 +1,43 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    public function up(): void
+    {
+        Schema::create('asset_connections', function (Blueprint $table) {
+            $table->bigIncrements('id');
+            $table->uuid('uuid')->unique();
+            $table->string('public_id')->unique();
+            $table->foreignUuid('company_uuid')->constrained('companies', 'uuid')->cascadeOnDelete();
+            $table->string('connector_type');
+            $table->uuid('connector_uuid');
+            $table->string('connected_type');
+            $table->uuid('connected_uuid');
+            $table->uuid('active_connected_uuid')->nullable()->unique();
+            $table->string('active_connector_position')->nullable()->unique();
+            $table->string('relationship_type')->default('towing');
+            $table->unsignedSmallInteger('position')->default(1);
+            $table->timestamp('connected_at');
+            $table->timestamp('disconnected_at')->nullable();
+            $table->string('source')->default('manual');
+            $table->string('confidence')->nullable();
+            $table->text('notes')->nullable();
+            $table->json('meta')->nullable();
+            $table->foreignUuid('created_by_uuid')->nullable()->constrained('users', 'uuid')->nullOnDelete();
+            $table->foreignUuid('updated_by_uuid')->nullable()->constrained('users', 'uuid')->nullOnDelete();
+            $table->timestamps();
+            $table->softDeletes();
+            $table->index(['company_uuid', 'connector_type', 'connector_uuid'], 'asset_connections_connector_index');
+            $table->index(['company_uuid', 'connected_type', 'connected_uuid'], 'asset_connections_connected_index');
+            $table->index(['company_uuid', 'disconnected_at'], 'asset_connections_active_index');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('asset_connections');
+    }
+};

package/server/migrations/2026_09_03_000003_create_device_installations_table.php

@@ -0,0 +1,33 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    public function up(): void
+    {
+        Schema::create('device_installations', function (Blueprint $table) {
+            $table->bigIncrements('id');
+            $table->uuid('uuid')->unique();
+            $table->foreignUuid('company_uuid')->constrained('companies', 'uuid')->cascadeOnDelete();
+            $table->foreignUuid('device_uuid')->constrained('devices', 'uuid')->cascadeOnDelete();
+            $table->string('attachable_type');
+            $table->uuid('attachable_uuid');
+            $table->uuid('active_device_uuid')->nullable()->unique();
+            $table->timestamp('installed_at');
+            $table->timestamp('removed_at')->nullable();
+            $table->string('source')->default('manual');
+            $table->json('metadata')->nullable();
+            $table->softDeletes();
+            $table->timestamps();
+            $table->index(['company_uuid', 'attachable_type', 'attachable_uuid'], 'device_installations_attachable_index');
+            $table->index(['device_uuid', 'installed_at'], 'device_installations_history_index');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('device_installations');
+    }
+};

package/server/migrations/2026_09_09_000001_create_inspection_tables.php

@@ -0,0 +1,152 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('inspection_forms', function (Blueprint $table) {
+            $table->increments('id');
+            $table->uuid('uuid')->index();
+            $table->string('_key')->nullable()->index();
+            $table->string('public_id', 191)->nullable()->unique()->index();
+            $table->foreignUuid('company_uuid')->constrained('companies', 'uuid')->cascadeOnDelete();
+
+            $table->string('name')->index();
+            $table->text('description')->nullable();
+            $table->string('type')->default('dvir')->index();
+            $table->string('status')->default('draft')->index();
+            $table->string('frequency')->nullable()->index();
+
+            $table->string('subject_type')->nullable();
+            $table->uuid('subject_uuid')->nullable();
+            $table->index(['subject_type', 'subject_uuid']);
+
+            $table->json('items')->nullable();
+            $table->json('settings')->nullable();
+            $table->json('meta')->nullable();
+            $table->timestamp('published_at')->nullable()->index();
+
+            $table->foreignUuid('created_by_uuid')->nullable()->constrained('users', 'uuid')->nullOnDelete();
+            $table->foreignUuid('updated_by_uuid')->nullable()->constrained('users', 'uuid')->nullOnDelete();
+
+            $table->softDeletes();
+            $table->timestamps();
+
+            $table->index(['company_uuid', 'status', 'type']);
+        });
+
+        Schema::create('inspection_links', function (Blueprint $table) {
+            $table->increments('id');
+            $table->uuid('uuid')->index();
+            $table->string('_key')->nullable()->index();
+            $table->string('public_id', 191)->nullable()->unique()->index();
+            $table->foreignUuid('company_uuid')->constrained('companies', 'uuid')->cascadeOnDelete();
+            $table->foreignUuid('inspection_form_uuid')->constrained('inspection_forms', 'uuid')->cascadeOnDelete();
+            $table->foreignUuid('driver_uuid')->nullable()->constrained('drivers', 'uuid')->nullOnDelete();
+            $table->foreignUuid('vehicle_uuid')->nullable()->constrained('vehicles', 'uuid')->nullOnDelete();
+            $table->foreignUuid('created_by_uuid')->nullable()->constrained('users', 'uuid')->nullOnDelete();
+
+            $table->string('token_hash', 191)->unique();
+            $table->string('status')->default('active')->index();
+            $table->boolean('single_use')->default(true)->index();
+            $table->timestamp('expires_at')->nullable()->index();
+            $table->timestamp('last_viewed_at')->nullable();
+            $table->timestamp('used_at')->nullable()->index();
+            $table->string('used_ip')->nullable();
+            $table->text('used_user_agent')->nullable();
+            $table->json('meta')->nullable();
+
+            $table->softDeletes();
+            $table->timestamps();
+
+            $table->index(['company_uuid', 'inspection_form_uuid', 'status']);
+        });
+
+        Schema::create('inspection_submissions', function (Blueprint $table) {
+            $table->increments('id');
+            $table->uuid('uuid')->index();
+            $table->string('_key')->nullable()->index();
+            $table->string('public_id', 191)->nullable()->unique()->index();
+            $table->foreignUuid('company_uuid')->constrained('companies', 'uuid')->cascadeOnDelete();
+            $table->foreignUuid('inspection_form_uuid')->nullable()->constrained('inspection_forms', 'uuid')->nullOnDelete();
+            $table->foreignUuid('vehicle_uuid')->nullable()->constrained('vehicles', 'uuid')->nullOnDelete();
+            $table->foreignUuid('driver_uuid')->nullable()->constrained('drivers', 'uuid')->nullOnDelete();
+            $table->foreignUuid('submitted_by_uuid')->nullable()->constrained('users', 'uuid')->nullOnDelete();
+            $table->foreignUuid('issue_uuid')->nullable()->constrained('issues', 'uuid')->nullOnDelete();
+            $table->foreignUuid('work_order_uuid')->nullable()->constrained('work_orders', 'uuid')->nullOnDelete();
+
+            $table->string('type')->default('dvir')->index();
+            $table->string('status')->default('draft')->index();
+            $table->string('result')->nullable()->index();
+            $table->string('source')->nullable()->index();
+            $table->unsignedBigInteger('odometer')->nullable();
+            $table->unsignedBigInteger('engine_hours')->nullable();
+            $table->unsignedInteger('total_items')->default(0);
+            $table->unsignedInteger('failed_items')->default(0);
+            $table->timestamp('started_at')->nullable()->index();
+            $table->timestamp('submitted_at')->nullable()->index();
+            $table->timestamp('resolved_at')->nullable()->index();
+
+            $table->json('location')->nullable();
+            $table->json('signature')->nullable();
+            $table->json('attachments')->nullable();
+            $table->json('meta')->nullable();
+
+            $table->foreignUuid('created_by_uuid')->nullable()->constrained('users', 'uuid')->nullOnDelete();
+            $table->foreignUuid('updated_by_uuid')->nullable()->constrained('users', 'uuid')->nullOnDelete();
+
+            $table->softDeletes();
+            $table->timestamps();
+
+            $table->index(['company_uuid', 'status', 'result']);
+            $table->index(['vehicle_uuid', 'submitted_at']);
+        });
+
+        Schema::create('inspection_item_results', function (Blueprint $table) {
+            $table->increments('id');
+            $table->uuid('uuid')->index();
+            $table->string('_key')->nullable()->index();
+            $table->foreignUuid('company_uuid')->constrained('companies', 'uuid')->cascadeOnDelete();
+            $table->foreignUuid('inspection_submission_uuid')->constrained('inspection_submissions', 'uuid')->cascadeOnDelete();
+            $table->foreignUuid('issue_uuid')->nullable()->constrained('issues', 'uuid')->nullOnDelete();
+            $table->foreignUuid('work_order_uuid')->nullable()->constrained('work_orders', 'uuid')->nullOnDelete();
+
+            $table->string('item_key')->nullable()->index();
+            $table->string('label')->index();
+            $table->string('category')->nullable()->index();
+            $table->string('status')->default('passed')->index();
+            $table->string('severity')->nullable()->index();
+            $table->boolean('passed')->default(true)->index();
+            $table->text('comments')->nullable();
+            $table->json('photos')->nullable();
+            $table->json('meta')->nullable();
+
+            $table->foreignUuid('created_by_uuid')->nullable()->constrained('users', 'uuid')->nullOnDelete();
+            $table->foreignUuid('updated_by_uuid')->nullable()->constrained('users', 'uuid')->nullOnDelete();
+
+            $table->softDeletes();
+            $table->timestamps();
+
+            $table->index(['company_uuid', 'passed', 'severity']);
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::disableForeignKeyConstraints();
+        Schema::dropIfExists('inspection_item_results');
+        Schema::dropIfExists('inspection_submissions');
+        Schema::dropIfExists('inspection_links');
+        Schema::dropIfExists('inspection_forms');
+        Schema::enableForeignKeyConstraints();
+    }
+};

package/server/migrations/2026_09_10_000001_convert_inspection_form_items_to_field_groups.php

@@ -0,0 +1,44 @@
+<?php
+
+use Fleetbase\FleetOps\Models\InspectionForm;
+use Fleetbase\FleetOps\Support\InspectionFormSync;
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Folds the first cut's `items` checklist into the second cut's structure.
+ *
+ * A form used to be a JSON list of pass/fail items; it is now groups of typed
+ * fields. Rather than ask an operator to rebuild every form by hand, each
+ * legacy checklist becomes a "Checklist" group of `pass-fail` fields carrying
+ * the same labels and severities. `items` is left in place, read-only, for one
+ * release, so a console or app that has not been updated still renders.
+ *
+ * Idempotent: a form that already has fields is skipped, so re-running this —
+ * or running it after a form has been rebuilt in the builder — changes
+ * nothing. There is no down: dropping fields that an operator may since have
+ * edited would lose work, and `items` was never removed.
+ */
+return new class extends Migration {
+    public function up(): void
+    {
+        if (!Schema::hasTable('inspection_forms') || !Schema::hasTable('custom_fields') || !Schema::hasTable('categories')) {
+            return;
+        }
+
+        InspectionForm::query()
+            ->whereNotNull('items')
+            ->orderBy('id')
+            ->chunkById(100, function ($forms) {
+                foreach ($forms as $form) {
+                    InspectionFormSync::convertLegacyItems($form);
+                }
+            });
+    }
+
+    public function down(): void
+    {
+        // Nothing to undo: `items` was never removed, and the fields written
+        // here may have been edited since.
+    }
+};