Book 5, Chapter 21 — Vehicle Service & Route Compliance¶

STATIC ANALYSIS ONLY. The ERP/DB was never run. Every technical claim carries a file:line citation. Section 7 separates CODE-PROVEN facts from INFERENCE.

1. Purpose (plain language)¶

This chapter covers two adjacent but distinct halves of the Fleet module, both reached from the Fleet sidebar (resources/views/admin/includes/sidebar_includes/fleet.blade.php).

Half A — the Vehicle Service Center is the workshop / maintenance workflow. It answers "which trucks are due for a service, who asked for it, is it in the garage right now, and what did the last service cost?" A driver (from the mobile app) or a back-office user raises a service request; the office reviews and approves it; the driver drops the vehicle at the garage and marks it in progress; when they collect it they mark it completed. Each completed job becomes a permanent service record with parts, labour, supplier and odometer. The system tracks when a vehicle is "due" purely off telemetry mileage versus a per-vehicle service interval, and can recommend the next service type from a configurable sequence (e.g. Small → Medium → Small → Large, looping). Supporting "Utility" screens configure service types, service sequences and warranty schedules.

Half B — Route Compliance & Geofencing is the telematics/GPS compliance layer. It consumes the same GPS/telemetry feed that Chapter 18 (tracking devices) ingests, but here it applies rules: has a carton truck strayed off its geomapped route? Has a delivery vehicle idled inside a branch geofence too long? Is a route running late against a learned baseline? When a rule trips, the system records a violation and — in the more aggressive configurations — can immobilise the vehicle (cut the engine via the SIM/telematics command channel). A Vehicle Command Center lets staff manually switch vehicles on/off, reset mileage, or send raw modem commands, and schedule automatic shut-offs (exemption schedules and custom schedules).

The two halves are related because both are keyed on the Vehicle model and both consume vehicle_last_telemetries (mileage / GPS). This is a prime "AI-leverage / predictability" surface: the compliance side is fundamentally algorithmic (thresholds, route-deviation detection, delay baselines), and the service side has a clear predictive angle (mileage-based due-date forecasting).

2. Users & roles (permissions)¶

Access is gated by the codebase's can('<action>', '<model>') helper against permission strings defined in app/Permissions/FleetManagement.php.

Service Center permission strings¶

Screen	Permission `model`	Controller guard
Service Status list	`vehicle-service-records`	`can('view','vehicle-service-records')` — `VehicleServiceRecordController@index` (`VehicleServiceRecordController.php:31`)
Service Requests list	`vehicle-service-records` (shares)	`VehicleServiceRecordController@indexServiceRequests` (`:55`)
Service History (read-only report)	`vehicle-service-history`	`VehicleServiceHistoryController@index` (`VehicleServiceHistoryController.php:20`)
Service Types / Sequences / Warranty (Utility)	`vehicle-utility`	e.g. `VehicleServiceTypeController@index` (`VehicleServiceTypeController.php:16`), `VehicleServiceSequenceController@index` (`VehicleServiceSequenceController.php:13`), `VehicleSupplierWarrantyController@index` (`VehicleSupplierWarrantyController.php:18`)

Permission model groupings appear in FleetManagement.php at lines 65–87 (vehicle-service, vehicle-service-records, vehicle-service-requests, vehicle-service-history).

Compliance / Command Center permission strings¶

Screen	Permission `model`	Source
Route Compliance (vehicles / violations / settings / route-time-settings)	`route-compliance`, `route-compliance-vehicles`, `route-compliance-violations`, `route-compliance-settings`, `route-compliance-route-time-settings`	`FleetManagement.php:346–373`; sidebar `fleet.blade.php:118–128`
Carton Truck Geomapping	`carton-truck-geomapping`, `-vehicles`, `-violations`, `-settings`	`FleetManagement.php:383–404`; sidebar `fleet.blade.php:191–192`
Idle Branch Geofencing	`idle-branch-geofencing`, `-violations`, `-settings`	`FleetManagement.php:414–427`; sidebar `fleet.blade.php:229–231`
Vehicle Command Center	`vehicle-command-center`	guard `can('view','vehicle-command-center')` (`VehicleCommandContoller.php:38`); `FleetManagement.php:437`
Exemption Schedules (add vehicles)	`add-vehicles-to-exemption-schedules` (sub-permission)	`VehicleCommandContoller.php:170`; `FleetManagement.php:441`
Custom Schedules	`vehicle-command-center-custom-schedules` (`view`/`add`/`edit`)	`VehicleCommandContoller.php:203,222,257`; `FleetManagement.php:454`

