Skip to content

feat(orders): the Mode B handoff, sent from the order - #630

Open
privatejoel wants to merge 3 commits into
mainfrom
feat/order-handoff-send
Open

privatejoel wants to merge 3 commits into
mainfrom
feat/order-handoff-send

Conversation

@privatejoel

@privatejoel privatejoel commented Oct 20, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

This is C-18 of docs/SO_EXECUTION_COHESION.md (R-F3), built as plan PR 16 of docs/SO_TERMS_AND_HANDOFF_SCOPE.md (section 8). The engineer sends a Mode B order to the order processing team with one click in the SO workspace. The clerk then keys the sales order into Tally.

The owner accepted all defaults of C-D11, C-D12 and C-D13. This PR applies them.

The endpoint: /api/orders/handoff

  • GET ?order_id= gives the preview: the prefill with its sources, the origin groups and their modes, the To and CC lines with a reason for each address, the subject, the body, the attachments and the blockers.
  • POST { order_id, fields?, resend? } sends. fields is { required_by, contact_name, contact_phone, modes }. A key that you do not send keeps the prefill. resend: true sends a handoff again.
  • Gate: requirePermission(ctx, "write"), then requireAction(ctx, "order.handoff"). The new action is in SERVER_ACTIONS (auth.js) and in ACTIONS (rbac.ts). Roles: sales_engineer, sales_manager, operator, admin. The route is in STATIC_ROUTES.
  • The handoff is off unless tenant_settings.order_handoff_enabled is on. It is for Mode B only. Off gives { enabled: false } on GET and 409 on POST. The flag default does not change.
  • A database without migration 251 gives 503 migration_251_not_applied. The endpoint never reads that as "not handed off".

The five R-F3 changes

  1. Direct send. The row starts as a draft, and sendCommunication sends it in the same request. The reaper reads only queued rows, so it cannot send this row. With no mail provider, the order shows not_configured, and the row becomes failed with metadata.error = "no_provider_at_send". The screen says "Not sent: no mail provider".
  2. Reply-to. Reply-to is the engineer who sends the handoff. This is the owner's change to C-D12, until C-33 exists: a clerk's reply to the tenant's inbound address would enter the Postmark pipeline as a new PO. The engineer is also in CC. The subject has the PO number. The Graph branch of sendCommunication now passes reply_to (buildGraphMessage sets replyTo).
  3. Records. The send writes handoff_status, handoff_sent_at, handoff_sent_by (ctx.user.id), handoff_comm_id, handoff_payload, dispatch_plan, and dispatch_mode when there is one origin group. handoff_payload.payload_hash is the order's payload_hash at send. This is the contract with C-9 (feat(orders): one derived execution stage on every order endpoint #626).
  4. Changed since handoff. When the order's payload_hash moves after the send, the workspace chip and the register say "Changed since handoff". The button becomes "Re-send handoff". The rule is the same as in order-stage.js (C-9).
  5. Customer acknowledgement. Not built. It is for later.

The decisions (C-D11, C-D12)

  • The handoff can occur before approval. These blockers gate it, and the server calculates them again on POST: an undecided critical terms flag (409 TERMS_UNDECIDED), a blank material required date, a blank contact name, an origin group with no mode or with a mode that is not in its group, an unresolved blocking finding, a CANCELLED, DUPLICATE, REUSED or BLOCKED order, no lines, and no To recipient (409 HANDOFF_BLOCKED).
  • The email has no prices and no clause wording. It attaches the SO PDF and the original PO.
  • Origin precedence: the part-string marker, then the quote line's source_country, then the item master. If two strong signals do not agree, the line goes to unknown. The item master is weak: it is read only when no other signal exists.
  • Ship modes: import is ocean (default) or air. Local is road (default), hand carry by the customer, or hand carry by our engineer. Unknown has no default. The Header tab select gets the two hand-carry modes.
  • Required-by is the PO date. The committed date shows beside it with its source.
  • A second POST on a sent handoff gives the first result. "Send again" needs a confirm in the modal and passes resend: true.

