Dispatch Reliability and Reconciliation (Unit User Stories)¶

Context Summary¶

Product area: BetterFleet Manage Dispatch.
Primary entrypoints: Dispatch and Settings -> Dispatch -> Schedules.
Repo scope: bf-manage-web, bf-manage-core, and bf-schedule-creator.
Scope basis: challenge and spec.
Delivery order: operator trust and manual testability first, assignment reconciliation second, manual/ad-hoc operations third.
Story slicing decision: the first slices optimise for safe manual testing and trustworthy operator signals before any larger reconciliation or manual-block workflow is introduced.
Cross-cutting delivery rule: if a UUS still needs multiple repo-level implementation steps, keep the UUS canonical and track the smaller backend/UI/test tasks as execution-only Linear issues rather than widening this file.
Linear mirror rule: each UUS in this file should map to one flat Linear story issue under the future dispatch initiative/project for this artifact set.

Phase 1: Trust and Testability¶

Keep dispatch controls accessible while manually testing¶

Linear issue: TBD

User Story¶

As a dispatcher manually testing assignments, I want the dispatch controls to stay accessible while resizing and scrolling so that I can work continuously without losing my place or my filters.

Acceptance Criteria¶

Block-side and vehicle-side controls such as search, filters, sorting, and tab selection remain accessible after browser or window resize.
Scrolling through block or vehicle results does not force the operator to page-scroll away from the active dispatch controls for that panel.
Supported desktop-size layouts do not leave dispatch content trapped behind stale panel heights after resize.
Existing block selection and assignment interactions remain available while the layout stays stable.

Dependencies¶

None.

Split Signals¶

A broader responsive or mobile redesign is a separate story.

Make the empty Dispatch state easier to understand and act on¶

Linear issue: TBD

User Story¶

As a dispatcher opening Dispatch before blocks are available, I want the empty state to clearly explain what is missing and what I can do next so that I can recover setup without scanning a visually noisy two-pane workspace.

Acceptance Criteria¶

When the selected dispatch day has no blocks, the page presents one clear empty-state message for the block setup problem rather than making the operator interpret empty tabs and a large blank block pane.
The empty state clearly distinguishes between no scheduled blocks and no available schedules when those states occur together.
The primary next action is visible and understandable from the empty state, including when Set up day is disabled.
The block and vehicle panes remain visually balanced in the empty or sparse state at supported desktop and tablet-width layouts.
The vehicle pane does not show detached readiness fragments such as Unknown now and - without a clear label or summary.
Empty-state controls and icon-only actions have accessible names that describe their purpose.

Dependencies¶

Keep dispatch controls accessible while manually testing

Split Signals¶

Cleaning up the populated state with real blocks, selected blocks, recommendations, and allocation actions is a separate story.
Redesigning block cards, vehicle cards, or selected-block density for active assignment workflows is a separate story.

Make populated Dispatch panels scan as one coordinated workspace¶

Linear issue: TBD

User Story¶

As a dispatcher reviewing blocks and vehicle readiness, I want the block and vehicle panels to feel aligned and readable so that I can compare work and allocation options without fighting the layout.

Acceptance Criteria¶

The block and vehicle panes have deliberate separation or framing, so they do not appear crashed together at the center divider.
Panel headings, toolbar rows, section lines, and content starts align across the block and vehicle panes at supported desktop and tablet widths.
The block-side tab/dropdown, unassigned toggle, and sort controls stay readable and do not clip or half-render at tablet width.
The vehicle-side top row uses the same tab/dropdown pattern as the block side for meaningful vehicle categories.
Populated block and vehicle rows use a consistent visual hierarchy, with repeated actions and unknown telemetry values given lower priority than block identity, status, timing, vehicle identity, and readiness.
Selected block state remains visible without stacking excessive outlines, inner borders, and competing status pills.
Past or finished blocks do not visually imply the same urgent allocation workflow as future actionable blocks.

Dependencies¶

Make the empty Dispatch state easier to understand and act on

Split Signals¶

Changing the business rules for whether finished blocks can be allocated is a separate implementation decision if the current API still permits it.
Reworking recommendation logic, energy estimates, or telemetry quality is a separate story.

Show trustworthy status for started and completed blocks¶

Linear issue: TBD

User Story¶

As a dispatcher, I want started and completed blocks to show trustworthy status so that I can focus only on work that still needs intervention.

Acceptance Criteria¶