Notable: the Command Center's index() scopes visible branches by user_branches — role_id == 1 (superadmin) sees all branches, everyone else only their assigned branches (VehicleCommandContoller.php:43–53).

Mobile driver role¶

The driver mobile app authenticates via JWT (JWTAuth::parseToken()), not the can() permission system. A driver only ever acts on the vehicle where vehicles.driver_id == user.id (Api/VehicleServiceRequestController.php:35,111). Driver-initiated records are stamped initiator_role = 'driver' (:152); back-office ones 'backend' (VehicleServiceRecordController.php:500).

3. Processes¶

3.1 Service-request lifecycle¶

The status enum has five states (app/Enums/VehicleServiceRecordStatus.php:7–11): requested → approved → in_progress → completed, plus cancelled. Note that a back-office "log service" shortcut skips straight to completed (VehicleServiceRecordController.php:498), whereas the driver request flow walks the full ladder.

Trigger & due-detection. A vehicle is "due" when last_service_mileage + service_interval <= current telemetry mileage; "almost due" within ALMOST_DUE_KM_THRESHOLD = 1000 km (VehicleServiceRecordController.php:151, 158–188). The mobile endpoint computes the same status labels ok | almost_due | due (Api/VehicleServiceRequestController.php:24,44–59). Current mileage is read from vehicle_last_telemetries.mileage (VehicleServiceRecordController.php:162).

Recommended service type comes from the vehicle's serviceSequence: getNextServiceTypeName($completedCount) indexes into the stored sequence array; if is_loop the index wraps modulo the sequence length (VehicleServiceSequence.php:43–61, casts sequence => array, is_loop => boolean at :16–17).

Driver flow (mobile API): 1. POST /api/vehicle-service/initiate — creates a VehicleServiceRecord with status = requested, initiator_role = 'driver', odometer snapshotted from telemetry; blocks a second open request (Api/VehicleServiceRequestController.php:108–160). 2. Office reviews via approve() / processApproval() and sets status to approved (VehicleServiceRecordController.php:513, 557–602). 3. PATCH /request/{id}/status with status=in_progress — only allowed from approved; records in_progress_at, lat/long, sets vehicle garage_status = IN_GARAGE, refreshes serviced_at/odometer (Api/VehicleServiceRequestController.php:213–232). Geofence guard: if the garage supplier has coordinates, the driver must be within 400 m (MappingService::getTheaterDistanceBetweenTwoPoints, :190–211). 4. status=completed — only from in_progress; records completed_at, pickup lat/long; calls syncVehicleLastService(); sends the completion alert; marks the garage stay completed or resets garage_status = ACTIVE (:233–255).

On completion, syncVehicleLastService() re-derives the vehicle's last_service_date / last_service_mileage from the newest completed record (VehicleServiceRecordController.php:753–769; duplicated in the API at :554–570), and sendVehicleServiceCompletedMessage() fires an AlertService::sendMessageV2('vehicle_service_completed', …) SMS (:775–786).

Garage stays. A service record must be tied to a VehicleGarageEstimatedTime row (status STATUS_IN_GARAGE); the store/update handlers will inline-create one from garage_estimated_in_at if none is linked (VehicleServiceRecordController.php:466–483). This is the "vehicle currently in garage" source for the In Service datatable (:235–238).

stateDiagram-v2
    [*] --> requested: driver POST /initiate\n(or back-office review)
    requested --> approved: office processApproval()
    requested --> cancelled: office
    approved --> in_progress: driver PATCH status\n(within 400m of garage)\ngarage_status=IN_GARAGE
    in_progress --> completed: driver PATCH status\nsyncVehicleLastService()\nSMS alert + close garage stay
    note right of completed
      Back-office "Log service"
      shortcut writes status=completed
      directly (store())
    end note
    completed --> [*]
    cancelled --> [*]

