Skip to content

feat(orders): one derived execution stage on every order endpoint - #626

Open
privatejoel wants to merge 1 commit into
mainfrom
feat/order-stage
Open

privatejoel wants to merge 1 commit into
mainfrom
feat/order-stage

Conversation

@privatejoel

Copy link
Copy Markdown
Collaborator

Summary

This is C-9 (R-M1) of docs/SO_EXECUTION_COHESION.md. Each order now has one execution stage. The server derives the stage from records that exist today. Every order endpoint returns the same stage. Nothing is written. orders.status keeps its meaning, and no status value is added (C-D3).

The output shape (stable: C-10 builds on it)

orderStage(order, evidence) in src/api/_lib/order-stage.js returns:

{ stage, since, evidence_ref, holder_role, next_action }
Field Meaning
stage A key of STAGES. STAGE_LABELS gives the label.
since The ISO time that the order entered the stage, or null.
evidence_ref The record that puts the order in the stage: orders.<column>, order_documents:<document id> or extraction_jobs:<job id>.
holder_role The role that must do the next step: system, sales_engineer, the approver role (default sales_manager), operator (the clerk), or null.
next_action A key of ACTIONS in order-next-step.js.

Evidence: { mode: "A" or "B", erp_so: [{ document_id }] or null, extraction_job: { id, created_at } or null, approver_role }.

The stage keys

Key Label When
received Received A background extraction job is in flight.
verifying Verifying DRAFT, BLOCKED, DUPLICATE or REUSED. Also an approved order whose approval a line edit cleared (the revision rule).
returned Returned for correction DRAFT with correction_reason.
in_approval In approval PENDING_REVIEW. A handoff or a keyed entry before approval does not move it on (C-D11).
approved Approved Approved. In Mode B, not handed off yet, or changed since the handoff (next action resend_handoff).
handed_off Handed off Mode B, handoff_status = 'sent' for the order as it is now.
keyed_unverified Keyed, unverified Mode B, tally_status = 'imported' and no Tally SO PDF (C-D4).
keyed Keyed in ERP Mode B, a Tally SO PDF is attached. Mode A, EXPORTED_TO_TALLY.
verified Verified in ERP Mode B, tally_status = 'reconciled'. Mode A, RECONCILED.
cancelled Cancelled CANCELLED.

Rules:

  • Keyed needs the approval. Keyed evidence also closes the handoff: an entry from the clerk shows that the order got to the clerk.
  • A line edit clears the approval and keeps status APPROVED. The stage goes back to verifying, and the next action is resubmit_for_approval.
  • A sent handoff whose stored hash is not the current payload_hash gives approved with resend_handoff. This is before keyed and verified, so a clerk does not key old lines.

Contract for C-18

The handoff must write handoff_payload.payload_hash (the orders.payload_hash at send). If a sent handoff has no stored hash, the stage asks for a re-send.

Where the stage appears

  • GET /api/orders, full and slim=1: stage on each order.
  • GET /api/orders/register: stage on each row.
  • GET /api/admin/quote_approvals?type=queue: stage on each order. The holder is the open threshold's role.
  • GET /api/orders/exceptions: a top-level stage. Only this endpoint reads the in-flight extraction job.

No N+1. A list reads the mode once and reads the ERP SO links in one chunked read (100 ids for each .in()). The register uses the same link read for its voucher numbers, so it reads order_documents once, not twice. An empty page reads no evidence.

The next-step bar

nextStep() takes an optional stage. With a stage, it gives an answer at every stage: the handoff, the Tally entry, the PDF and the check show with the button off, because no call in this PR does them. Verified and cancelled show "No next step ()". A revised order gets "send for approval again" (DRAFT, then PENDING_REVIEW). Without a stage, the status decides, as before. The workspace does not pass the stage yet (C-10).

Deploy notes

  • No migration.
  • The selects read columns from migrations 001, 005, 104 and 251. All of them are live.
  • No new endpoint, no new requireAction, no RBAC change.

Tests

