Phase 4: Warehouse screen, pull table, shorts, MTRs and the upload pipeline

The Warehouse home with the numbers, the Open shorts table, the find bar and the five-column task board
(waiting, being pulled, on hold, pulled, released in the last 3 days) with buttons, hold reasons and drag.
Every role sees the warehouse stage on a packet as the WH pill and the line under it. The pull table on the
Materials tab: Pulled with auto-start, issued, location, heat with Enter to the next line, shorts with
receipts, N/A, MTR per line with a viewer. Send back to Clerical with a reason. Release to supervisor stays
blocked until every line is pulled or short and every pulled line has a heat.

Server: the heats_recorded precondition on WH_RELEASE, receive by custody, server-validated hold and short
reasons, the old packet history texts, GET /api/warehouse/board, cards with the warehouse stage and pull
counts. Uploads typed by content per kind (drawing, mtr, document, bom with XLSX and CSV), limits per kind,
optional ClamAV behind the clamav compose profile, a storage quota alert on the new notification_events
table (migration 0005) shown on the Admin Storage tab.

Tests: every warehouse action as every role, the release gate, the short-receive exception, the heat
pattern, upload sniffing and limits, the ClamAV path with a fake scanner, the quota alert; frontend board
and pull table tests; Playwright scenarios for the board and the pull flow. Verified on docker-1 in the CI
stack: 3557 server tests, 106 frontend tests, 17 Playwright scenarios. Docs updated; D5 closed.

Co-Authored-By: Claude Fable 5.1 <[email protected]>

frontend/src/api/packets.ts