Cost settlement (cross-module). A service record does not itself post to the ledger; the money flows through Petty Cash (Book 4, Ch 17). petty_cash_purchase_orders carries a nullable vehicle_service_record_id FK (migration 2026_03_03_000001_...), populated in PettyCashPurchaseOrderController.php:2265, 3242, with a picker endpoint getVehicleServiceRecords() (:4580). The driver expense-history API reads these back through VehicleCost rows whose reference_type = 'petty_cash_lpo' (Api/VehicleServiceRequestController.php:453–487). So: service record ← linked → petty-cash LPO → VehicleCost ledger line.

3.2 Violation detection & exemption flow¶

The compliance side is event/telematics-driven. Route Compliance, Carton-Truck Geomapping and Idle-Branch Geofencing each expose a violations list, a settings page (thresholds/toggles), and a release-immobilisation POST action; Route Compliance additionally has geomapped-route sync/view, delay-baseline backfill, live-compare telemetry, and a pass-by report PDF (routes fleet.php:88–148).

Immobilisation mechanics. When a rule trips (or a scheduled shut-off fires), the vehicle is immobilised by sending a modem command over the SIM channel. The manual path is the Command Center's controlAction(): activateImmobilizer() / deactivateImmobilizer() on the Vehicle model, guarded by SIM + plate presence, with switch-off / switch-on / reset-mileage (setparam 11807:<km>) / raw custom commands (VehicleCommandContoller.php:59–142). Immobilisation events are logged to vehicle_immobilizations (causer_id, reason, switch_on_date, later triggered_at, cut_location, source), and pending/automatic cuts queue in pending_immobilizations (executed, speed, send_notification, stage) (migrations 2024_06_20_133631, 2026_03_24_095501, 2026_07_10_120000).

flowchart TD
    T[GPS / telemetry feed\nvehicle_last_telemetries] --> D{Compliance rule evaluated}
    D -->|off geomapped route| V1[Route / Carton violation]
    D -->|idle inside branch geofence too long| V2[Idle-branch violation]
    D -->|late vs delay baseline| V3[Route delay event]
    V1 & V2 & V3 --> E{Vehicle exempt?\nexemption/custom schedule\nor branch toggle off}
    E -->|yes| SKIP[No immobilisation - logged only]
    E -->|no| IMB[Queue pending_immobilization\n-> send SIM cut command\n-> log vehicle_immobilizations]
    IMB --> REL["Staff release-immobilisation\n(releaseViolationImmobilisation)"]
    REL --> ON[deactivateImmobilizer / switch-on]

Exemptions & schedules. Two exemption mechanisms live in the Command Center: - Exemption schedules (vehicle_exemption_schedules): a schedule_type (e.g. 5pm-shutdown, 10pm-shutdown, 4am-shutdown) plus a comma-joined vehicle_ids list. Editing attaches vehicles filtered to primary_responsibility = 'Route Deliveries' (VehicleCommandContoller.php:143–200; migration 2024_07_15_153345). These carve out vehicles from a standard shutdown window. - Custom schedules (vehicle_custom_schedules): an ad-hoc action (switch-off/on) at a specific time for a vehicle_ids list (VehicleCommandContoller.php:201–288; migration 2024_07_28_113703).

Route-compliance settings also expose per-branch toggles (updateBranchToggles, settings.branch-toggles route at fleet.php:106) so compliance can be enabled/disabled per branch, and dedicated route-time settings per branch (RouteComplianceRouteTimeSettingsController, routes fleet.php:101–104).

The precise trip conditions (speed thresholds, idle-minute limits, geofence radius, delay-baseline maths) live inside RouteComplianceController.php, the geomapping controllers and the idle-geofencing controller. Findings from a focused read of those files are folded into §4 and §7 below.

4. Tables touched & key data (verbatim names)¶

Service Center¶

