[goetchstone]

Summary

PR 4 of the stock-ledger plan (docs/domains/inventory.md → "Roadmap", phases 15–20): the warehouse floor on a handheld. Receiving, counting, put-away, picking and loading now happen where the stock is, through the same ledger functions as the desk, and each scan is done once however often a bad connection resends it. Delivery runs can now record what actually happened at a stop: a part delivery, a stop that could not be done, or a return collected on the way.

It also removes SonarQube at the owner's direction: the local server was not being run, and CodeQL in CI covers the analysis.

What is in it

• Scanner pages under /app/scan (lookup, receive, count, move, pick). Each sits behind the permission of the desk screen that does the same job. One resolver reads Holt's place labels (L-<id>), box labels (B-<product>-<box>-<of>), UPCs, consignment barcodes, product numbers and place codes. A retry key (withAction, StockAction) makes each handheld write happen once.
• Labels: place and box labels, plus one renderer for every label with ZPL escaping. A label routes only to its own store's printer.
• Boxes are evidence, never a quantity (DECISIONS TypeScript is strict across the whole tree, not five files: strict: true plus noImplicitReturns, noImplicitOverride, noFallthroughCasesInSwitch #22). A unit short of boxes is received into quarantine with a note naming what is missing; it moves to stock when the last box arrives.
• Count by place (DECISIONS An order's balance counts only the lines still owed: cancelled and replaced lines no longer charge the customer #21). Counting needs inventory.count; posting needs inventory.adjust and moves the difference as ADJUST movements, free stock first. The Oversold report shows the last count's difference. The store-grain count stays as the POS cutover tool.
• Put away and move (quick moves only; committed units keep their order) and pick to the loading bay, then load the run.
• Delivery outcomes (DECISIONS Merge train: #15 #18 #14 #16 #17 #19 #20 #21 #22 in one CI run (merge commit, not squash) #23):
  • A part delivery hands over only what went and raises fulfilledQty. The rest stays committed, and a DELIVERY appointment for it goes back in the dispatch pool. The last units are the handover.
  • A stop that could not be done comes off the run, with the reason on the order.
  • A return's pickup is a run stop (RETURN_PICKUP), added from the pickup schedule.
• Migration 20261020120000_handheld_floor: additive only.

Found while checking it in a browser, fixed here

• The driver screen could not complete any stop. "Mark Arrived" sent PENDING → ARRIVED, which the transition table refused, and nothing sets EN_ROUTE. PENDING → ARRIVED is now allowed.
• A failed stop whose appointment was IN_PROGRESS dropped out of the dispatch pool.
• A place or box label for a store with no printer printed at another store's printer. It now refuses and names what to set up (rule 63).
• "Transfer it first" compared a delivery's units with the store the order was sold at, not where it leaves from.
• A count of a place at another store than the scanner's store picker was refused.
• Demo seed: committed stock and order-linked transfers used products that were not on the order, and the open delivery runs carried orders that were already delivered. Picking and delivery could not be shown at all.

Trace / Verification

• Trace (rule 45). The only shared-infrastructure file touched is lib/auth/pagePermissions.ts: 11 added lines (the scanner pages and two admin pages). PAGE_ACCESS is read by pagePermissions.test.ts, which checks every page under (dashboard)/app has an entry. Nothing under lib/adapters, paymentService, secureUpload or automations changed.
• Migration. migrate deploy into an empty database, then npm run setup -- --scale=ci --no-cms, then prisma migrate diff --from-config-datasource --to-schema --exit-code: "No difference detected". seed:coverage passes on it. Rebased onto main after Returns money: refund to the original payment or to store credit, restocking fees, and a return that books as its own order #33; both migrations apply in order.
• Browser, on a demo-seeded scratch database (keyboard input standing in for a scanner, at phone width), each with the database checked afterwards:
  • Lookup: by product and by place label.
  • Receive: two lines received; status RECEIVED_PARTIAL; the movement carries its action key.
  • Count: a quick count posted; free stock removed first, the order's unit kept.
  • Move: a cross-store move refused with "start a transfer"; a same-store move done.
  • Pick: picked to a loading bay; "Load the truck" refused with what is left.
  • Driver: a part delivery (one line of five), "Couldn't deliver" with a reason, and a return pickup completed.
  • Pickup schedule: "Add to run".
  • Place label: the refusal message.
• Mutation-checked (13). Each was reintroduced, its test failed, and the file was restored:
  • open quantity ignoring fulfilledQty;
  • the stop not claimed before completing;
  • pickup stops on the pull list;
  • the any-store printer fallback;
  • PENDING → ARRIVED refused;
  • the pool dropping IN_PROGRESS;
  • delivery cross-site checked against the sale store;
  • a delivery of nothing accepted;
  • a part delivery consuming nothing;
  • a pickup completed as a handover;
  • an incomplete set picked;
  • a count taking committed stock before free;
  • the retry key doing the work twice.
• Unverified (rule 58).
  • A real Zebra (DataWedge, keystroke output) on HTTPS staging. The pages have only seen keyboard input in a desktop browser.
  • Printing on a real label printer. Only the refusal and printer-timeout paths ran here; there is no printer.
  • Offline behaviour beyond "the request fails, and resending is safe".

Scan / gate state

npm run check:local, run on the final branch tip after rebasing onto main (it is five steps now that SonarQube is gone):

Check	Result
validate (lint, typecheck, format)	clean; 0 errors (lint warnings are the existing ones, plus nested-ternary and complexity warnings in the new scanner pages)
test:coverage	3,985 unit tests pass (14 skipped); 111 integration files, none failing; merged coverage thresholds met
markdownlint	clean
Semgrep	clean (no ERROR findings)
OSV	skipped: the lockfile did not change
CodeQL	runs in CI on this PR

Deferred (rule 50)

Listed in docs/domains/inventory.md → "The handheld floor" and tracked in the owner's ROADMAP.md → "Handheld floor (left by ledger-plan PR 4)":

• an offline outbox;
• the SCANNED move mode;
• a truck place per run;
• the store-grain count's whole-number columns;
• the stop and run-status routes still on role lists;
• a run that can be completed with stops open;
• return pickups suggested by the run planner.

Test plan

• On a phone-width browser, /app/scan/lookup: scan a product number, then a place label L-<id>.
• Create a STAGING place, then on /app/scan/pick pick a run's unit to it. The pull list shrinks; "Load the truck" refuses while rows remain.
• On /app/dispatch/driver, mark a stop arrived and complete it with one line set to 0. The order stays open, and a new DELIVERY appointment appears in the unassigned pool.
• "Couldn't deliver" on another stop: it leaves the run, and the reason shows on the order's change log.
• On /app/warehouse/pickups, add a pickup to a run, then complete it on the driver screen. The return reads PICKUP_COMPLETED.
• Before a store relies on any of this: run receive, count, move and pick on a Zebra against HTTPS staging.

🤖 Generated with Claude Code