New:

  • src/v3-app/api-order-stage.test.js: each stage from fixtures, Mode A and Mode B, handoff before and after approval, returned, revised after handoff, cancelled, manual exit unverified, received, and the next-step bar at every stage.
  • src/v3-app/api-orders-list-stage.test.js: the real GET /api/orders handler, full and slim, with the select applied. Each order has its stage. One order_documents read and one tenant_settings read for a page. 150 orders give 2 chunked reads. An empty page reads no evidence. Another tenant's ERP SO never counts.
  • src/v3-app/api-order-stage-endpoints.test.js: the approvals queue and GET /api/orders/exceptions.

Changed:

  • api-orders-register.test.js: the row has stage. Mode B gives keyed from one link read.
  • home-queue.test.tsx and pipeline-kanban-card.test.tsx: their Supabase mock gets in and maybeSingle for the new evidence read.

Mutation check. I broke each rule, saw a test fail, and restored it. 19 of 19 killed:

  1. An approved order with a cleared approval counts as approved.
  2. An ERP SO before approval reads as keyed.
  3. Changed since handoff is not checked.
  4. The manual exit is checked before the PDF.
  5. Mode B never reaches verified.
  6. A failed handoff counts as sent.
  7. Mode A reads the Mode B evidence.
  8. Returned is not told apart from verifying.
  9. Cancelled is not checked first.
  10. Received is never reached.
  11. The approver role is ignored.
  12. nextStep ignores the stage-only actions.
  13. nextStep ignores the revision.
  14. nextStep lets a failed import go back to DRAFT.
  15. The evidence is read for each order, not in a batch.
  16. Any linked document counts as an ERP SO.
  17. An empty page still reads evidence.
  18. The in-flight job read has no tenant filter.
  19. The slim select does not have the stage columns.

Gates:

  • npm run check: pass.
  • npm run lint: 0 errors (the warnings were there before).
  • npm run build: pass.
  • npm run verify: pass. It rewrote docs/RBAC_AUDIT.md and docs/WRITE_PATH_AUDIT.md with drift that is not from this change. I restored both.
  • npm run eval:golden: pass, aggregate 1.000.
  • vitest run --maxWorkers=2: 629 files, 7405 tests, all pass.

Not covered

  • Screens do not read the stage yet. C-10 adds stageLabel(), the stepper, Home, Kanban and the badges. The workspace must handle resubmit_for_approval when it passes the stage.
  • since uses updated_at when no column records the start of the stage (in approval, revised, keyed, verified, cancelled). A later write moves it. C-27 can read the audit rows.
  • The lists do not read extraction jobs, so only the exceptions endpoint shows received.
  • If the order changes after a keyed or verified entry and there is no handoff record, the stage does not see it. C-12 must reset tally_status when lines change.
  • Sourced, Dispatched and Invoiced are later lanes and are not in this PR.

🤖 Generated with Claude Code

Add src/api/_lib/order-stage.js. It is pure and writes nothing. It
returns { stage, since, evidence_ref, holder_role, next_action } for
one order, from the order row and the evidence that the endpoint read.

The stage keys are received, verifying, returned, in_approval,
approved, handed_off, keyed_unverified, keyed, verified and cancelled.
STAGE_LABELS gives the label for each key.

Mode A reads EXPORTED_TO_TALLY as keyed and RECONCILED as verified.
Mode B reads the handoff columns, tally_status and an attached Tally
SO PDF. Keyed needs the approval. A line edit clears the approval, so
the order goes back to verifying. A change since the handoff asks for
a re-send.

GET /api/orders (full and slim), /api/orders/register, the approvals
queue and /api/orders/exceptions return the stage. A list reads the
mode once and the ERP SO links in one chunked read. The register uses
the same link read for its voucher numbers.

nextStep() takes the stage, so the next-step bar has an answer at
every stage. Without a stage, the status decides as before.

No migration. No new order_status value.

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

vercel Bot commented Oct 19, 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 19, 2026 4:03pm UTC

This branch was successfully deployed

1 active deployment
Preview — 07041c53 Deployed Oct 19, 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