Table	Notable columns	Source
`vehicle_service_records`	`vehicle_id`, `vehicle_service_type_id`, `vehicle_garage_estimated_time_id`, `serviced_at`, `odometer_km`, `vehicle_service_supplier_id`, `is_warranty_service`, `reference`, `parts_amount`, `labor_amount`, `total_amount`, `notes`	migration `2026_02_22_160000:14–27`
↳ + service-request cols	`status` (default `completed`), `initiated_by`, `initiator_role`, `driver_notes`	`2026_03_03_000002:14–19`
↳ + driver-status cols	`in_progress_at/_lat/_long`, `completed_at/_lat/_long`	`2026_03_09_000001:14–22`
`vehicle_service_types`	`name`, `description`	`2026_02_22_150000`
`vehicle_service_sequences`	`name`, `sequence` (JSON array of type ids), `is_loop`	`2026_03_05_100000`; model casts `VehicleServiceSequence.php:16–17`
`vehicles.vehicle_service_sequence_id`	links vehicle → sequence	`2026_03_05_100001`
`vehicle_service_items`	per-record parts: `vehicle_maintenance_item_id`, `quantity`, `unit_cost`, `total_cost`	`2026_03_02_120000`; sync logic `VehicleServiceRecordController.php:728–748`
`vehicle_maintenance_items`	`description`, `cost` (+ amortization fields)	`2025_02_20_085605`, `2025_08_06_130000`
`vehicle_garage_estimated_times`	`estimated_in_at`, `estimated_out_at`, `status`, `wa_supplier_id`, `replacement_vehicle_id`, `recorded_by_user_id`, `completed_by_user_id`	`2026_02_20_103717` + follow-ups
`vehicle_service_suppliers` / `vehicle_centre_suppliers`	garage suppliers (joined `wa_suppliers`)	`2025_02_18_175046`; used `VehicleServiceRecordController.php:409–413`
`supplier_warranty_schedules`	`vehicle_supplier_id`, `config` (JSON)	`2026_02_22_100000`; `VehicleSupplierWarrantyController.php:47–70`
`petty_cash_purchase_orders.vehicle_service_record_id`	cost link (Ch 17)	`2026_03_03_000001`

Odometer/mileage source throughout is vehicle_last_telemetries.mileage (VehicleServiceRecordController.php:162,180).

Verbatim spelling note: the controller class file is named VehicleCommandContoller.php — "Contoller" is misspelled (missing the "r"); this is the real class name VehicleCommandContoller (:18).

Compliance / Command Center¶

Table	Notable columns	Source
`vehicle_immobilizations`	`vehicle_id`, `causer_id`, `reason`, `switch_on_date`, `switch_on_by`; + `triggered_at`, `cut_location`, `source`	`2024_06_20_133631`, `2026_03_24_160000`, `2026_07_10_130000`, `2026_07_23_030000`
`pending_immobilizations`	`vehicle_id`, `executed`, `user_id`, `reason`, `speed`, `send_notification`, `stage`	`2026_03_24_095501`, `2026_07_10_120000`
`vehicle_exemption_schedules`	`schedule_type`, `vehicle_ids` (CSV)	`2024_07_15_153345`
`vehicle_custom_schedules`	`action`, `time`, `vehicle_ids` (CSV), `created_by`	`2024_07_28_113703`
`geomapped_vehicle_routes`	`vehicle_id`, `route_id`, `geomap_date`, `encoded_polyline`, `coordinates` (JSON), `allocation_source`	`2026_05_06_000001`, `2026_05_12_100000`
`route_compliance_violations`	`max_deviation_meters`, `buffer_meters_snapshot`, `violation_occurrence_date`, `actions_summary`, `enforcement_state`, `enforcement_episodes` (JSON), soft-deletes + `deletion_reason`	`2026_05_07_000001` + follow-ups
`route_compliance_settings`	per-route `buffer_distance_meters`, `alerts/immobilisation_on_violations`, `travel/dwell_tolerance_minutes`, `gate_pass_overstay_minutes`, `alerts/immobilisation_on_delays`	`2026_05_02_000001`, `2026_06_03_000001`, `2026_07_23_010000`
`route_compliance_delay_events`	`delay_type` (travel/dwell/gate_pass_overstay), `expected/actual/delay_seconds`, `tolerance_seconds_snapshot`, `stop_key`	`2026_07_23_020000`
`route_compliance_delay_baselines`	`route_id` (unique), `segments_json`, `stop_sessions_json`, `reference_geomapped_vehicle_route_id`	`2026_07_23_000001`
`route_compliance_setting_change_logs`	`scope` (route/branch), old/new for every setting, `changed_by`	`2026_07_01_140000`
`geomapped_carton_truck_routes`	`route_type` (supplier_route/inter_branch), `route_id`, `encoded_polyline`, `coordinates`	`2026_08_17_161649`
`carton_truck_geomapping_violations` / `_settings` / `_setting_change_logs`	mirror of route-compliance shape (buffer 100 m default)	`2026_08_18_090000/100000/100100`
`idle_branch_geofencing_violations` / `_settings` / `_setting_change_logs`	`distance_from_branch_meters`, `radius_meters_snapshot`; settings per `branch_id`, `radius_meters` default 500	`2026_08_24_123721/123722/123723`

