@fleetbase/fleetops-engine 0.6.64 → 0.6.66

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

@@ -0,0 +1,362 @@
+<?php
+
+namespace Fleetbase\FleetOps\Http\Controllers\Api\v1;
+
+use Fleetbase\FleetOps\Events\TrailerLocationChanged;
+use Fleetbase\FleetOps\Http\Controllers\Api\v1\Concerns\ResolvesFleetOpsApiResources;
+use Fleetbase\FleetOps\Http\Controllers\Api\v1\Concerns\ResolvesPublicExpansions;
+use Fleetbase\FleetOps\Http\Requests\CreateTrailerRequest;
+use Fleetbase\FleetOps\Http\Requests\UpdateTrailerRequest;
+use Fleetbase\FleetOps\Http\Resources\v1\AssetConnection as AssetConnectionResource;
+use Fleetbase\FleetOps\Http\Resources\v1\DeletedResource;
+use Fleetbase\FleetOps\Http\Resources\v1\Trailer as TrailerResource;
+use Fleetbase\FleetOps\Models\AssetConnection;
+use Fleetbase\FleetOps\Models\Trailer;
+use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Models\Vendor;
+use Fleetbase\FleetOps\Models\Warranty;
+use Fleetbase\FleetOps\Support\Utils;
+use Fleetbase\Http\Controllers\Controller;
+use Fleetbase\LaravelMysqlSpatial\Types\Point;
+use Fleetbase\Models\Category;
+use Fleetbase\Models\File;
+use Illuminate\Database\Eloquent\ModelNotFoundException;
+use Illuminate\Http\Request;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Facades\DB;
+
+class TrailerController extends Controller
+{
+    use ResolvesFleetOpsApiResources;
+    use ResolvesPublicExpansions;
+
+    /**
+     * Relations that are part of the base Trailer representation. The towing
+     * connection, attached devices and attached equipment are first-class trailer
+     * state, so they are always present rather than opt-in expansions.
+     */
+    private const RELATIONS = ['currentConnection.vehicle', 'connections.vehicle', 'devices', 'equipments'];
+
+    /**
+     * Optional expansions accepted through `with` / `expand`.
+     */
+    public const EXPANDABLE = [
+        'category'  => 'category',
+        'vendor'    => 'vendor',
+        'warranty'  => 'warranty',
+        'photo'     => 'photo',
+        'positions' => 'positions',
+    ];
+
+    public function create(CreateTrailerRequest $request)
+    {
+        $this->rejectUuidIdentifiers($request);
+        $this->applyPublicExpansions($request, static::EXPANDABLE);
+
+        $input                 = $this->input($request);
+        $input['company_uuid'] = session('company');
+
+        return new TrailerResource($this->load(Trailer::create($input), $request));
+    }
+
+    public function query(Request $request)
+    {
+        $this->rejectUuidIdentifiers($request);
+        $expansions = $this->applyPublicExpansions($request, static::EXPANDABLE);
+
+        return TrailerResource::collection($this->queryTrailers($request, fn (&$query) => $query->with(array_merge(self::RELATIONS, $expansions))->withCount(['devices', 'equipments'])));
+    }
+
+    public function find(string $id, ?Request $request = null)
+    {
+        // The parameter carries a default, so Laravel's dispatcher does not inject it;
+        // fall back to the container request so expansions are still mapped.
+        $request = $request instanceof Request ? $request : request();
+        $this->applyPublicExpansions($request, static::EXPANDABLE);
+
+        try {
+            return new TrailerResource($this->load($this->resolveModel(Trailer::class, $id), $request));
+        } catch (ModelNotFoundException) {
+            return $this->notFound();
+        }
+    }
+
+    public function update(string $id, UpdateTrailerRequest $request)
+    {
+        $this->rejectUuidIdentifiers($request);
+        $this->applyPublicExpansions($request, static::EXPANDABLE);
+
+        try {
+            $trailer = $this->resolveModel(Trailer::class, $id);
+        } catch (ModelNotFoundException) {
+            return $this->notFound();
+        }
+
+        $trailer->update($this->input($request));
+
+        return new TrailerResource($this->load($trailer->refresh(), $request));
+    }
+
+    public function delete(string $id)
+    {
+        try {
+            $trailer = $this->resolveModel(Trailer::class, $id);
+        } catch (ModelNotFoundException) {
+            return $this->notFound();
+        }
+
+        if ($this->hasActiveConnection($trailer)) {
+            return response()->json(['error' => 'Detach the trailer before deleting it.'], 409);
+        }
+
+        $trailer->delete();
+
+        return new DeletedResource($trailer);
+    }
+
+    /**
+     * Record a direct Trailer observation. Stale observations (older than the last
+     * recorded telemetry event) and null-island coordinates are acknowledged without
+     * mutating live state.
+     */
+    public function track(string $id, Request $request)
+    {
+        $request->validate([
+            'latitude'    => ['required', 'numeric', 'between:-90,90'],
+            'longitude'   => ['required', 'numeric', 'between:-180,180'],
+            'observed_at' => ['nullable', 'date'],
+            'speed'       => ['nullable', 'numeric', 'min:0'],
+            'heading'     => ['nullable', 'numeric', 'between:0,360'],
+            'altitude'    => ['nullable', 'numeric'],
+            'odometer'    => ['nullable', 'numeric', 'min:0'],
+        ]);
+
+        try {
+            $resolved = $this->resolveModel(Trailer::class, $id);
+        } catch (ModelNotFoundException) {
+            return $this->notFound();
+        }
+
+        if ((float) $request->latitude === 0.0 && (float) $request->longitude === 0.0) {
+            return new TrailerResource($this->load($resolved, $request));
+        }
+
+        [$trailer, $changed] = DB::transaction(function () use ($resolved, $request) {
+            $trailer    = Trailer::where('company_uuid', session('company'))->where('uuid', $resolved->uuid)->lockForUpdate()->firstOrFail();
+            $observedAt = $request->date('observed_at') ?? now();
+            $currentAt  = data_get($trailer->telematics, 'last_event_at');
+
+            if ($currentAt && $observedAt->lt(Carbon::parse($currentAt))) {
+                return [$trailer, false];
+            }
+
+            $snapshot = ['location' => new Point((float) $request->latitude, (float) $request->longitude), 'online' => true, 'last_online_at' => $observedAt];
+            foreach (['speed', 'heading', 'altitude', 'odometer'] as $field) {
+                if ($request->exists($field)) {
+                    $snapshot[$field] = $request->input($field);
+                }
+            }
+
+            $snapshot['telematics'] = array_merge($trailer->telematics ?? [], [
+                'last_event_at'       => $observedAt->toISOString(),
+                'last_provider'       => 'public_api',
+                'last_telemetry_data' => $request->only(['speed', 'heading', 'altitude', 'odometer']),
+            ]);
+
+            $trailer->update($snapshot);
+            $trailer->createPosition($request->only(['latitude', 'longitude', 'speed', 'heading', 'altitude']));
+
+            return [$trailer, true];
+        }, 3);
+
+        if ($changed) {
+            broadcast(new TrailerLocationChanged($trailer, ['source' => 'public_api']));
+        }
+
+        return new TrailerResource($this->load($trailer, $request));
+    }
+
+    /**
+     * Attach the Trailer to a Vehicle. Re-attaching to the same Vehicle is idempotent
+     * and returns the existing active connection.
+     */
+    public function attach(string $id, Request $request)
+    {
+        $this->rejectUuidIdentifiers($request);
+        $request->validate([
+            'vehicle'      => ['required', 'string'],
+            'connected_at' => ['nullable', 'date'],
+            'source'       => ['nullable', 'string', 'max:255'],
+            'position'     => ['nullable', 'integer', 'min:1'],
+        ]);
+
+        try {
+            $trailer = $this->resolveModel(Trailer::class, $id);
+            $vehicle = $this->resolveModel(Vehicle::class, $request->input('vehicle'));
+        } catch (ModelNotFoundException) {
+            return response()->json(['error' => 'Trailer or vehicle resource not found.'], 404);
+        }
+
+        $result = DB::transaction(function () use ($trailer, $vehicle, $request) {
+            $active = $this->activeConnectionQuery($trailer)->lockForUpdate()->first();
+
+            if ($active) {
+                if ($active->connector_uuid === $vehicle->uuid) {
+                    return $active;
+                }
+
+                return 'Trailer is already attached to another vehicle. Detach it before moving.';
+            }
+
+            $position    = $request->integer('position', 1);
+            $positionKey = $vehicle->uuid . ':' . $position;
+
+            if (AssetConnection::where('company_uuid', session('company'))->where('active_connector_position', $positionKey)->lockForUpdate()->exists()) {
+                return 'Another trailer already occupies this towing position.';
+            }
+
+            return AssetConnection::create([
+                'company_uuid'              => session('company'),
+                'connector_type'            => Vehicle::class,
+                'connector_uuid'            => $vehicle->uuid,
+                'connected_type'            => Trailer::class,
+                'connected_uuid'            => $trailer->uuid,
+                'active_connected_uuid'     => $trailer->uuid,
+                'active_connector_position' => $positionKey,
+                'relationship_type'         => 'towing',
+                'position'                  => $position,
+                'connected_at'              => $request->date('connected_at') ?? now(),
+                'source'                    => $request->input('source', 'manual'),
+                'created_by_uuid'           => session('user'),
+                'updated_by_uuid'           => session('user'),
+            ]);
+        }, 3);
+
+        if (is_string($result)) {
+            return response()->json(['error' => $result], 409);
+        }
+
+        return new AssetConnectionResource($result->load(['vehicle', 'trailer']));
+    }
+
+    /**
+     * End the active towing connection while preserving it as history. Detaching an
+     * unattached Trailer is a no-op.
+     */
+    public function detach(string $id, Request $request)
+    {
+        $request->validate([
+            'disconnected_at' => ['nullable', 'date'],
+            'notes'           => ['nullable', 'string'],
+        ]);
+
+        try {
+            $trailer = $this->resolveModel(Trailer::class, $id);
+        } catch (ModelNotFoundException) {
+            return $this->notFound();
+        }
+
+        $connection = DB::transaction(function () use ($trailer, $request) {
+            $active = $this->activeConnectionQuery($trailer)->lockForUpdate()->first();
+
+            if (!$active) {
+                return null;
+            }
+
+            $active->update([
+                'disconnected_at'           => $request->date('disconnected_at') ?? now(),
+                'active_connected_uuid'     => null,
+                'active_connector_position' => null,
+                'notes'                     => $request->input('notes', $active->notes),
+                'updated_by_uuid'           => session('user'),
+            ]);
+
+            return $active->load(['vehicle', 'trailer']);
+        }, 3);
+
+        return response()->json([
+            'status'     => 'ok',
+            'connection' => $connection ? new AssetConnectionResource($connection) : null,
+        ]);
+    }
+
+    public function connections(string $id)
+    {
+        try {
+            $trailer = $this->resolveModel(Trailer::class, $id);
+        } catch (ModelNotFoundException) {
+            return $this->notFound();
+        }
+
+        return AssetConnectionResource::collection($trailer->connections()->with(['vehicle', 'trailer'])->get());
+    }
+
+    public function vehicleTrailers(string $id)
+    {
+        try {
+            $vehicle = $this->resolveModel(Vehicle::class, $id);
+        } catch (ModelNotFoundException) {
+            return response()->json(['error' => 'Vehicle resource not found.'], 404);
+        }
+
+        $trailers = Trailer::whereHas('currentConnection', fn ($q) => $q->where('connector_uuid', $vehicle->uuid))
+            ->with(self::RELATIONS)
+            ->withCount(['devices', 'equipments'])
+            ->get();
+
+        return TrailerResource::collection($trailers);
+    }
+
+    protected function input(Request $request): array
+    {
+        $input = $request->only([
+            'name', 'description', 'code', 'type', 'body_type', 'status', 'vin', 'plate_number', 'serial_number', 'make', 'model', 'year', 'color',
+            'usage_type', 'measurement_system', 'odometer', 'odometer_unit', 'ownership_type', 'purchased_at', 'lease_expires_at', 'financing_status',
+            'currency', 'acquisition_cost', 'current_value', 'insurance_value', 'depreciation_rate', 'length', 'width', 'height', 'tare_weight', 'gvwr',
+            'payload_capacity', 'cargo_volume', 'axle_count', 'tire_count', 'door_count', 'coupling_type', 'brake_type', 'abs_equipped', 'ebs_equipped',
+            'refrigerated', 'temperature_min', 'temperature_max', 'reefer_engine_hours', 'capacity', 'specs', 'attributes', 'notes',
+        ]);
+
+        if ($request->filled(['latitude', 'longitude'])) {
+            $input['location'] = new Point((float) $request->latitude, (float) $request->longitude);
+        } elseif ($request->filled('location')) {
+            $input['location'] = Utils::getPointFromCoordinates($request->location);
+        }
+
+        $this->applyPublicIdRelation($input, 'category', 'category_uuid', Category::class, $request);
+        $this->applyPublicIdRelation($input, 'vendor', 'vendor_uuid', Vendor::class, $request);
+        $this->applyPublicIdRelation($input, 'warranty', 'warranty_uuid', Warranty::class, $request);
+        $this->applyPublicIdRelation($input, 'photo', 'photo_uuid', File::class, $request);
+
+        return $input;
+    }
+
+    protected function queryTrailers(Request $request, callable $callback)
+    {
+        // @codeCoverageIgnoreStart
+        return Trailer::queryWithRequest($request, $callback);
+        // @codeCoverageIgnoreEnd
+    }
+
+    protected function activeConnectionQuery(Trailer $trailer)
+    {
+        return AssetConnection::where('company_uuid', session('company'))->where('active_connected_uuid', $trailer->uuid);
+    }
+
+    protected function hasActiveConnection(Trailer $trailer): bool
+    {
+        return $this->activeConnectionQuery($trailer)->exists();
+    }
+
+    protected function notFound()
+    {
+        return response()->json(['error' => 'Trailer resource not found.'], 404);
+    }
+
+    private function load(Trailer $trailer, ?Request $request = null): Trailer
+    {
+        $expansions = $request ? $this->resolvePublicExpansions($request, static::EXPANDABLE) : [];
+
+        return $trailer->load(array_merge(self::RELATIONS, $expansions))->loadCount(['devices', 'equipments']);
+    }
+}

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

