Specification: Mobile Operations Companion v1¶

TLDR (Solution Summary)¶

Deliver a new depot-scoped mobile companion under /mobile/* inside bf-manage-web.
Gate the surface behind one root feature flag: manage-mobile-ops.
Keep the main desktop layout, routes, and service-worker behavior unchanged.
Ship four phase-1 mobile screens: Home, Yard, Chargers, and Incidents, plus charger and incident detail screens.
Reuse existing auth, depot context, permissions, charger mutations, and data hooks.
Limit mobile charger actions to soft reset, remote start/stop, and remote cable release, with explicit accessible confirmation.
Make the delivered mobile slice WCAG 2.2 AA conscious by design.

Problem statement:
- BetterFleet Manage currently optimises for desktop operations, while mobile depot-floor tasks need a smaller, faster, and more focused flow.
Goal and success criteria:
- Build a mobile-first companion for depot-walk use cases without affecting the main desktop tool.
- Success is measured by:
- mobile operators being able to access charger, yard, and active incident awareness through /mobile/*;
- charger detail exposing only the approved action set with clear confirmation and feedback;
- the mobile slice remaining usable from 320px widths upward without horizontal scrolling for the core tasks;
- desktop routes and layout remaining unchanged when the mobile flag is off.
What will be built in this phase:
- /mobile home with alert banners, summary counts, and quick links.
- /mobile/yard list-first yard status with optional read-only visual yard support.
- /mobile/chargers and /mobile/chargers/:chargePointId for charger visibility and narrow actions.
- /mobile/incidents and /mobile/incidents/:incidentId for active-only incident visibility.
Out of scope in this phase:
- mobile settings, dispatch, timeline, reports, workspace-wide mobile overview, out-of-depot map, incident resolution, hard reset, charger overrides, charger settings edits, and depot vehicle-location editing.

Primary persona:
- Yard operator or depot floor supervisor walking a selected depot.
Secondary persona:
- Support or operations user triaging a live charger or incident from a phone.
High-level user stories:
- As a depot-floor operator, I want a mobile home screen so I can quickly assess whether anything needs attention.
- As a depot-floor operator, I want a list-first yard view so I can understand site activity without relying on complex touch gestures.
- As an operator with charger permissions, I want a narrow set of mobile charger actions so I can safely request common interventions.
- As an operations user, I want active incident detail with asset links so I can move from alert to charger context quickly.

Route namespace:
- /mobile -> Home
- /mobile/yard
- /mobile/chargers
- /mobile/chargers/:chargePointId
- /mobile/incidents
- /mobile/incidents/:incidentId
Feature flags:
- Root exposure flag: manage-mobile-ops
- Existing action flags continue to apply inside mobile:
- hide-remote-actions
- manage-enable-remote-cable-release
Permissions:
- Mobile charger actions continue to depend on checkPermissions("Charger", ["operate"]).
Data and service reuse:
- Reuse current auth session and depot context.
- Reuse current chargers, vehicles, depot-layout, and incidents service hooks.
- No mobile-only backend endpoint is introduced in this phase.

Show current depot context and mobile navigation.
Show site alert banners for the selected depot.
Show summary cards for:
- active incidents
- chargers needing attention
- vehicles needing attention
- charging now
Provide clear quick links into Yard, Chargers, and Incidents.

Be list-first and usable without visual yard interpretation.
When depot layout data exists and is published:
- show a read-only visual yard representation as supplemental context;
- show the same live assets and statuses in an accessible list.
When depot layout data does not exist:
- fall back to the list-only experience.
The list remains the primary interaction surface in all cases.

Show a mobile-friendly list of chargers for the selected depot.
Support quick filter chips for All, Charging, Available, Unavailable, and Faulted.
Each charger card shall show:
- charger name
- charger state and connection state
- connector summaries
- connected vehicle when available
- SoC when available
- estimated time to target when available
- last-updated context
Charger actions shall not be available from the list screen.

Show charger state, connection state, zone, circuit, and connector details.
Expose only the approved mobile actions:
- soft reset
- remote start/stop
- remote cable release
Hide or disable unsupported actions instead of exposing desktop parity.
Respect existing feature flags and operate permissions.
Require accessible confirmation before every operational action.
Announce success or failure feedback through live status messaging.

Scope:
- Compliance work applies to the delivered mobile slice only.
Reflow and zoom:
- Core mobile screens shall work from 320px width upward.
- Screens shall support browser zoom and text zoom up to 200% without breaking core actions.
Interaction:
- Every interactive control shall have a visible label or accessible name.
- Focus order shall be logical and visible.
- Controls shall remain keyboard reachable.
- Touch targets shall be large enough for mobile use.
Status communication:
- Charger, vehicle, and incident states shall not rely on color alone.
- Statuses shall include text labels, icons with accessible names, or both.
Yard view:
- The visual yard representation shall never be the only way to access the live yard state.
Motion:
- Avoid mobile-only gestures without explicit alternatives.
- Respect reduced-motion preferences for any transitions.

Desktop behavior remains unchanged for /overview, /chargers, /vehicles, /incidents, /map, and related routes.
The mobile slice remains online-only for phase 1.
No service-worker or manifest behavior changes are introduced.
Existing query and mutation seams remain the source of truth for data and action execution.

Unit and component coverage should validate:
- route and layout helpers for mobile path isolation
- mobile transformation helpers for yard, charger, and incident data
- charger action visibility and filtering logic
Targeted UI verification should cover:
- mobile shell navigation
- scope warning when the app is in all-depots mode
- accessible labels for filters, cards, and action buttons
Manual or later automated regression coverage should include:
- 320x568, 375x812, and 768x1024
- one landscape pass
- desktop regression with manage-mobile-ops off

Add a dedicated mobile shell that activates only on /mobile/*.
Keep the shell visually independent from the desktop left-nav layout.
Build screen-specific presentation using shared mobile components and helper transforms.
Reuse desktop data hooks and narrow action hooks rather than cloning API logic.
Update in-app help and working release notes as part of delivery.