5. Interactions with other modules¶

Vehicle register & tracking devices (Ch 18): everything keys on the App\Vehicle model. Mileage, GPS and the SIM/immobilizer command channel (activateImmobilizer, sim_card_number, switch_off_status) belong to the vehicle/tracking layer; this chapter consumes that data and issues cut commands. Tracking DEVICES = Ch 18; the compliance RULES that consume their data = here.
Petty Cash / AP (Ch 17): service-record costs settle via petty-cash LPOs (vehicle_service_record_id FK) which post VehicleCost ledger lines (reference_type='petty_cash_lpo') — see §3.1.
VehicleCost / expense history: the driver expense-history API reads vehicle->expenses() and hides categories per the VEHICLE_COST_CATEGORIES_SHOWN_ON_MOBILE setting (Api/VehicleServiceRequestController.php:355–367).
Alerts / SMS: completion notifications go through AlertService::sendMessageV2 with scenario SmsScenarios::VEHICLE_SERVICE_COMPLETED (VehicleServiceRecordController.php:782); immobilisation commands go through the injected SmsService (VehicleCommandContoller.php:25,100).
Branches (Restaurant/user_branches): branch scoping for the Command Center and per-branch compliance toggles / route-time settings.
Mapping: MappingService::getTheaterDistanceBetweenTwoPoints provides the 400 m garage-proximity guard (Api/VehicleServiceRequestController.php:200).

6. Alternatives & variants (flags / tenant)¶

Two initiation paths, one table. Driver mobile (requested → full ladder) vs. back-office "Log service" (straight to completed) share vehicle_service_records, distinguished by initiator_role (VehicleServiceRecordController.php:500; Api/...:152).
Service interval fallback. The mobile status uses the vehicle's own service_interval; a comment notes a vehicle-model fallback was intended ("vehicle's value if set, otherwise vehicle model's") but the code reads only $vehicle->service_interval (Api/VehicleServiceRequestController.php:47–49) — see §7.
Looping vs. linear sequences (is_loop) change the recommended-service rotation (VehicleServiceSequence.php:50–57).
Per-branch compliance toggles and route-time settings allow compliance to be tuned or disabled per branch (fleet.php:103–106).
Exemption vs. custom schedules offer standing windows vs. one-off shut-offs (§3.2).
Mobile cost-category visibility driven by the VEHICLE_COST_CATEGORIES_SHOWN_ON_MOBILE DB setting (Api/VehicleServiceRequestController.php:356).
No hard-coded tenant/feature-flag branching was found in the service controllers beyond the permission can() gates.

7. Open questions — CODE-PROVEN vs INFERENCE¶

CODE-PROVEN¶

Service status enum and its five states, badge classes and labels (VehicleServiceRecordStatus.php:7–33).
Due / almost-due detection is pure mileage arithmetic against service_interval with a 1000 km "almost" band (VehicleServiceRecordController.php:151,158–188).
Driver status transitions are strictly guarded (approved→in_progress→completed) with a 400 m garage geofence (Api/VehicleServiceRequestController.php:190–255).
Costs settle via petty-cash LPO carrying vehicle_service_record_id → VehicleCost (PettyCashPurchaseOrderController.php:2265,4580; migration 2026_03_03_000001).
Command Center issues real modem commands (switch-off/on, setparam 11807, custom) via SmsService and logs to vehicle_immobilizations (VehicleCommandContoller.php:59–142).
Exemption/custom schedule tables store CSV vehicle_ids and typed schedule/action strings (migrations 2024_07_15_153345, 2024_07_28_113703).
Class filename/class name misspelling VehicleCommandContoller (VehicleCommandContoller.php:18).

