Skip to content

feat(v3): every screen reads the stage and one money helper - #629

Open
privatejoel wants to merge 1 commit into
feat/order-stagefrom
feat/screens-read-stage
Open

privatejoel wants to merge 1 commit into
feat/order-stagefrom
feat/screens-read-stage

Conversation

@privatejoel

Copy link
Copy Markdown
Collaborator

Stacked on #626. Merge #626 first.

Summary

This is C-10 of docs/SO_EXECUTION_COHESION.md (R-M1). Every order screen now reads order.stage, which #626 sends. One label and one value come from one helper module.

Helpers in src/v3-app/lib/helpers.ts:

  • stageLabel(key) uses STAGE_LABELS from src/api/_lib/order-stage.js. The client does not copy the labels.
  • stageKeyOf(o) and stageChip(o) read o.stage. If an endpoint sends no stage, they read the status (Mode A, no handoff or ERP evidence).
  • awaitsAction(o) is true while the order has a next move: not verified, not cancelled, not parked.
  • orderValue(o, lines?) and fmtOrderValue(o, { compact, lines }) give the printed grand total, else the sum of the line totals, in the order currency. orderValue is in src/api/_lib/order-value.js, so the server uses the same code.

What changes for a person:

  • Labels. stageOf() and its status map are gone. "approval" for APPROVED, "shipped" for RECONCILED, and the per-screen maps are gone too. Home, the SO list, the Kanban, the Register, Tally push, Tally reconcile, the gun viewer and the thread drawer show the same stage label. A status that the stage hides shows as a note, for example "Verifying, blocked" or "Approved, push failed".
  • Home "My queue". The queue counts from the stage, and it counts before it takes 8 rows, so 30 open orders show 30. A verified or cancelled order leaves the queue. A Mode B order that is done in Tally also leaves it. "Oldest" is now the oldest order, not the newest. "In approval" counts the in_approval stage.
  • Nav badges. SO counts orders with a next move. A RECONCILED order is no longer active. Approvals counts in_approval. Intake counts received, verifying and returned.
  • SO list. There is one tab for each stage. A stage with no orders has no tab. "In flight" uses awaitsAction.
  • Kanban. Each column holds stages. A Mode B order that is handed off goes to Push. A keyed or verified order goes to Closed. BLOCKED, DUPLICATE and REUSED stay in Validate, and FAILED_TALLY_IMPORT stays in Push. When you drop a card, it moves at once (the old server stage is cleared until the next load).
  • SO workspace. The stage comes from GET /api/orders/exceptions. If that call fails, the screen runs the same pure orderStage() on the order. nextStep() gets the stage.
    • The stepper reads the stage. When a later edit clears an approval, Approve is not done. A Mode B order that is keyed in Tally completes the stepper.
    • The next-step bar shows at every stage. resubmit_for_approval (an edit after the approval) sends PATCH DRAFT, then PENDING_REVIEW. The other stage-only steps show their label on a disabled button.
  • Money. The duplicate formatters are gone: fmtMoney in the Kanban and in Pending SOs, and the local money in the workspace. A scanned PO with no grand total now has the same value on the list, Home, the Kanban, the approvals drawer and queue, the Register and the workspace. The workspace header now adds tax, the same as the line grid footer (it summed taxable only before).
  • Pending SOs. The open value is rate x balance quantity. Before, it was rate x ordered quantity.

On the server, the line math moves from src/v3-app/lib/line-totals.ts to src/api/_lib/line-totals.js (the TS file now only re-exports it). The approvals queue (value_inr) and the Register (value) call orderValue().

Shortcuts (each one has a shortcut: comment):

  • helpers.ts: a row with no stage is read from its status alone. Upgrade when every order endpoint sends stage.
  • home.tsx: the queue counts the newest 50 orders for the whole tenant. Upgrade when the C-14 worklist serves "waiting on me".
  • order-value.js: orderGrandTotal (the win/loss rollups) still calculates its own value. Upgrade when the rollups must match the screens.

Deploy notes

  • No migration. No new RBAC action. No environment change.
  • Built assets are not committed.

Tests