Other changes

  • src/api/_lib/so-document.js: the SO PDF builder and its loader move here from orders/so_pdf.js. The download and the handoff render the same PDF. so_pdf.js re-exports the builder. When a dispatch plan has more than one group, the PDF prints "As per dispatch plan".
  • Register: the Handoff column (not sent; sent at and by; failed; not configured; changed since handoff) and a "not handed off" filter. The response does not include the handoff payload's contact.
  • terms/check.js exports poDocumentOf, so the handoff finds the original PO the same way.

Deploy notes

  • No migration. Migration 251 has all the columns (it was applied on 2026-10-13).
  • The feature ships off. C-D13 turns on order_handoff_enabled for the pilot after this PR and the shadow week.
  • Before you turn it on, configure a mail provider (Graph, or the mailer keys) and the To list (Admin > Order handoff). Without a provider, the send says "Not sent: no mail provider" and nothing goes out.

Tests

New:

  • src/v3-app/api-orders-handoff.test.js: the parity of order.handoff, the role gate, flag off, Mode A, migration 251 missing, the preview and its sources, the send, no prices, the actor is ctx.user.id, the stored payload_hash, the audit has no contact data, the dispatch plan and the PDF label, the second click and Send again, every blocker, terms (critical blocks, high does not, shadow does not), origin precedence, and tenancy.
  • src/v3-app/api-orders-handoff.send-direct.test.js: the row is inserted as a draft and is never queued; not_configured with no provider; a provider refusal is failed.
  • src/v3-app/api-orders-handoff.reply-to.test.js: replies go to the engineer who sends (an operator's send replies to the operator); with a Postmark inbound address or a watched Outlook mailbox set, replies still go to the engineer; the real Graph message carries the engineer as replyTo.
  • src/v3-app/api-orders-handoff.changed-since.test.js: the hash moves, then a re-send stores the new hash.
  • src/v3-app/api-order-register.handoff-column.test.js: the column, the filter, no contact data, the export words.
  • src/v3-app/components/OrderHandoffButton.test.tsx: hidden when off or for a role without the action, sends the edited fields, the confirm for Send again, the server's blockers.
  • src/v3-app/test-support/handoff-harness.js: the shared in-memory stand-in for the endpoint tests.

Changed: screens/so-register.test.tsx (the new not_handed_off parameter).

Follow-up commits on this branch: 9ca9aa7f (reply-to is the engineer; the SO PDF prints "-" for a blank description and seller name; part-origin.js exports ORIGIN_COUNTRY) and 40fd3918 (the part-origin comments name no tenant and use no em dashes; no code change).

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

  1. requireAction removed.
  2. order.handoff missing from SERVER_ACTIONS.
  3. The flag off is ignored.
  4. The Mode B check is removed.
  5. An undecided critical flag is ignored.
  6. An undecided high flag blocks too.
  7. A price is in the email.
  8. The actor is ctx.userId.
  9. The payload hash is not stored.
  10. The row is inserted as queued.
  11. A queued row stays queued.
  12. A queued result is reported as sent.
  13. Reply-to is the Postmark inbound address (2 tests fail). 13b. Reply-to is the watched Outlook mailbox (1 test fails).
  14. The Graph branch drops reply_to.
  15. buildGraphMessage drops replyTo.
  16. "Changed since" is never true.
  17. The register keeps the placeholder.
  18. The "not handed off" filter is removed.
  19. The order read has no tenant filter.
  20. The second click sends again.
  21. A blank required date does not block.
  22. The unknown group defaults to road.
  23. A mode outside its group is allowed.
  24. A blocking finding is ignored.
  25. The item master overrides a part marker.
  26. Disagreeing signals do not give unknown.
  27. dispatch_mode is written for a mixed order.
  28. The PDF ignores the dispatch plan.
  29. The contact goes into the audit.
  30. The "entered" source label is lost.
  31. No recipient does not block.
  32. Send again has no confirm.
  33. The button shows for every role.

Gates:

  • npm run check: pass.
  • npm run lint: 0 errors (the warnings were there before; three move with the code to so-document.js).
  • npm run build: pass. I deleted the build outputs.
  • npm run verify: pass. It rewrote docs/RBAC_AUDIT.md and docs/WRITE_PATH_AUDIT.md with drift that is on main too. I restored both and kept only the new orders/handoff.js | write row in RBAC_AUDIT.md.
  • npm run eval:golden: pass, aggregate 1.000.
  • NODE_OPTIONS=--no-experimental-webstorage npx vitest run: 632 files, 7418 tests, all pass (run again on 40fd3918).

Not covered

  • The customer acknowledgement (R-F3 change 5).
  • The "keyed in ERP" record that closes the handoff (R-F2, C-12). The stage (C-9) reads this PR's columns.
  • order_handoff_sender is not read. sendCommunication uses Graph when it is connected, else the mailer (decision 4 default).
  • order_handoff_template is not read. The template is the decision 5 default.
  • The matched source PO prefix is not an origin signal yet. It exists only after procurement.
  • The SO PDF line table does not print a mode for each line. The email does.
  • The "not handed off" filter does not find a sent handoff that changed since. The column shows it.
  • A second To address goes in CC, because communications.to_addr holds one address.
  • The SO PDF goes on the row as inline base64. It is not kept as a document.
  • Two POSTs in the same second can both send. The button is disabled while a send runs.
  • The engineer cannot pick a different customer contact from a list. They can type the name and phone.
  • The modal preview shows the prefilled values. The email uses the values in the form.
  • Reply-to goes to the tenant inbound address only after C-33 joins a clerk reply to its order (shortcut: in orders/handoff.js).
  • fix/honest-send-status (fix(ui): show only what the server confirmed, and say when the worker is down #623) also changes comms-send.js. This PR changes only the Graph call line, which fix(ui): show only what the server confirmed, and say when the worker is down #623 does not touch.

🤖 Generated with Claude Code

This is C-18 (plan PR 16, R-F3). The engineer sends the order to the
order processing team with one click in the SO workspace. The clerk
then keys the sales order into Tally.

- New endpoint /api/orders/handoff. GET gives the preview. POST sends.
  The gate is write, then the new action order.handoff (sales_engineer,
  sales_manager, operator, admin). The action is in SERVER_ACTIONS and
  in rbac.ts ACTIONS.
- The handoff is off unless order_handoff_enabled is on. It is for
  Mode B only. The flag default does not change.
- The send is direct, through sendCommunication. The row starts as a
  draft, so the reaper cannot send it. With no mail provider, the
  order shows not_configured and the row becomes failed.
- Reply-to is the tenant's Anvil inbound address when one exists.
  Else it is the engineer. The engineer is in CC. The Graph branch of
  sendCommunication now passes reply_to.
- The send writes handoff_status, handoff_sent_at, handoff_sent_by
  (ctx.user.id), handoff_comm_id, handoff_payload, dispatch_plan, and
  dispatch_mode for one origin group. handoff_payload.payload_hash is
  the order's payload_hash at send (the contract with C-9).
- An undecided critical terms flag blocks the send (409
  TERMS_UNDECIDED). Blank required fields, a missing mode, a blocking
  finding, a bad status or no recipient also block it.
- The email has no prices. It attaches the SO PDF and the original PO.
- The SO PDF builder and loader move to _lib/so-document.js, so the
  download and the handoff render the same PDF.
- The register shows the handoff column and a "not handed off" filter.
  The workspace and the register show "changed since handoff".

No migration. Migration 251 has the columns.

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 21, 2026 2:20am UTC

…l origin map name

The owner made three changes to the handoff (C-18).

- Reply-to is now the engineer who sends the handoff, until C-33
  exists. A clerk's reply to the tenant's inbound address would enter
  the Postmark pipeline as a new PO. The engineer stays in CC. The
  Graph branch still passes reply_to. The email no longer has the
  "reply to all" text.
- The SO PDF prints "-" (not an em dash) for a blank description and a
  blank seller name.
- part-origin.js exports ORIGIN_COUNTRY. order-handoff.js was the only
  importer outside that file.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…ents

The comments in part-origin.js named the tenant and used em dashes. This
PR touches the file, so the comments now use neutral words and colons.
The code does not change.

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

This branch was successfully deployed

1 active deployment
Preview — 40fd3918 Deployed Oct 21, 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