Add first-class Trailer operations

[roncodes]

Summary

Trailer becomes a first-class Fleet-Ops resource: its own navigation entry directly below Vehicles, list/grid/details/create/edit flows, effective-dated towing connections with Vehicles, polymorphic Device and Equipment attachment, telematics ingestion, maintenance integration, import/export, search, reporting, AI query resources, permissions, and full localization in all nine locales.

Architecture

• Model. Trailer extends Asset on the shared assets table with an asset_class = trailer global scope, its own trailer_ public-id namespace and a trailer payload identity, so every internal envelope is { "trailers": [...], "meta": {...} } / { "trailer": {...} } and never assets. Shared status, type and ownership constants back validation, import and the console.
• Towing. asset_connections stores effective-dated connections (connector Vehicle, connected Trailer, towing position, source, audit). Unique active_connected_uuid / active_connector_position columns make single-attachment and position rules database-enforced; attach and detach are idempotent and company-scoped; attaching to another vehicle or an occupied position answers 409.
• Devices and equipment. Device::attachTo() and the Equipment assignment accept fleet-ops:trailer; device_installations keeps installation history. Trailer telemetry flows through TelematicService (device events, with stale-event rejection) and the public track endpoint (stale and null-island observations acknowledged but ignored), persists real spatial positions, and broadcasts trailer.location_changed.
• Public API. /v1/trailers follows the Vehicle conventions from Expand public Fleet, Vehicle, and Driver API contracts #311: additive relation identifiers (category_id, vendor_id, warranty_id, photo_id, vehicle_id), with/expand expansions for category, vendor, warranty, photo, positions; towing state, devices and equipment are part of the base representation; no private identifiers anywhere (the public telematics snapshot drops device/event UUIDs). GET /v1/vehicles/{id}/trailers and GET /v1/vehicles/{id}?with=trailers expose the vehicle side.
• Internal API. fleetbaseRoutes('trailers') plus attach/detach vehicle, device and equipment, statuses/types, export and import. Deleting an attached trailer is refused (single and bulk); vehicles gain attach/detach equipment endpoints.
• Console. Vehicle-convention form (grouped sections, localized labels/placeholders/help, unit-aware dimension, weight and temperature fields driven by the measurement system, conditional reefer and lease sections, money/date/currency controls), details overview, and dedicated Positions, Devices, Equipment, Towing history, Schedules, Work orders and Maintenance tabs. Index with localized enum cells, towing-vehicle link, multi-option/date/model filters mapped to backend params, bulk delete, column customization and layout switch. Vehicle details gain Trailers and Equipment tabs. All mutations update the open panel without a page reload.

Migrations

• assets: nullable unique public_id (historical Asset rows are not rewritten), asset_class, photo_uuid, online, last_online_at, telematics, purchased_at, dimension/weight/running-gear/reefer columns and a company/class/status index.
• asset_connections and device_installations tables.

Review fixes on top of the original branch

• Extension setup resolves Intl through app.lookup('service:intl'); the Trailer sidebar item renders directly below Vehicles after priority sorting (asserted from the rendered menu).
• The console never received attachment_state (missing Ember attribute), the Devices tab posted to the vehicle route, EquipmentFilter::equipable used whereHas on a morphTo relation and matched nothing, modal/tab components lacked the app/ re-exports the host needs, and the modal classes imported a non-existent ember-core base.
• Towing conflicts returned framework abort() HTML, relation filters ignored console UUIDs and multi-option arrays, internal attach responses leaked class-name morph types, the public snapshot leaked device UUIDs, and the post-save transition was aborted.

UI polish round (owner review feedback)