@@ -52,6 +52,7 @@ class VehicleController extends Controller
         'warranty' => 'warranty',
         'photo'    => 'photo',
         'devices'  => 'devices',
+        'trailers' => 'currentTrailers',
     ];
 
     /**

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

@@ -2,6 +2,7 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
+use Fleetbase\FleetOps\Exceptions\DeviceAlreadyAttachedException;
 use Fleetbase\FleetOps\Exports\DeviceExport;
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
 use Fleetbase\FleetOps\Models\Device;
@@ -134,6 +135,8 @@ class DeviceController extends FleetOpsController
         try {
             $device->attachTo($vehicle);
             $device->load(['telematic', 'warranty', 'attachable']);
+        } catch (DeviceAlreadyAttachedException $e) {
+            return response()->error($e->getMessage(), 409);
         } catch (\Throwable $e) {
             $this->logDeviceAttachmentFailure('attach', $device, $vehicle, $e);
 

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

@@ -64,15 +64,28 @@ class FuelProviderConnectionController extends FleetOpsController
 
     public function sync(Request $request, string $id): JsonResponse
     {
+        $request->validate([
+            'from'    => 'nullable|date',
+            'to'      => 'nullable|date|after_or_equal:from',
+            'options' => 'nullable|array',
+        ]);
         $connection = $this->findConnection($id);
-        $async      = $request->boolean('async', true);
-        $from       = $request->input('from') ? Carbon::parse($request->input('from')) : null;
-        $to         = $request->input('to') ? Carbon::parse($request->input('to')) : null;
-        $options    = $request->array('options', []);
-        $syncRun    = $this->fuelProviderService->createSyncRun($connection, $from, $to, $async ? 'queued' : 'running');
+        if ($connection->status === 'disabled') {
+            throw ValidationException::withMessages(['connection' => 'Enable this integration before syncing.']);
+        }
+        $async   = $request->boolean('async', true);
+        $from    = $request->input('from') ? Carbon::parse($request->input('from'))->startOfDay() : null;
+        $to      = $request->input('to') ? Carbon::parse($request->input('to'))->endOfDay() : null;
+        $options = $request->array('options', []);
+        $syncRun = $this->fuelProviderService->createSyncRun($connection, $from, $to, $async ? 'queued' : 'running');
 
         if ($async) {
-            SyncFuelProviderTransactionsJob::dispatch($connection->uuid, $from?->toIso8601String(), $to?->toIso8601String(), $options, $syncRun->uuid);
+            try {
+                SyncFuelProviderTransactionsJob::dispatch($connection->uuid, $syncRun->from?->toIso8601String(), $syncRun->to?->toIso8601String(), $options, $syncRun->uuid);
+            } catch (\Throwable $error) {
+                $syncRun->update(['status' => 'error', 'finished_at' => now(), 'error' => 'Unable to queue sync. Please retry.']);
+                throw $error;
+            }
 
             return response()->json(['status' => 'ok', 'message' => 'Fuel provider sync queued.', 'sync_run' => $syncRun], 202);
         }
@@ -82,9 +95,28 @@ class FuelProviderConnectionController extends FleetOpsController
         return response()->json(['status' => 'ok', 'summary' => $summary, 'sync_run' => $syncRun->fresh()]);
     }
 
+    public function activity(Request $request, string $id): JsonResponse
+    {
+        $connection   = $this->findConnection($id);
+        $transactions = $connection->transactions();
+        $totals       = (clone $transactions)->selectRaw('COUNT(*) as transactions, SUM(volume) as liters, COUNT(fuel_report_uuid) as fuel_reports')->first();
+        $unmatched    = (clone $transactions)->where('sync_status', 'unmatched')->count();
+        $spend        = (clone $transactions)->selectRaw('currency, SUM(amount) as amount')->groupBy('currency')->get()->map(fn ($row) => ['currency' => $row->currency, 'amount' => (int) $row->amount]);
+        $runs         = $connection->syncRuns()->latest()->limit(20)->get();
+
+        return response()->json([
+            'connection' => $connection->only(['status', 'last_synced_at', 'last_tested_at', 'last_error', 'last_sync_state']),
+            'totals'     => ['transactions' => (int) $totals->transactions, 'liters' => (float) $totals->liters, 'fuel_reports' => (int) $totals->fuel_reports, 'unmatched' => $unmatched, 'spend' => $spend],
+            'runs'       => $runs->map(fn ($run) => $run->only(['uuid', 'status', 'from', 'to', 'imported', 'matched', 'unmatched', 'fuel_reports_created', 'liters', 'amount', 'started_at', 'finished_at', 'created_at', 'error', 'summary'])),
+        ]);
+    }
+
     protected function validateConnectionInput(array $input, ?FuelProviderConnection $connection = null): void
     {
         $provider = data_get($input, 'provider');
+        if (isset($input['environment']) && !in_array($input['environment'], ['production', 'sandbox'], true)) {
+            throw ValidationException::withMessages(['environment' => 'Choose Production or Sandbox.']);
+        }
         if (!$provider) {
             throw ValidationException::withMessages(['provider' => 'Fuel integration provider is required.']);
         }
@@ -104,13 +136,13 @@ class FuelProviderConnectionController extends FleetOpsController
     protected function normalizeConnectionInput(array &$input, ?FuelProviderConnection $connection = null): void
     {
         $input['company_uuid'] ??= session('company');
-        $input['environment'] ??= 'production';
+        $input['environment'] ??= $connection?->environment ?? 'production';
         $input['status']        = $connection?->status && $connection->status !== 'draft' ? $connection->status : ($input['status'] ?? 'configured');
         $input['sync_settings'] = array_merge([
             'window_days'              => 7,
             'matching_order'           => ['plate_number', 'internal_id', 'vin', 'serial_number', 'call_sign', 'fuel_card_number', 'trip_number'],
             'auto_create_fuel_reports' => true,
-        ], (array) data_get($input, 'sync_settings', []));
+        ], (array) $connection?->sync_settings, (array) data_get($input, 'sync_settings', []));
     }
 
     protected function findConnection(string $id): FuelProviderConnection

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

@@ -9,6 +9,8 @@ use Fleetbase\FleetOps\Models\Equipment;
 use Fleetbase\FleetOps\Models\Fleet;
 use Fleetbase\FleetOps\Models\FuelProviderTransaction;
 use Fleetbase\FleetOps\Models\FuelReport;
+use Fleetbase\FleetOps\Models\InspectionForm;
+use Fleetbase\FleetOps\Models\InspectionSubmission;
 use Fleetbase\FleetOps\Models\Issue;
 use Fleetbase\FleetOps\Models\Maintenance;
 use Fleetbase\FleetOps\Models\MaintenanceSchedule;
@@ -112,24 +114,36 @@ class HubController extends Controller
         $now     = Carbon::now();
         $next7   = Carbon::now()->addDays(7);
 
-        $overdueSchedules        = $this->count(MaintenanceSchedule::query()->where('status', 'active')->whereNotNull('next_due_date')->where('next_due_date', '<', $now), $company);
-        $upcomingSchedules       = $this->count(MaintenanceSchedule::query()->where('status', 'active')->whereBetween('next_due_date', [$now, $next7]), $company);
-        $openWorkOrders          = $this->count(WorkOrder::query()->whereIn('status', ['open', 'in_progress']), $company);
-        $overdueWorkOrders       = $this->count(WorkOrder::query()->whereNotIn('status', ['closed', 'canceled'])->whereNotNull('due_at')->where('due_at', '<', $now), $company);
-        $openMaintenance         = $this->count(Maintenance::query()->whereNotIn('status', ['completed', 'canceled']), $company);
-        $highPriorityMaintenance = $this->count(Maintenance::query()->whereNotIn('status', ['completed', 'canceled'])->whereIn('priority', ['high', 'urgent', 'critical']), $company);
-        $lowStockParts           = $this->count(Part::query()->where('quantity_on_hand', '>', 0)->where('quantity_on_hand', '<=', 5), $company);
-        $equipment               = $this->count(Equipment::query(), $company);
+        $overdueSchedules         = $this->count(MaintenanceSchedule::query()->where('status', 'active')->whereNotNull('next_due_date')->where('next_due_date', '<', $now), $company);
+        $upcomingSchedules        = $this->count(MaintenanceSchedule::query()->where('status', 'active')->whereBetween('next_due_date', [$now, $next7]), $company);
+        $openWorkOrders           = $this->count(WorkOrder::query()->whereIn('status', ['open', 'in_progress']), $company);
+        $overdueWorkOrders        = $this->count(WorkOrder::query()->whereNotIn('status', ['closed', 'canceled'])->whereNotNull('due_at')->where('due_at', '<', $now), $company);
+        $openMaintenance          = $this->count(Maintenance::query()->whereNotIn('status', ['completed', 'canceled']), $company);
+        $highPriorityMaintenance  = $this->count(Maintenance::query()->whereNotIn('status', ['completed', 'canceled'])->whereIn('priority', ['high', 'urgent', 'critical']), $company);
+        $publishedInspectionForms = $this->count(InspectionForm::query()->where('status', 'published'), $company);
+        $failedInspections        = $this->count(InspectionSubmission::query()->whereIn('status', ['submitted', 'needs_review'])->where('result', 'failed'), $company);
+        $unresolvedInspections    = $this->count(InspectionSubmission::query()->where('result', 'failed')->whereNull('resolved_at'), $company);
+        $lowStockParts            = $this->count(Part::query()->where('quantity_on_hand', '>', 0)->where('quantity_on_hand', '<=', 5), $company);
+        $equipment                = $this->count(Equipment::query(), $company);
 
         return response()->json([
             'kpis'     => [
                 $this->kpi('overdue_schedules', 'Overdue Schedules', $overdueSchedules, $overdueSchedules > 0 ? 'Recurring service needs attention.' : 'No recurring service is overdue.', $overdueSchedules > 0 ? 'rose' : 'green', 'calendar-xmark', 'maintenance.schedules'),
                 $this->kpi('upcoming_schedules', 'Due This Week', $upcomingSchedules, 'Maintenance schedules due in the next 7 days.', 'blue', 'calendar-day', 'maintenance.schedules'),
+                $this->kpi('failed_inspections', 'Failed Inspections', $failedInspections, $failedInspections > 0 ? 'Failed DVIR items need issue or work order follow-up.' : 'No failed inspections need review.', $failedInspections > 0 ? 'rose' : 'green', 'clipboard-check', 'maintenance.inspection-submissions'),
                 $this->kpi('open_work_orders', 'Open Work Orders', $openWorkOrders, $openWorkOrders > 0 ? 'Active work needs assignment or closure.' : 'No open work orders right now.', $openWorkOrders > 0 ? 'amber' : 'green', 'clipboard-list', 'maintenance.work-orders'),
-                $this->kpi('low_stock_parts', 'Low Stock Parts', $lowStockParts, $lowStockParts > 0 ? 'Parts inventory may need replenishment.' : 'No low-stock parts detected.', $lowStockParts > 0 ? 'amber' : 'green', 'cog', 'maintenance.parts'),
             ],
-            'actions'  => $this->maintenanceActions($overdueSchedules, $upcomingSchedules, $openWorkOrders, $overdueWorkOrders, $highPriorityMaintenance, $lowStockParts, $equipment),
+            'actions'  => $this->maintenanceActions($overdueSchedules, $upcomingSchedules, $openWorkOrders, $overdueWorkOrders, $highPriorityMaintenance, $lowStockParts, $equipment, $failedInspections, $unresolvedInspections, $publishedInspectionForms),
             'sections' => [
+                [
+                    'key'         => 'inspections',
+                    'title'       => 'Inspections And DVIR',
+                    'description' => 'Capture driver inspections, failed items, and repair follow-up.',
+                    'links'       => [
+                        $this->link('Inspection Forms', 'maintenance.inspection-forms', 'clipboard-check', $publishedInspectionForms, 'Published forms available for driver and technician inspections.'),
+                        $this->link('Inspections', 'maintenance.inspection-submissions', 'list-check', $unresolvedInspections, 'Submitted DVIRs, failed items, and linked follow-up work.'),
+                    ],
+                ],
                 [
                     'key'         => 'planning',
                     'title'       => 'Planning',
@@ -152,6 +166,7 @@ class HubController extends Controller
             ],
             'docs'     => [
                 $this->doc('Schedules', 'calendar-alt', 'fleet-ops/maintenance/schedules/overview', 'Maintenance schedules guide', 'Plan recurring service windows and convert due schedules into work orders.'),
+                $this->doc('Inspections', 'clipboard-check', 'fleet-ops/maintenance/inspections/overview', 'Inspections guide', 'Capture DVIR checks, failed items, and issue or work order follow-up.'),
                 $this->doc('Work Orders', 'clipboard-list', 'fleet-ops/maintenance/work-orders/overview', 'Work orders guide', 'Coordinate assigned maintenance work, vendors, due dates, and completion.'),
                 $this->doc('Equipment', 'trailer', 'fleet-ops/maintenance/equipment/overview', 'Equipment guide', 'Track serviceable equipment that participates in maintenance operations.'),
                 $this->doc('Parts', 'cog', 'fleet-ops/maintenance/parts/overview', 'Parts guide', 'Manage parts inventory and restocking signals used by maintenance teams.'),
@@ -231,10 +246,16 @@ class HubController extends Controller
         return $actions ? array_slice($actions, 0, 6) : [$this->action('ready', 'Core resources look ready', 'Drivers, vehicles, issues, and supporting records are in a healthy operating posture.', 'success', 'check-circle', null)];
     }
 
-    protected function maintenanceActions(int $overdueSchedules, int $upcomingSchedules, int $openWorkOrders, int $overdueWorkOrders, int $highPriorityMaintenance, int $lowStockParts, int $equipment): array
+    protected function maintenanceActions(int $overdueSchedules, int $upcomingSchedules, int $openWorkOrders, int $overdueWorkOrders, int $highPriorityMaintenance, int $lowStockParts, int $equipment, int $failedInspections = 0, int $unresolvedInspections = 0, int $publishedInspectionForms = 0): array
     {
         $actions = [];
 
+        if ($failedInspections > 0) {
+            $actions[] = $this->action('failed_inspections', 'Review failed inspections', "{$failedInspections} failed inspection" . ($failedInspections === 1 ? ' needs' : 's need') . ' issue or work order follow-up.', 'warning', 'clipboard-check', 'maintenance.inspection-submissions', ['result' => 'failed']);
+        } elseif ($publishedInspectionForms === 0) {
+            $actions[] = $this->action('create_inspection_forms', 'Create inspection forms', 'Publish DVIR forms so drivers can report vehicle defects before dispatch.', 'info', 'clipboard-check', 'maintenance.inspection-forms');
+        }
+
         if ($overdueSchedules > 0) {
             $actions[] = $this->action('overdue_schedules', 'Review overdue schedules', "{$overdueSchedules} recurring service schedule" . ($overdueSchedules === 1 ? ' is' : 's are') . ' overdue.', 'warning', 'calendar-xmark', 'maintenance.schedules');
         }
@@ -259,6 +280,10 @@ class HubController extends Controller
             $actions[] = $this->action('low_stock_parts', 'Replenish low-stock parts', "{$lowStockParts} stocked part" . ($lowStockParts === 1 ? ' is' : 's are') . ' at or below the default threshold.', 'warning', 'cog', 'maintenance.parts');
         }
 
+        if ($unresolvedInspections > 0 && $failedInspections === 0) {
+            $actions[] = $this->action('unresolved_inspections', 'Resolve inspection follow-up', "{$unresolvedInspections} failed inspection" . ($unresolvedInspections === 1 ? ' remains' : 's remain') . ' unresolved.', 'warning', 'list-check', 'maintenance.inspection-submissions', ['result' => 'failed']);
+        }
+
         if ($equipment === 0) {
             $actions[] = $this->action('add_equipment', 'Add serviceable equipment', 'Equipment records make maintenance planning more complete.', 'info', 'trailer', 'maintenance.equipment');
         }