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/packet/PacketPage.tsx

@@ -15,6 +15,9 @@ import { MoveSheet, SendToDeptSheet } from "./sheets";
 import { DocumentsTab, HistoryTab, MaterialsTab, WorkOrdersTab, type Mutate } from "./tabs";
 import { coSummary, coToReview } from "../lib/changeOrders";
 import { ChangesTab, VisualBox } from "./visual";
+import type { Write } from "../warehouse/PullTable";
+import { packetMessage, pillClassFor, WH_STAGES, pillText, progress, whLine, whStage } from "../warehouse/stages";
+import { useWhMove } from "../warehouse/useWhMove";
 
 type Tab = "drawing" | "materials" | "workorders" | "changes" | "docs" | "history";
 
@@ -122,15 +125,18 @@ export function PacketPage() {
   const versionRef = useRef<number | null>(null);
   const fileRef = useRef<HTMLInputElement>(null);
 
+  // A read that was sent before a write committed can answer after the write's own answer: never go back.
+  const take = useCallback((p: PacketRead) => setPacket((cur) => (cur && cur.id === p.id && cur.version > p.version ? cur : p)), []);
+
   const reload = useCallback(async () => {
     try {
       const p = await packetsApi.get(id);
-      setPacket(p);
+      take(p);
       setLoadError(null);
     } catch (err) {
       setLoadError(errorText(err));
     }
-  }, [id]);
+  }, [id, take]);
 
   useEffect(() => {
     setPacket(null);
@@ -150,6 +156,31 @@ export function PacketPage() {
 
   const job = packet ? jobName(packet) : "";
 
+  // Line writes: the answer replaces the packet; the error goes back to the row that made it.
+  const write: Write = useCallback(
+    async (fn) => {
+      try {
+        const r = await run(fn, { sub: job });
+        if (r === undefined) return { ok: false };
+        if (r && typeof r === "object" && "id" in r) take(r as PacketRead);
+        else await reload();
+        return { ok: true };
+      } catch (err) {
+        return { ok: false, err };
+      }
+    },
+    [run, reload, job, take],
+  );
+
+  const wh = useWhMove({
+    run,
+    onDone: setPacket,
+    onError: (err) => {
+      if (err instanceof ApiError && err.status === 409) void reload();
+      setMsg({ ok: false, text: errorText(err) });
+    },
+  });
+
   const mutate: Mutate = useCallback(
     async (fn, opts = {}) => {
       setBusy(true);
@@ -157,7 +188,7 @@ export function PacketPage() {
       try {
         const r = await run(fn, { sign: opts.sign, sub: job });
         if (r === undefined) return false;
-        if (r && typeof r === "object" && "id" in r) setPacket(r);
+        if (r && typeof r === "object" && "id" in r) take(r as PacketRead);
         else await reload();
         if (opts.ok) setMsg({ ok: true, text: opts.ok });
         return true;
@@ -170,7 +201,7 @@ export function PacketPage() {
         setBusy(false);
       }
     },
-    [run, reload, job],
+    [run, reload, job, take],
   );
 
   if (!packet) {
@@ -272,6 +303,22 @@ export function PacketPage() {
   const target = targetHours(p);
   const lotQty = Math.max(0, ...p.work_orders.map((w) => Number(w.qty) || 0));
   const backTo = me?.screens.includes("clerical") ? `/clerical/units/${p.unit.id}` : homePath(me?.screens ?? []);
+  const atWh = p.status === "warehouse";
+  const whCan = atWh && can("set_wh_stage");
+  const stage = whStage(p);
+  const whMsg = whCan ? packetMessage(p) : null;
+  const whTarget = { id: p.id, stage, job, progress: progress(p) };
+  const sendBack = async () => {
+    const reason = await askReason({
+      title: "Send back to Clerical",
+      sub: job,
+      note: "The packet goes back to Clerical as a draft. Say what needs fixing.",
+      min: 8,
+      submitLabel: "Send back to Clerical",
+    });
+    if (reason === null) return;
+    await transition("wh_send_back", { reason }, "Sent back to Clerical.");
+  };
   const hasDraftControls =
     draft && ["edit_header", "send_to_warehouse", "release_to_shop", "send_draft_to_qc", "edit_document_set", "move_unit", "remove"].some((a) => can(a) || p.blocked[a]);
 
@@ -473,6 +520,71 @@ export function PacketPage() {
         </section>
       ) : null}
 
+      {atWh ? (
+        <section className={whCan ? "panel actbox" : "callout"} aria-label="Warehouse">
+          <div className="whstep">
+            <span className={pillClassFor(stage)}>{pillText(stage)}</span>
+            <div className={`whline ${WH_STAGES[stage].cls}`}>{whLine(p)}</div>
+          </div>
+          {whMsg ? (
+            <div>
+              <b>{whMsg.head}</b> {whMsg.rest}
+            </div>
+          ) : null}
+          {whCan || can("wh_send_back") || can("wh_release") || p.blocked.wh_release ? (
+            <div className="acts">
+              <Act p={p} action="wh_send_back" busy={busy} className="btn ghost" onClick={() => void sendBack()}>
+                Send back to Clerical
+              </Act>
+              {whCan && stage === "incoming" ? (
+                <div className="act">
+                  <button className="btn" type="button" disabled={busy || wh.busy} onClick={() => wh.move(whTarget, "pulling")}>
+                    Start pulling
+                  </button>
+                </div>
+              ) : null}
+              {whCan && stage === "hold" ? (
+                <div className="act">
+                  <button className="btn" type="button" disabled={busy || wh.busy} onClick={() => wh.move(whTarget, "pulling")}>
+                    Resume pulling
+                  </button>
+                </div>
+              ) : null}
+              {whCan && stage === "pulling" ? (
+                <div className="act">
+                  <button className="btn" type="button" disabled={busy || wh.busy} onClick={() => wh.move(whTarget, "pulled")}>
+                    Mark pulled
+                  </button>
+                </div>
+              ) : null}
+              {whCan && stage === "pulled" ? (
+                <div className="act">
+                  <button className="btn" type="button" disabled={busy || wh.busy} onClick={() => wh.move(whTarget, "pulling")}>
+                    Back to pulling
+                  </button>
+                </div>
+              ) : null}
+              {whCan && (stage === "incoming" || stage === "pulling") ? (
+                <div className="act">
+                  <button className="btn" type="button" disabled={busy || wh.busy} onClick={() => wh.move(whTarget, "hold")}>
+                    Hold
+                  </button>
+                </div>
+              ) : null}
+              <Act
+                p={p}
+                action="wh_release"
+                busy={busy || wh.busy}
+                className="btn pri"
+                onClick={() => void transition("wh_release", {}, "Released to supervisor.")}
+              >
+                Release to supervisor{p.open_shorts ? ` (${p.open_shorts} short)` : ""}
+              </Act>
+            </div>
+          ) : null}
+        </section>
+      ) : null}
+
       {!draft && (can("set_vclosed") || can("file") || p.blocked.file) ? (
         <section className="panel actbox" aria-label="Close and file">
           <div>
@@ -536,7 +648,7 @@ export function PacketPage() {
             <DrawingViewer pages={drawingPages} />
           </div>
         ) : null}
-        {shownTab === "materials" ? <MaterialsTab p={p} mutate={mutate} busy={busy} /> : null}
+        {shownTab === "materials" ? <MaterialsTab p={p} mutate={mutate} busy={busy} write={write} reload={reload} /> : null}
         {shownTab === "workorders" ? <WorkOrdersTab p={p} /> : null}
         {shownTab === "changes" ? <ChangesTab p={p} roles={me?.roles ?? []} sub={job} mutate={mutate} busy={busy} askReason={askReason} /> : null}
         {shownTab === "docs" ? <DocumentsTab p={p} mutate={mutate} busy={busy} /> : null}
@@ -565,6 +677,7 @@ export function PacketPage() {
           }}
         />
       ) : null}
+      {wh.sheet}
       {guardSheet}
     </>
   );

frontend/src/packet/tabs.tsx

@@ -5,6 +5,9 @@ import { packetsApi } from "../api/packets";
 import type { BomLine, Guarded, PacketRead, WorkOrder } from "../api/types";
 import { errorText, fmtTime } from "../lib/format";
 import { useLoad } from "../lib/useLoad";
+import { MtrViewer } from "../warehouse/MtrViewer";
+import { PullTable, ShortChip, type Write } from "../warehouse/PullTable";
+import { ShortSheet } from "../warehouse/ShortSheet";
 
 export type Mutate = (
   fn: (g: Guarded) => Promise<PacketRead | null | undefined>,
@@ -35,10 +38,28 @@ const toDraft = (b: BomLine): LineDraft => ({
 
 const EMPTY_LINE: LineDraft = { qty: "", part_id: "", description: "", material: "", length: "", dwg_ref: "" };
 
-/** The BOM. Clerical may edit the lines of a hand draft (PUT /bom, full replace). */
-export function MaterialsTab({ p, mutate, busy }: { p: PacketRead; mutate: Mutate; busy: boolean }) {
+/**
+ * The BOM. Clerical may edit the lines of a hand draft (PUT /bom, full replace). The warehouse gets the pull table
+ * while the packet is with it. Anyone who may receive a short gets Receive on the line.
+ */
+export function MaterialsTab({
+  p,
+  mutate,
+  busy,
+  write,
+  reload,
+}: {
+  p: PacketRead;
+  mutate: Mutate;
+  busy: boolean;
+  write?: Write | undefined;
+  reload?: (() => Promise<void>) | undefined;
+}) {
   const editable = p.status === "draft" && p.source_kind === "hand" && p.can.includes("edit_bom");
   const [lines, setLines] = useState<LineDraft[] | null>(null);
+  const [receiveFor, setReceiveFor] = useState<number | null>(null);
+  const [viewFor, setViewFor] = useState<number | null>(null);
+  const canReceive = p.can.includes("wh_receive_short") || p.can.includes("edit_bom");
   const set = (i: number, k: keyof LineDraft, v: string) => setLines((rows) => (rows ?? []).map((r, j) => (j === i ? { ...r, [k]: v } : r)));
 
   const save = async (e: FormEvent) => {
@@ -124,6 +145,19 @@ export function MaterialsTab({ p, mutate, busy }: { p: PacketRead; mutate: Mutat
     );
   }
 
+  if (p.status === "warehouse" && p.can.includes("edit_bom") && write && reload) {
+    return <PullTable p={p} write={write} reload={reload} busy={busy} />;
+  }
+
+  const receiving = receiveFor === null ? undefined : p.bom.find((b) => b.item === receiveFor);
+  const viewed = viewFor === null ? undefined : p.bom.find((b) => b.item === viewFor);
+  const receive = async (item: number, body: Parameters<typeof packetsApi.receiveShort>[2]): Promise<string | null> => {
+    if (!write) return "Receiving is not available here.";
+    const r = await write((g) => packetsApi.receiveShort(p.id, item, body, g));
+    if (r.ok || r.err === undefined) return null;
+    return errorText(r.err);
+  };
+
   return (
     <div className="stack">
       {editable ? (
@@ -164,12 +198,29 @@ export function MaterialsTab({ p, mutate, busy }: { p: PacketRead; mutate: Mutat
                   </td>
                   <td className="small">{show(b.material)}</td>
                   <td className="small">{show(b.length)}</td>
-                  <td className="mono small">{show(b.heat)}</td>
+                  <td className="mono small">
+                    {show(b.heat)}
+                    {b.mtr_asset_id ? (
+                      <>
+                        {" "}
+                        <button type="button" className="lnk small" onClick={() => setViewFor(b.item)}>
+                          MTR
+                        </button>
+                      </>
+                    ) : null}
+                  </td>
                   <td>
-                    {b.na ? (
+                    {b.na && !b.short ? (
                       <span className="pill st-filed">N/A</span>
                     ) : b.short ? (
-                      <span className="pill st-review">{String(b.short.qty_open)} short</span>
+                      <div className="stack tight">
+                        <ShortChip s={b.short} />
+                        {canReceive && write ? (
+                          <button className="btn sm pri" type="button" disabled={busy} onClick={() => setReceiveFor(b.item)}>
+                            Receive
+                          </button>
+                        ) : null}
+                      </div>
                     ) : b.pulled ? (
                       <span className="pill st-ok">Pulled</span>
                     ) : (
@@ -184,6 +235,12 @@ export function MaterialsTab({ p, mutate, busy }: { p: PacketRead; mutate: Mutat
       ) : (
         <div className="empty">No BOM lines on this packet.</div>
       )}
+      {receiving ? (
+        <ShortSheet mode="receive" line={receiving} onClose={() => setReceiveFor(null)} onReceive={(body) => receive(receiving.item, body)} />
+      ) : null}
+      {viewed?.mtr_asset_id ? (
+        <MtrViewer assetId={viewed.mtr_asset_id} title={`MTR · item ${viewed.item}${viewed.heat ? ` · ${viewed.heat}` : ""}`} onClose={() => setViewFor(null)} />
+      ) : null}
     </div>
   );
 }
@@ -305,7 +362,7 @@ export function DocumentsTab({ p, mutate, busy }: { p: PacketRead; mutate: Mutat
     }
     setUploading(true);
     try {
-      const asset = await assetsApi.upload(file, { packet_id: p.id, purpose: "doc" });
+      const asset = await assetsApi.upload(file, { packet_id: p.id, purpose: "document" });
       const ok = await mutate((g) => packetsApi.addDoc(p.id, { asset_id: asset.id, kind, title: title.trim() || file.name, ...g }), { ok: "Document added" });
       if (ok) {
         setTitle("");