Core owns the operational bucket, operational state, assignment state, attention state, attention reasons, and whether a block issue is currently actionable.
Dispatch API block responses include additive operational status fields while preserving the existing raw block fields.
Dispatch API block responses can be projected against an explicit operational current time so spoof-time manual testing still changes block buckets and active errors.
The Dispatch frontend uses core-provided operational buckets for the Arrivals, Finished, Started, and Future tabs instead of recalculating those buckets locally.
Arrivals remain in the Arrivals bucket, but their operational state is completed or in-progress based on the operational current time.
A started block does not show an insufficient-energy or equivalent assignment-error state when that state is derived only from a pre-start estimate that no longer reflects the live operational window.
A completed block with no unresolved actionable issue shows an explicit completed-route outcome instead of a generic allocation-error state.
A block with a real unresolved dispatch issue still shows an actionable warning or error state.
Any page-level allocation error summary counts only blocks that still need operator attention.

Implementation Note¶

Core is responsible for dispatch block status and actionability calculations using timezone-aware UTC datetimes. The frontend is responsible for presentation only: tabs, labels, relative time text, icons, colours, sorting, and layout.
Future or opportunistic enhancement: if reliable odometer readings are available at block start and during the active block, derive distance travelled since block start and use it as an additional signal for whether a started block remains viable. This could help Dispatch move from passive status information toward actionable warnings when a started block may no longer be able to complete the remaining work.

Dependencies¶

None.

Split Signals¶

Future automation of recommendation strictness or hard-stop enforcement is a separate story.

Warn on physical blocking at block departure¶

Linear issue: TBD

User Story¶

As a dispatcher, I want physical parking constraints to be shown as a departure-time warning so that I can check yard reality without losing the ability to make an informed dispatch decision.

Acceptance Criteria¶

Physical accessibility is evaluated for the selected block's start time rather than the current page time when a selected block has a start timestamp.
Physical accessibility calculations use timezone-aware UTC datetimes.
A vehicle reported as physically blocked is marked as potentially viable rather than not viable unless a future implementation provides a stronger hard-stop reason.
The frontend presents physical blocking as warning-grade copy and styling.

Dependencies¶

None.

Split Signals¶

Predicting whether a vehicle will be unblocked by departure from planned yard moves is a separate story.
Turning physical blocking into a hard dispatch stop is a separate story and requires a stronger operational rule.

Show a consistent selected-day future horizon¶

Linear issue: TBD

User Story¶

As a dispatcher, I want the Future view to show upcoming work through the selected depot day so that I can prepare the rest of the service day reliably.

Acceptance Criteria¶

The Future view shows selected-day blocks that start after the current depot-local time and before the selected depot day ends.
The same dispatch day and current depot-local time produce the same future block set in both UI presentation and API-backed data.
Overnight carry-over work still appears in the appropriate non-future views such as arrivals, started, or finished.

Dependencies¶

None.

Split Signals¶

Any later move to a configurable or customer-specific horizon is a separate story.

Recover schedule setup from upload and applicability mistakes¶

Linear issue: TBD

User Story¶

As a dispatcher or depot planner, I want schedule setup failures and applicability mistakes to be recoverable in-product so that I can correct dispatch setup without relying on re-upload-only workarounds.

Acceptance Criteria¶

If schedule upload does not return a valid schedule identity, the flow stops with an explicit error and does not issue follow-up requests against a placeholder ID.
After a successful upload, the operator can edit the schedule applicability start date and end date before finishing the schedule setup flow.
An existing schedule can have its applicability start date and end date updated later from schedule management.
Updated applicability is reflected when choosing a schedule for day-of-operations setup.

Dependencies¶

None.

Split Signals¶

Repeat-frequency behaviour beyond date-range correction is a separate story.

Phase 2: Assignment Reconciliation¶

Export current dispatch assignments to CSV¶

Linear issue: TBD

User Story¶

As a dispatcher, I want to export the current dispatch day's blocks and assignments to CSV so that I can review or share the working plan outside BetterFleet and use it as the basis for reconciliation.

Acceptance Criteria¶

Export produces a CSV for the selected dispatch day that includes each exported block's identity, timing, source, and currently assigned vehicle when present.
Unassigned and ignored blocks are represented explicitly in the export rather than omitted silently.
The exported CSV structure is suitable for the later import workflow without requiring manual restructuring.
Export does not mutate the current dispatch day.

Dependencies¶

Show a consistent selected-day future view

Split Signals¶

Printable dispatch sheet layout or customer-facing report formatting is a separate story.

Preview assignment CSV reconciliation against current dispatch data¶

Linear issue: TBD

User Story¶

As a dispatcher, I want to upload an assignment CSV and review how each row matches the current dispatch day before applying changes so that I can catch mistakes safely.

Acceptance Criteria¶

Uploaded CSV rows are classified into matched, unmatched, duplicate, invalid, and missing-current-block outcomes.
The preview shows which matched rows would change an existing block assignment.
The preview does not persist any assignment or block change.
The operator can discard the preview and return to the current dispatch day without changing live dispatch data.