New tests:

  • src/v3-app/lib/helpers-stage-label.test.ts: labels, stage over status, the status fallback, notes, awaitsAction, orderValue and currency.
  • src/v3-app/screens/home-mode-b-queue.test.tsx: a verified or cancelled Mode B order leaves the queue. 30 open orders count as 30, the table shows 8 rows, and "oldest" is 30 days.
  • src/v3-app/lib/telemetry-badges.test.ts: the SO, Approvals and Intake badges count from the stage.
  • src/v3-app/screens/so-workspace-stepper.test.tsx: a verified Mode B order completes the stepper. The server stage wins. A cleared approval stops at Approve. The resubmit sends DRAFT, then PENDING_REVIEW.
  • src/v3-app/screens/order-value-list-workspace.test.tsx: a PO with no grand total shows 236 on the SO list and in the workspace.
  • src/v3-app/screens/orders-stage-tabs.test.tsx: the SO list files each order under its stage tab.
  • src/v3-app/api-pending-sales-orders-value.test.js: the real handler values a line at rate x balance.
  • src/v3-app/screens/pipeline-kanban.test.tsx (new describe): columns come from the stage, and a dropped card that has a server stage moves at once.

Updated assertions (intended label and format changes): the Register row labels, the Kanban card note and value (₹ 120k), the workspace summary value (₹1,500.00), the RECONCILED workspace bar (it is now present, with action none), and the stageOf unit tests (removed with stageOf).

Mutation check. I broke each rule, saw a test fail, and restored the rule:

# Mutation Failed
M1 stageKeyOf ignores o.stage helpers, Home
M2 awaitsAction ignores next_action: none helpers, badges
M3 Home takes 8 rows before it counts Home
M4 Home "oldest" is the first row Home
M5 Intake badge counts in_approval badges
M6 Stepper Approve reads status === APPROVED stepper
M7 Workspace ignores the server stage stepper
M8 Resubmit skips the DRAFT move stepper
M9 orderValue has no line-sum fallback helpers, list/workspace
M10 Pending value uses the ordered quantity pending API
M11 A dropped card keeps its old stage Kanban
M12 Kanban columns by status only Kanban
M13 SO list tabs by status SO list tabs
M14 Home queue filters by status (RECONCILED, CANCELLED) Home

Gates:

  • npm run check: pass.
  • npm run lint: 0 errors. The warnings were there before.
  • npm run build: pass. I deleted the outputs.
  • npm run verify: pass. I restored docs/RBAC_AUDIT.md and docs/WRITE_PATH_AUDIT.md. Their changes were drift from earlier work, not from this change.
  • npm run eval:golden: pass.
  • NODE_OPTIONS=--no-experimental-webstorage npx vitest run --maxWorkers=2: 636 files and 7432 tests pass.

Not covered

  • The lists never show "Received". Only the one-order exceptions endpoint reads the extraction job (this is a C-9 shortcut).
  • The workspace fallback (when the exceptions call fails) does not know about an attached ERP SO or an extraction job.
  • The Register status filter still filters by status. Its options show the stage label next to each status.
  • "Mine" and per-user queues wait for C-14 and the owner column (R-F4).
  • The win/loss rollups (orderGrandTotal) keep their own value calculation.
  • The approvals queue column is still named value_inr, and it shows the value in INR.

🤖 Generated with Claude Code

Every order screen now reads order.stage, which C-9 sends. One set of
helpers in lib/helpers.ts gives the label and the value:

- stageLabel(key) uses STAGE_LABELS from the server stage module.
- stageKeyOf(o) and stageChip(o) read o.stage. If an endpoint sends
  no stage, they read the status.
- awaitsAction(o) is true while the order has a next move.
- orderValue(o, lines?) and fmtOrderValue(o, opts) give the value: the
  printed grand total, else the sum of the line totals, in the order
  currency.

The per-screen status maps and money formatters are gone. Home, the
SO list, the Kanban, the Register, the approvals drawer, Tally push,
Tally reconcile, the gun viewer and the thread drawer use the helpers.

Home "My queue" counts from the stage before it takes 8 rows. A
verified or cancelled order leaves the queue. "Oldest" is the oldest
order. The nav badges count from the stage.

The SO list has one tab for each stage. The Kanban puts each order in
a column by its stage. A Mode B order that is handed off, keyed or
verified moves out of Approve.

The SO workspace reads the stage from GET /api/orders/exceptions, else
from orderStage() on the order it holds. The stepper reads the stage.
The next-step bar shows at every stage. When an edit clears the
approval, the bar sends the order to DRAFT and then for approval
again.

The server uses the same value. The line math moves to
src/api/_lib/line-totals.js, and orderValue() is added to
_lib/order-value.js. The approvals queue and the Register use it.
Pending SOs give the open value as rate x balance quantity, not rate
x ordered quantity.

No migration.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@vercel

vercel Bot commented Oct 20, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
anvil Ready Ready Preview Oct 20, 2026 4:44am UTC

This branch was successfully deployed

1 active deployment
Preview — 142db040 Deployed Oct 20, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant