Repository navigation
feat(orders): one derived execution stage on every order endpoint - #626
Open
privatejoel wants to merge 1 commit into
Open
privatejoel wants to merge 1 commit into
privatejoel wants to merge 1 commit into
Conversation
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]>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This was referenced Oct 20, 2026
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.statuskeeps its meaning, and no status value is added (C-D3).The output shape (stable: C-10 builds on it)
orderStage(order, evidence)insrc/api/_lib/order-stage.jsreturns:stageSTAGES.STAGE_LABELSgives the label.sinceevidence_reforders.<column>,order_documents:<document id>orextraction_jobs:<job id>.holder_rolesystem,sales_engineer, the approver role (defaultsales_manager),operator(the clerk), or null.next_actionACTIONSinorder-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
receivedverifyingreturnedcorrection_reason.in_approvalapprovedresend_handoff).handed_offhandoff_status = 'sent'for the order as it is now.keyed_unverifiedtally_status = 'imported'and no Tally SO PDF (C-D4).keyedverifiedtally_status = 'reconciled'. Mode A, RECONCILED.cancelledRules:
verifying, and the next action isresubmit_for_approval.payload_hashgivesapprovedwithresend_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(theorders.payload_hashat send). If a sent handoff has no stored hash, the stage asks for a re-send.Where the stage appears
/api/orders, full andslim=1:stageon each order./api/orders/register:stageon each row./api/admin/quote_approvals?type=queue:stageon each order. The holder is the open threshold's role./api/orders/exceptions: a top-levelstage. 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 readsorder_documentsonce, not twice. An empty page reads no evidence.The next-step bar
nextStep()takes an optionalstage. 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
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/ordershandler, full and slim, with the select applied. Each order has its stage. Oneorder_documentsread and onetenant_settingsread 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 hasstage. Mode B gives keyed from one link read.home-queue.test.tsxandpipeline-kanban-card.test.tsx: their Supabase mock getsinandmaybeSinglefor the new evidence read.Mutation check. I broke each rule, saw a test fail, and restored it. 19 of 19 killed:
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
stageLabel(), the stepper, Home, Kanban and the badges. The workspace must handleresubmit_for_approvalwhen it passes the stage.sinceusesupdated_atwhen 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.received.tally_statuswhen lines change.🤖 Generated with Claude Code