Dependencies¶

Export current dispatch assignments to CSV

Split Signals¶

Automatic correction suggestions for invalid or unmatched rows are a separate story.

Apply CSV assignment changes to existing blocks safely¶

Linear issue: TBD

User Story¶

As a dispatcher, I want confirmed CSV matches to update assignments for existing blocks so that I can seed dispatch quickly from an external dispatch sheet.

Acceptance Criteria¶

Confirmed matched CSV rows update assignments for existing blocks on the selected dispatch day.
Per-row failures are reported back to the operator without hiding successful changes.
Schedule-derived blocks that are absent from the CSV are not deleted or silently changed.
After apply, Dispatch refreshes to show the resulting assignments for the current dispatch day.

Dependencies¶

Preview assignment CSV reconciliation against current dispatch data

Split Signals¶

CSV-driven deletion is out of scope for schedule-derived blocks and should not be introduced by this story.

Phase 3: Manual and Ad-Hoc Operations¶

Mark a vehicle as requiring attention¶

Linear issue: TBD

User Story¶

As a dispatcher, I want to mark a vehicle as requiring attention so that maintenance issues or other temporary unavailability are visible before the vehicle is used for service.

Acceptance Criteria¶

A dispatcher can mark an available vehicle as requiring attention from Dispatch.
A vehicle marked as requiring attention is visibly separated from vehicles that are available for normal service.
A vehicle marked as requiring attention is not presented as a normal available allocation option without a clear warning or explicit override path.
If a vehicle already assigned to work is marked as requiring attention, Dispatch surfaces that affected assignment for operator review rather than silently removing the assignment.
A dispatcher can clear the requires-attention state when the vehicle is ready for service again.
The requires-attention state remains visible to other dispatch users for the same depot until it is cleared.

Dependencies¶

Make populated Dispatch panels scan as one coordinated workspace

Split Signals¶

Capturing full workshop maintenance records, maintenance scheduling, or defect history is a separate story.
Automatically deriving vehicle unavailability from telematics, charging, or maintenance integrations is a separate story.

Create, edit, and delete manual/ad-hoc blocks¶

Linear issue: TBD

User Story¶

As a dispatcher, I want to create, edit, and delete manual or ad-hoc blocks in Dispatch so that I can represent replacement work and late changes directly in the product.

Acceptance Criteria¶

A dispatcher can create a manual or ad-hoc block from Dispatch with its core operational details.
A dispatcher can edit a manual or ad-hoc block after it has been created.
A dispatcher can delete a manual or ad-hoc block through an explicit confirmation step.
Manual or ad-hoc blocks remain distinct from schedule-derived blocks in both details and lifecycle behaviour.

Dependencies¶

Recover schedule setup from upload and applicability mistakes

Split Signals¶

Bulk manual-block creation from non-CSV external feeds is a separate story.

Round-trip manual/ad-hoc blocks through dispatch CSV workflows¶

Linear issue: TBD

User Story¶

As a dispatcher, I want manually created ad-hoc blocks to export and re-import cleanly so that external dispatch sheets and BetterFleet stay aligned after late changes.

Acceptance Criteria¶

Manual or ad-hoc blocks appear in export with stable identity and explicit source.
Import preview can match exported manual or ad-hoc blocks back to the current dispatch day.
CSV omission does not delete schedule-derived blocks, and any manual or ad-hoc deletion path requires explicit confirmation.
Imported manual or ad-hoc rows preserve their ad-hoc meaning instead of being reclassified as schedule-derived work.

Dependencies¶

Export current dispatch assignments to CSV
Preview assignment CSV reconciliation against current dispatch data
Apply CSV assignment changes to existing blocks safely
Create, edit, and delete manual/ad-hoc blocks

Split Signals¶

Persisting uploaded CSVs as historical audit artifacts is a separate story.

Highlight and filter manual/ad-hoc and source-aware blocks¶

Linear issue: TBD

User Story¶

As a dispatcher, I want to highlight and filter manual, ad-hoc, and source-aware blocks so that I can reduce noise and focus on the work that matters right now.

Acceptance Criteria¶

Dispatch filtering can explicitly surface or hide manual or ad-hoc blocks.
Manual or ad-hoc blocks have a visible indicator in list and detail views.
Where source or vehicle-type distinctions exist, dispatch filtering uses those distinctions instead of collapsing all blocks into one misleading generic class.
Blocks without a meaningful source or type distinction are shown with explicit neutral or unknown handling rather than misleading classification.

Dependencies¶

Create, edit, and delete manual/ad-hoc blocks
Round-trip manual/ad-hoc blocks through dispatch CSV workflows

Split Signals¶

Full eBus recommendation logic or mixed-fleet dispatch optimisation beyond filtering is a separate story.