INFERENCE (needs runtime/deeper read to confirm)¶

The exact trip conditions for route-compliance, carton-truck-geomapping and idle-branch-geofencing violations (speed limits, idle-minute thresholds, geofence radii, route-deviation tolerance, delay-baseline formulae) live in the compliance controllers; see the agent-derived detail below — treat threshold values as inference until confirmed against settings defaults.
Who evaluates the rules and when. No scheduler/job was read here; a cron/queue worker consuming telemetry is inferred from the pending_immobilizations "queue" table (executed flag, stage) and the backfill-delay-baselines route.
The vehicle-model service-interval fallback appears intended but not implemented (Api/VehicleServiceRequestController.php:47–49).
AI-leverage surface (INFERENCE): the compliance layer is a strong candidate — route-deviation scoring, learned delay baselines, and predictive "due for service" forecasting from mileage trends are all algorithmic and could be model-assisted. This is flagged as opportunity, not existing behaviour.

CODE-PROVEN — Route Compliance (from `RouteComplianceController.php` + models/migrations)¶

Corridor-deviation rule. RouteComplianceCorridorEvaluator::evaluateAgainstReferencePolyline() computes the max perpendicular (great-circle / Haversine, earth radius 6371000 m) distance of each telematics sample from the reference polyline; compliant = max_deviation_meters <= buffer_meters. Points are downsampled (actual ≤2000, reference ≤3000, endpoints preserved). Buffer default 100 m (RouteComplianceCorridorEvaluator.php:14,64–118; controller compareViolationRoutes :450–463).
Delay rules. route_compliance_delay_events has three delay_types: travel, dwell, gate_pass_overstay (RouteComplianceDelayEvent.php:17–21). A delay fires when actual_seconds > expected_seconds + tolerance_seconds, where expected comes from a per-route baseline (route_compliance_delay_baselines.segments_json / stop_sessions_json) and tolerance from settings (defaults travel 15 min, dwell 10 min). Travel delays are never immobilised (post-hoc), only dwell / gate-pass overstay can (RouteComplianceDelayActionService.php:21–24,66).
Baselines are learned from a reference geomap day (RouteComplianceDelayBaselineService), enriched with OSRM road distances; rebuilt on geomap sync (RouteComplianceController.php:1046) or via backfill-delay-baselines (:1071–1094).
Settings (route_compliance_settings, per-route after the 2026_06_03_000001 refactor): buffer_distance_meters (100), alerts_on_violations (true), immobilisation_on_violations (false), travel/dwell_tolerance_minutes, gate_pass_overstay_minutes, alerts_on_delays, immobilisation_on_delays (RouteComplianceSetting.php:12–24). Branch-wide toggle via updateBranchToggles() (:928–961). Every change is audited to route_compliance_setting_change_logs.
Enforcement episodes (enforcement_state: open/immobilised/released/closed; enforcement_episodes JSON) drive escalating alerts and the release flow; releaseViolationImmobilisation() / releaseDelayEventImmobilisation() call deactivateImmobilizer() (RouteComplianceController.php:313–381).
Live monitoring. liveCompare() / liveCompareTelemetry() re-evaluate the corridor in real time during an active delivery, polling every ~15 s (fleet.route_compliance_live_compare_poll_ms, :1400). A pass-by report PDF is exportable (:682–729).

CODE-PROVEN — Carton-Truck Geomapping & Idle-Branch Geofencing (from Fleet controllers/models/migrations)¶