• Badges: attached, detached, in_use, out_of_service and retired had no entry in ember-ui's badge palette and rendered unstyled. They are now styled in the engine stylesheet with the same 800/700/100 convention.
• Card view: the trailer card body is an image stage plus a padded summary strip (status and connectivity badges, "Towed by " link) instead of badges floating on the body.
• Details panel scroll: the details TabNavigation now uses the tab-navigation-fill layout so the tab content is the scroll container and the last sections (Dimensions & capacity onwards) are reachable. Applied to Vehicles too, which had the same clipping.
• Tab overflow: route-backed tabs carry stable ids so ember-ui's overflow bookkeeping can compute the "More" menu; the root cause (identity keyed on a missing id) is fixed upstream in fix(tab-navigation): overflow menu for route-backed tabs without ids ember-ui#171.
• Devices / equipment / trailers / towing history share one AttachmentList component (header with description and primary action, uniform rows with a pill, status badge and row actions, one empty state). New Equipment::Pill and Trailer::Pill complement Device::Pill. Towing history is a compact timeline (vehicle pill, connected/disconnected rows, position, duration, source, state badge) instead of a seven-column table.
• Placeholder image: trailers use an inline SVG trailer silhouette (trailer-placeholder-image helper); a console can override it through defaultValues.trailerImage.
• Map popovers: the live vehicles feed eager-loads current trailers, the index resource emits a compact trailers list, and both map providers (Leaflet template and Google info window builder) show Trailers and Devices cells with an online dot per row. Names are HTML-escaped in the builder.
• Resource cards (driver, vehicle, trailer) share one structure modelled on the driver card: title row with the online indicator, image body on the card background (no extra layers), footer with the status badge beside the actions, then meta rows that style linked records identically (fleetops-card-meta*). The vehicle card lists the assigned driver and the trailers it tows; the trailer card lists the towing vehicle and connectivity; the driver card links its assigned vehicle. The internal vehicle payload carries a compact trailers list (shared TrailerSummary helper, also used by the live-map resource) and the vehicles index requests currentTrailers.
• Grid views for vendors, contacts and customers: table/grid layout switch remembered per listing, plus Vendor::Card and Contact::Card (customers reuse the contact card through the customer actions service).
• Third review round: driver status badge titleized; vehicle and trailer images fill the card body; vehicle index gains driver/trailer/device multi-select filters (new filter/multi-model), "trailer attached / driver assigned / device attached" yes-no filters and a batch internal-id tag input; trailer index gains a devices filter and the refrigerated checkbox loses its redundant label and moves last; orders internal-id filter is a tag input for batch scanning (Feature Request: Support multi-Internal ID filtering in orders table view fleetbase#576). Backend filters accept comma-separated lists and presence flags.
• Device re-attach guard (fleetops#177 follow-up): Device::attachTo throws DeviceAlreadyAttachedException when the device is installed on another asset; the internal device, vehicle and trailer attach endpoints and the public device API answer 409 naming the asset. The attach modal already lists only unattached devices, so the UI and API now agree.
• Translations for the new strings in all nine locales.
• Branch merged with main at v0.6.64 (nested-resource expansion fix); trailer and vehicle contract suites re-run green after the merge.

Verified in the in-app browser pane against the local stack: attached badge colour, card view, details scroll to the last section, More menu listing Schedules/Work orders/Maintenance, Devices/Equipment/Towing history tabs with and without rows, Vehicle Trailers tab, and the CEN-01 popover listing its trailer and device; vehicles, drivers, trailers, vendors, contacts and customers grid views with the unified cards.

Testing

• PHP: composer test:lint clean for the touched files; Trailer suites (TrailerControllerLifecycleTest, TrailerSupportCoverageTest, TrailerTest, TelematicServiceTelemetryTest) pass; a coverage slice reports 100% line coverage for every changed server file. composer test:unit (the CI runner, every test file in its own process) passes: 441 files, exit 0. Repository-wide php-cs-fixer --dry-run only reports pre-existing files outside this change.
• Ember: pnpm lint:js, pnpm lint:hbs, pnpm lint:css, pnpm lint:intl and pnpm build pass. New unit/integration tests cover rendered navigation order, store.query('trailer') normalization, trailer-actions, the details controller, the index route params, the form and the translated-value cell. They were validated only partially here: the engine's dummy app cannot boot ember-core's universe services because ember-core does not declare its tracked-built-ins dependency (see below), and the browser test runner was stopped at the user's request.

Manual verification (local stack, console + API)

Extension startup clean; Trailers directly below Vehicles; empty index state; create a reefer via the UI (type selection reveals the reefer section); index with localized type/status/attachment/connectivity badges; details overview and every tab; attach to a vehicle from the overview (modal with towing position) and see it from the Vehicle's Trailers tab; attach and detach equipment and a device from the tabs; edit and save; public API lifecycle via curl (create flatbed, expansions, position conflict 409, re-attach idempotent, attach elsewhere 409, delete-while-attached 409, vehicle trailer list, with=trailers, track, stale and null-island observations, connections, detach twice); device-event telemetry ingestion updates the trailer. No feature-related console errors.

Not re-verified after the last two front-end fixes (post-save transition, image fallback), and not exercised: delete from the UI, index filtering/sorting from the UI, dark mode and narrow viewports. See the final review notes.

Known limitations

• ember-core 0.3.24 imports tracked-built-ins without declaring it; any setupTest in this engine's dummy app fails until that is fixed upstream (CI does not run ember test for this package).
• Repository-wide PHPStan reports the existing baseline (not part of CI).
• Two pre-existing untranslated host keys (common.search-input, select-resource-filter-by) surface on the index as they do on Vehicles.

Related PRs

• fleetops-data: Add first-class Trailer data models fleetops-data#75
• Postman: Add Trailer API lifecycle collection postman#58 (contract workflow pinned to 0590548)
• fleetbase.io: Document first-class Trailer operations fleetbase.io#96
• ember-ui: fix(tab-navigation): overflow menu for route-backed tabs without ids ember-ui#171 (TabNavigation overflow for route-backed tabs)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (4008bea) to head (461d2ef).

Additional details and impacted files

@@              Coverage Diff              @@
##                main      #309     +/-   ##
=============================================
  Coverage     100.00%   100.00%             
- Complexity     10007     10274    +267     
=============================================
  Files            531       545     +14     
  Lines          38592     39684   +1092     
=============================================
+ Hits           38592     39684   +1092     

Flag	Coverage Δ
backend	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.