Dispatch & Returns boards

Day boards for outbound and inbound jobs — config-driven stages, unrestricted drag, scan deep-links, and warehouse filtering.

Overview#

The dispatch and returns boards are the warehouse day surfaces: every order going out today, and every order due back today, grouped into columns that follow your configured stages. They share one kanban shell. Cards keep both a Scan deep-link (into the scan console) and an advance button; dragging a card uses the same stage-advance action as the button.

These are multi-job boards, not a single-load scan session. Off-manifest “needs a decision” work lives on the scan console, not as a board column.

A per-rental returns workbench at /returns/{rental} is a separate editor and is not the board.

The returns workbench exposes outstanding lines through Flag return issue, which opens Missing, Swap, Repair, and Damage disposition choices. Exception cards are persisted against the rental as soon as they are raised, so they survive refreshes and are shared by operators with returns access. An operator can commit a disposition or dismiss a card raised in error. Close return & raise charges is available only when no pending exception remains and every manifest line is returned or dispositioned; the close action validates both conditions again.

Stages#

Columns come from DispatchStage / ReturnStage rows, ordered by sort_order. Adding a stage in settings appears on the board without a code change. Seeded defaults:

Named tokens (zinc, blue, green, amber, red) and a safe # hex (# plus 3–8 hex digits) colour the column’s inset edge accent. amber uses the shared --amber token so attention stages stay distinct from terminal green.

Moving a job#

Anyone with dispatch.manage / returns.manage can:

• click the card’s next-action button, or
• drag the card into any configured column (wire:sort → handleSort).

Both paths call AdvanceDispatchStage / AdvanceReturnStage (lazy row, lock-for-update, *.stage_advanced audit + webhook). Drags are not restricted by column-legality rules. Reordering inside a column is accepted by the sort handler but is not stored — card order inside a column follows the assembler (load/due time).

View-only users (dispatch.view / returns.view) see the board and cannot advance.

Cards#

Each card is assembled from the rental (not invented copy):

• name (customer, else title) and mono job ref
• out / due time via Formatter, with an urgency or overdue dot when the assembler flags it
• segmented pick / return progress when line counts exist
• chips for flightcases, vehicle (or “No vehicle”), and crew initials — dispatch only
• a blocker banner when the assembler reports a shortage, overdue ship, or open return exception
• Scan when the stage is scannable and the user has scanning.scan — check-out on dispatch, check-in on returns
• next-action advance, or a terminal “On vehicle” / “Closed” stamp

The identity strip’s CTA is derived from that same payload: “Resolve N first” when attention cards exist, “Progress remaining N” while non-terminal cards remain, “Board clear” when every job on the board is terminal. Attention lists cap at 50 with an honest truncation note. A 4px hairline under the board shows whole-load progress from real pick/return (or job) counts.

Warehouse filtering uses the shared warehouse filter (dropdown). Plugin actions inject through dispatch.board.actions / returns.board.actions.

On narrow viewports the shared shell turns columns into swipeable tabs. Wall-mode dimming remains a shell feature.

Permissions#

Related#

• Scan Console — check-out / check-in sessions the Scan links open.
• Rentals — allocation and per-order dispatch / return on the rental record.
• Warehouses — warehouse scoping for the filter.