Carton-truck is the same corridor-deviation engine applied to GRN routes (route_type ∈ supplier_route | inter_branch). Geomapped paths live in geomapped_carton_truck_routes (encoded polyline + coordinates, unique on vehicle_id+route_type+route_id+geomap_date); violations in carton_truck_geomapping_violations (dedupe key violation_occurrence_date, max_deviation_meters, buffer_meters_snapshot, soft-deleted with a deletion_reason); settings carton_truck_geomapping_settings (buffer default 100 m, alerts on, immob off). Admin manually syncs telematics into a polyline; the corridor evaluator flags deviation beyond the buffer, then CartonTruckGeomappingViolationActionService fires admin alert + optional driver SMS + optional immobilisation (carton_truck_geomapping_violation alert; migrations 2026_08_17_161649, 2026_08_18_090000/100000/100100).
Idle-branch geofencing is a distance-from-branch rule, not corridor-based: a violation is one row per vehicle per day when a vehicle is idle (no active inbound delivery) AND distance_from_branch_meters > radius_meters_snapshot (idle_branch_geofencing_violations, dedupe on vehicle_id+violation_occurrence_date). Settings are per branch (idle_branch_geofencing_settings.radius_meters default 500 m, alerts on, immob off; 2026_08_24_...). No driver SMS (idle vehicle has no active schedule). Release flow mirrors carton-truck.
Shared machinery: both use the HasEnforcementEpisodes trait, an action_log JSON audit, actions_summary (none/alert/immobilisation/alert_immobilisation), per-route/branch settings + change-log tables, and route the actual engine-cut through Vehicle::activateImmobilizer() / deactivateImmobilizer() with a RouteComplianceImmobilisationLockService open-lock guard.
Permission verbs beyond view: sync-geomap / clear-geomap on carton-truck-geomapping-vehicles, update/edit on the *-settings models, release-immobilisation on the *-violations models (per agent read of the Fleet controllers).

INFERENCE (from the above, needs runtime confirmation)¶

The evaluators run in a background telematics-ingest job, not synchronously in these controllers; the controllers mostly view/sync/release. The pending_immobilizations queue table and the "auto-refresh" allocation source support this but the scheduler/worker was not read here.
Exact threshold defaults (100 m buffer, 500 m idle radius, 15/10-min tolerances) are the migration/model defaults; live per-route/per-branch overrides may differ.
AI-leverage surface (strong): learned multi-day delay baselines, dynamic time-of-day/traffic-aware corridor buffers, re-violation likelihood scoring per driver/route, and immobilisation risk-scoring (vs. today's binary threshold) are all natural model-assisted extensions — opportunity, not current behaviour.

8. Source references¶

Routes - routes/web.php:5329–5338 — command-center, exemption/custom schedules - routes/web.php:6284–6321 — service-types, sequences, service-records, requests, history, warranty - routes/modules/fleet.php:88–148 — route-compliance, carton-truck-geomapping, idle-branch-geofencing groups - routes/modules/petty_cash.php:353–356 — petty-cash ↔ vehicle service records - API driver routes: Api\VehicleServiceRequestController methods (routes/modules/api.php)

Controllers - app/Http/Controllers/Admin/VehicleServiceRecordController.php (index/datatables/due/almost-due/in-service/create/store/approve/processApproval/edit/update/destroy/sync helpers) - app/Http/Controllers/Api/VehicleServiceRequestController.php (myVehicleStatus/initiate/updateStatus/history/expense-history/service-types) - app/Http/Controllers/Admin/VehicleServiceHistoryController.php - app/Http/Controllers/Admin/VehicleServiceTypeController.php, VehicleServiceSequenceController.php, VehicleSupplierWarrantyController.php - app/Http/Controllers/Admin/VehicleCommandContoller.php - app/Http/Controllers/Admin/Fleet/RouteComplianceController.php, RouteComplianceRouteTimeSettingsController.php - app/Http/Controllers/Admin/Fleet/CartonTruckGeomappingController.php, CartonTruckGeomappingViolationController.php, CartonTruckGeomappingSettingController.php - app/Http/Controllers/Admin/Fleet/IdleBranchGeofencingController.php - app/Http/Controllers/PettyCashPurchaseOrderController.php:2265,3242,3924,4580

Models / Enums - app/Enums/VehicleServiceRecordStatus.php - app/Models/VehicleServiceRecord.php, VehicleServiceSequence.php - app/Models/VehicleExemptionSchedule.php, VehicleCustomSchedule.php, VehicleImmobilization.php

Migrations — as cited inline in §4.

Permissions / Nav - app/Permissions/FleetManagement.php:65–87, 346–454 - resources/views/admin/includes/sidebar_includes/fleet.blade.php (nav gating §2)