@@ -4,6 +4,7 @@ import { asList, ifMatch, qs } from "./query";
 import type {
   AttachPagesBody,
   BomLine,
+  BomPatch,
   FieldCas,
   Guarded,
   LogRow,
@@ -12,7 +13,10 @@ import type {
   PacketHeader,
   PacketListQuery,
   PacketRead,
+  ReceiptBody,
+  ShortBody,
   TransitionBody,
+  WhStageBody,
   WorkOrder,
 } from "./types";
 
@@ -68,4 +72,18 @@ export const packetsApi = {
     api.post<PacketRead>(`${base(id)}/change-orders/${no}/reject`, body),
   coHold: (id: number, no: number, hold: boolean, extra: Guarded = {}) =>
     api.post<PacketRead>(`${base(id)}/change-orders/${no}/hold`, { hold, ...extra }),
+
+  /* Phase 4: the warehouse. */
+  /** One BOM line. If-Match is the line's row_version. */
+  patchBomLine: (id: number, item: number, rowVersion: number, body: BomPatch, g: Guarded = {}) =>
+    request<PacketRead>(`${base(id)}/bom/${item}`, { method: "PATCH", body: { ...body, ...g }, headers: ifMatch(rowVersion) }),
+  /** Opens the short on a line, or updates the open one. expect_open says which the caller saw. */
+  saveShort: (id: number, item: number, body: ShortBody, g: Guarded = {}) =>
+    api.post<PacketRead>(`${base(id)}/bom/${item}/short`, { ...body, ...g }),
+  /** "Not short after all": closes the open short. */
+  clearShort: (id: number, item: number, body: { expect_open: boolean }, g: Guarded = {}) =>
+    api.delWithBody<PacketRead>(`${base(id)}/bom/${item}/short`, { ...body, ...g }),
+  receiveShort: (id: number, item: number, body: ReceiptBody, g: Guarded = {}) =>
+    api.post<PacketRead>(`${base(id)}/bom/${item}/short/receipts`, { ...body, ...g }),
+  setWhStage: (id: number, body: WhStageBody, g: Guarded = {}) => api.post<PacketRead>(`${base(id)}/wh`, { ...body, ...g }),
 };

frontend/src/api/storage.ts

@@ -0,0 +1,10 @@
+// Admin: the assets volume, the scanner and the open alerts (phase 4 contract, api/admin.py).
+import { api } from "./client";
+import { asList } from "./query";
+import type { AlertRow, StorageInfo } from "./types";
+
+export const storageApi = {
+  storage: (signal?: AbortSignal) => api.get<StorageInfo>("/api/admin/storage", signal),
+  alerts: async (signal?: AbortSignal): Promise<AlertRow[]> => asList<AlertRow>(await api.get<unknown>("/api/admin/alerts", signal), "alerts"),
+  ack: (id: number) => api.post<AlertRow | null>(`/api/admin/alerts/${encodeURIComponent(String(id))}/ack`, {}),
+};

frontend/src/api/types.ts

@@ -175,6 +175,17 @@ export interface PacketCard {
   co_pending?: boolean;
   /** Phase 3: every leg is closed in VISUAL (observed). */
   visual_closed?: boolean;
+  /** Phase 4: the current warehouse row, on every card. */
+  wh?: WhInfo | null;
+  wh_sent_at?: string | null;
+  visual_rel?: string | null;
+  /** Lines not N/A. */
+  bom_total?: number;
+  /** Lines not N/A that are pulled or have an open short. */
+  bom_pulled?: number;
+  bom_missing_heat?: number;
+  /** The released column only: the newest wh_release transition. */
+  released_at?: string | null;
 }
 
 export interface PacketList {
@@ -229,7 +240,16 @@ export interface BomShort {
   eta: string | null;
   note: string | null;
   opened_at: string | null;
-  receipts?: unknown[];
+  receipts?: ShortReceipt[];
+  row_version?: number;
+}
+
+export interface ShortReceipt {
+  qty: number | string;
+  heat: string | null;
+  note: string | null;
+  at: string | null;
+  by?: WhoRef | null;
 }
 
 export interface BomLine {
@@ -249,6 +269,8 @@ export interface BomLine {
   pulled?: boolean;
   mtr_asset_id?: string | null;
   src?: string | null;
+  /** "Y" on a sub-assembly line: its heats are recorded on its own packet. */
+  sub?: string | null;
   short?: BomShort | null;
   row_version?: number;
 }
@@ -310,7 +332,7 @@ export interface PacketRead {
   heat_table: unknown[];
   stage: Record<string, unknown> | null;
   stages: unknown[];
-  wh: Record<string, unknown> | null;
+  wh: WhInfo | null;
   qc: Record<string, unknown> | null;
   qc_history: unknown[];
   change_orders: ChangeOrder[];
@@ -654,3 +676,131 @@ export interface ResourceMapRow {
   rows_last_run: number | null;
   updated_at: string | null;
 }
+
+/* ---------- Phase 4: warehouse ---------- */
+
+export type WhStage = "incoming" | "pulling" | "hold" | "pulled";
+
+/** The current packet_wh row. */
+export interface WhInfo {
+  stage: WhStage;
+  by: WhoRef | null;
+  at: string | null;
+  reason: string | null;
+  note: string | null;
+  auto: boolean;
+}
+
+/** POST /api/packets/{id}/wh. */
+export interface WhStageBody {
+  stage: WhStage;
+  expect_stage: WhStage;
+  reason?: string;
+  note?: string;
+}
+
+/** POST /api/packets/{id}/bom/{item}/short. */
+export interface ShortBody {
+  qty: number;
+  reason: string;
+  ref: string | null;
+  eta: string | null;
+  note: string | null;
+  heat?: string;
+  expect_open: boolean;
+}
+
+/** POST /api/packets/{id}/bom/{item}/short/receipts. */
+export interface ReceiptBody {
+  qty: number;
+  heat: string | null;
+  note: string | null;
+}
+
+/** PATCH /api/packets/{id}/bom/{item}. */
+export interface BomPatch {
+  heat?: string | null;
+  na?: boolean;
+  issued?: number | null;
+  loc?: string | null;
+  pulled?: boolean;
+  mtr_asset_id?: string | null;
+}
+
+/** One open short on GET /api/warehouse/board. */
+export interface ShortRow {
+  packet: {
+    id: number;
+    unit_number: string;
+    op: string | null;
+    drawing: string | null;
+    status: PacketStatus;
+    wh_stage: WhStage | null;
+    station: StationRef | null;
+    holder: string;
+    dept: DeptRef;
+  };
+  item: number;
+  bom_line_id: number;
+  description: string | null;
+  part_id: string | null;
+  material: string | null;
+  length: string | null;
+  qty: number | string;
+  qty_open: number | string;
+  reason: string | null;
+  ref: string | null;
+  eta: string | null;
+  note: string | null;
+  opened_at: string | null;
+  age_days: number;
+  late: boolean;
+  short_id: number;
+  row_version: number;
+  /** Not in the contract. A receipt needs no heat on an N/A line. */
+  na?: boolean;
+}
+
+export type BoardColumn = WhStage | "released";
+
+export interface BoardResponse {
+  kpis: { waiting: number; pulling: number; hold: number; pulled: number; open_shorts: number; released_24h: number };
+  columns: Record<BoardColumn, PacketCard[]>;
+  shorts: ShortRow[];
+}
+
+export interface BoardQuery {
+  q?: string;
+  project_id?: number;
+  unit_id?: number;
+  dept?: string;
+}
+
+/* ---------- Phase 4: storage and alerts (Admin) ---------- */
+
+export interface VolumeUsage {
+  total: number;
+  used: number;
+  free: number;
+  pct: number;
+  warn: boolean;
+}
+
+export interface AlertRow {
+  id: number;
+  kind: string;
+  severity: "info" | "warning" | "critical" | string;
+  subject: string | null;
+  detail: Record<string, unknown>;
+  created_at: string;
+  resolved_at: string | null;
+  acknowledged_at: string | null;
+  acknowledged_by: WhoRef | string | null;
+}
+
+export interface StorageInfo {
+  usage: VolumeUsage;
+  quota_warn_pct: number;
+  alert: AlertRow | null;
+  clamav: { configured: boolean; host: string | null; reachable: boolean | null };
+}

frontend/src/api/warehouse.ts

@@ -0,0 +1,22 @@
+// The warehouse board (phase 4 contract, api/warehouse.py).
+import { api } from "./client";
+import { qs } from "./query";
+import type { BoardQuery, BoardResponse, PacketCard } from "./types";
+
+const COLUMNS = ["incoming", "pulling", "hold", "pulled", "released"] as const;
+
+/** Every column and number present, even when the server leaves one out. */
+function normalise(raw: Partial<BoardResponse> | null): BoardResponse {
+  const cols = (raw?.columns ?? {}) as Partial<Record<(typeof COLUMNS)[number], PacketCard[]>>;
+  const columns = Object.fromEntries(COLUMNS.map((c) => [c, Array.isArray(cols[c]) ? cols[c] : []])) as BoardResponse["columns"];
+  return {
+    kpis: { waiting: 0, pulling: 0, hold: 0, pulled: 0, open_shorts: 0, released_24h: 0, ...(raw?.kpis ?? {}) },
+    columns,
+    shorts: Array.isArray(raw?.shorts) ? raw.shorts : [],
+  };
+}
+
+export const warehouseApi = {
+  board: async (q: BoardQuery = {}, signal?: AbortSignal): Promise<BoardResponse> =>
+    normalise(await api.get<Partial<BoardResponse> | null>(`/api/warehouse/board${qs({ ...q })}`, signal)),
+};