Operator-driven soft delete at item scope — flips item_status to
'cancelled' rather than removing the PB row, so any PO / DN /
invoice history the line carries is preserved for audit.
Mirrors cancelOrder's blocked-status list (delivered / invoiced /
cancelled): a line that's already reached the customer can't be
soft-deleted without orphaning the customer-facing record — a UI
gate should prevent the call from reaching the service, but the
service gate is the last line of defence.
The exclude_from_invoice flag doesn't affect eligibility — a normal
line and a non-invoiceable extra cancel the same way. The flag
only governs what reaches the customer invoice / delivery note.
When an actor is supplied, stamps [ISO timestamp] cancelled by
{name|id} on the row's notes field (appended, not replaced — preserves
any operator note that was already on the line). Soft delete leaves
a full audit trail in PB.
5 tests + 1 mutation-test prove:
- pending → cancelled (happy path)
- 404 when order doesn't exist
- 404 when item belongs to a different order
- 409 when item is already terminal (invoiced)
- actor stamp lands on notes
- mutation (don't flip the status): the happy-path test fails
Co-Authored-By: Claude <noreply@anthropic.com>
Three documents behind the two features on this branch:
- specs/2026-08-30-non-invoiceable-order-extras-design.md — the design
the implementation followed, including why the flag must be named for
the exception (a positively-named field defaults to false and would
mark every existing row non-billable the moment it is created).
- plans/2026-08-30-non-invoiceable-order-extras.md — the task-by-task
plan, now fully implemented.
- specs/2026-08-30-quantity-handling-audit.md — the order_qty /
quantity audit that produced the preceding fix, plus the partial
collection findings that are still open.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Review follow-up to the non-invoiceable-extras work. Task 6 of the plan
called for the billable-subset guard on `sendToQuickBooks` as well as
in the modals; it landed in the modals only.
`rows.length === 0` counts excluded rows, which ride along for the n8n
status flip but never bill. A group where every row is excluded passes
that check and ships an empty `items` array, so QuickBooks would create
a zero-line invoice while n8n still flipped every row to `invoiced`.
Not reachable through the current UI — both live modals disable submit
on this case. This is defence-in-depth for the callers that bypass
them: the (currently unrendered) bulk modal and any legacy call passing
`overrides: undefined`, which falls back to every row in the group.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`order_items.order_qty` is the SUPPLIER-facing quantity — what prints
on the PO. Five call sites read it as the customer quantity, which is a
money bug in both directions:
- supplier MOQ (customer 4, we buy 10) → invoiced 10, over-billing 6
- shorted line (customer 100, supplier covers 40) → invoiced 40,
under-billing 60 until the operator splits the remainder
The invoicing screen never fetched `quantity` at all (zero occurrences
in page.tsx), so it could not bill the customer quantity even in
principle. Added to the PB field projection, which is load-bearing:
drop it and PB returns undefined and every line silently falls back to
order_qty. A page-level test now fails if the projection drifts.
`maxSurplusFor` measured the surplus as `collected - order_qty`, which
on an MOQ line is always 0 — the overflow was mathematically unbookable
and vanished from inventory by construction, not by operator error.
Four call sites built delivery-note lines by hand; two passed
`quantity` and two forgot it, so the same DN printed the customer's 4
via the service layer and the supplier's 10 via the API routes. All
four now share `buildDeliveryNoteLine`, so they cannot diverge again.
`order_qty` had no doc comment at all next to an 11-line one on
`quantity` — that absence is why five subsystems guessed differently.
Now documented, with a new `src/lib/order-item-qty.ts` holding
`customerQty` / `supplierQty` as the single definition.
driver-stops.ts and collection-confirm/po-card.tsx read `order_qty`
CORRECTLY (they check what the supplier delivered against what we
ordered from them) and carry comments saying so, so the next cleanup
doesn't "fix" them into breaking.
23 new tests. Full suite: no regressions — the 15 failures are
identical before and after (verified by stashing and re-running).
Audit: docs/superpowers/specs/2026-08-30-quantity-handling-audit.md
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Task 9 of the non-invoiceable-order-extras plan.
order_items.create MCP tool:
- Input schema gains an optional boolean 'exclude_from_invoice'.
- Tool description rewritten to explain the supplier-side component
use case, the PO + driver + collection flow, the silent drop from
the customer invoice and delivery note, and the force-zero selling
price.
- operationData hint / nextActions block updated — the prior text
documented a '409 order_locked' refusal that no longer fires
(Task 2 removed the pending gate).
- Handler forwards the boolean to createOrderItemForOrder (which
itself forces selling_price=0 when the flag is set — Task 2).
Also fixed a TypeScript strict-mode complaint in the T7 test that
the previous commit left behind (vi.fn mock-call tuple type
needed an explicit parameter so mock.calls[0] is typed).
Co-Authored-By: Claude <noreply@anthropic.com>
Task 8 of the non-invoiceable-order-extras plan.
Two regression tests, no production code change. The picking-slip
feature relies on a property of the existing print pipeline:
excluded rows DO receive item_status = 'invoiced' (Task 7 / n8n
batch flip) and DO carry the invoice number / DN number, so the
print queries pick them up automatically. The picker must still
pull the washers even though they never reach the customer.
- print-bundle: explicitly verifies the picking slip renderer is
called with both billable and excluded rows (mocked
PickingSlipPdf → assert lines array has both descriptions).
- delivery-note-print: explicitly verifies the PB filter does NOT
carry an exclude_from_invoice clause — adding one would
silently filter the picker slip and break Task 7's design.
Co-Authored-By: Claude <noreply@anthropic.com>
Task 7 of the non-invoiceable-order-extras plan.
The status flip + audit stamp + delivery_note header create all
run on EVERY row so the order closes normally — excluded rows are
real operational lines from the supplier's POV. The PDF line
list is built from billable.items only, so the customer never
sees excluded lines.
Added exclude_from_invoice to the getFullList projection (load-
bearing — omit it and the billable filter silently passes
undefined, every extra lands on the customer delivery note).
New 400 guard 'No billable lines for a delivery note' when every
row in the request is excluded. UI guard in Task 6 prevents the
operator from reaching this path, but the route has its own
defence so the picker doesn't get a guaranteed-to-fail submit
silently.
2 tests + 1 mutation-test prove the split:
- excluded rows still get status flip + DN number + PDF upload,
but the renderer is called with ONLY billable items
- all-excluded returns 400 before any PATCH fires
- mutation (PDF built from items): the mixed test fails because
the renderer sees 3 lines instead of 2
Co-Authored-By: Claude <noreply@anthropic.com>
Task 6 of the non-invoiceable-order-extras plan.
Both modals (QB submit + delivery note submit) — same shape change:
- Excluded rows render muted with a 'Not invoiced' chip in the
row metadata. The muted state overrides 'bg-card' even when
included, so the operator doesn't mistake them for billable.
- Their include-checkbox is checked and disabled — the row must
ride along for the n8n status flip, and the operator must not
be able to remove it or add it to the bill. onChange defensively
bails when the flag is set, in addition to the disabled prop.
- New 'billableCount' guard: when every billable row has been
unchecked, submit is replaced with 'No billable lines' label
and the click handler toasts 'This order has no billable lines.'
The existing 'noneIncluded' check still catches the operator
unchecking everything (including the excluded rows the disabled
checkbox blocks them from unchecking in practice); the new guard
is the per-mode subset check.
The existing 'noneIncluded' check isn't sufficient because excluded
rows are always in 'includedRowIds' (they have to ride along), so
includedRowIds.size === 0 is unreachable in practice — the billable
subset can still be empty.
Co-Authored-By: Claude <noreply@anthropic.com>
Task 5 of the non-invoiceable-order-extras plan.
buildQbInvoicePayload now keeps order_item_ids built from ALL
rows (so n8n's 'Build PocketBase Invoice Update' node flips
excluded rows to invoiced alongside their siblings — the order
closes normally), and builds items from BILLABLE rows only (so
QuickBooks never learns about the excluded lines).
billableRows helper exported for sharing with the invoice UI
(Task 6) and the delivery-note route (Task 7) — three callers,
one definition of 'billable'.
Added exclude_from_invoice to RawInvoicingRow AND the
INVOICING_FIELDS projection. The projection is load-bearing:
omit it and PB returns undefined, every extra silently bills
the customer. Confirmed by inspection and by the failing
'mixed set' test if the projection drifts.
4 tests + 1 mutation-test prove the split:
- mixed: excluded ids in order_item_ids, absent from items
- all-billable: identical output to the no-flag case
- all-excluded: empty items, full order_item_ids
- billableRows helper unit tests
- mutation (items built from input.rows): mixed and all-excluded
tests fail
Co-Authored-By: Claude <noreply@anthropic.com>
Task 4 of the non-invoiceable-order-extras plan.
The page-level margin gate (process/page.tsx) short-circuits when
the item has exclude_from_invoice. An excluded line has
selling_price forced to 0 (Task 2), so the computed markup is
always -100 and the gate would wedge every extra into
approval_needed and block the order. Bypassing the gate keeps the
operational flow unblocked.
Suppressed low-margin colouring for excluded rows — a red
'-100%' chip on every extra is noise. The 'Not invoiced' badge
(T3) replaces the price chip visually.
Server-side guard in requestOrderItemMarginApproval refuses to gate
an excluded item with code 'excluded_from_invoice' (status 422).
Belt-and-braces: the MCP path can't weaponise the approval queue
to push an excluded row through manager review. Checked BEFORE
the missing_prices guard so an excluded item with selling=0 throws
the descriptive error rather than the misleading missing_prices
one.
2 tests + 1 mutation-test prove both sides of the bypass:
- excluded: throws 'excluded_from_invoice', webhook NOT fired
- non-excluded: proceeds to approval_needed, webhook DOES fire
- mutation (guard disabled): the excluded test fails
Co-Authored-By: Claude <noreply@anthropic.com>
Task 3 of the non-invoiceable-order-extras plan.
- New POST /api/v1/orders/{id}/items route wraps
createOrderItemForOrder. Same-origin browser auth (PB session
cookie), mirrors the posture of /quote after the order-quote
migration.
- AddItemSheet component on the process page: right-side Sheet
(mirrors PriceEditSheet's layout) with description / quantity /
cost / selling / supplier / notes + the load-bearing
'exclude_from_invoice' checkbox. When ticked, the selling-price
input is forced to 0 and disabled, a 'Not invoiced' badge replaces
the margin chip so a -100% red chip on every extra is noise.
- Add Item button below the item card stack — always available,
not gated on item_status. The empty-state copy above ('No line
items on this order. Add items before processing.') now points at
a real action.
- Existing excluded rows render with a muted 'Not invoiced' badge
in the card stack so the operator can spot them at a glance
without opening the sheet.
- The server (Task 2) forces selling_price=0 from the flag
regardless of caller input — the client forcing here is for UX
consistency.
Co-Authored-By: Claude <noreply@anthropic.com>
Dropped the pending gate in createOrderItemForOrder. The original
gate's reasoning was that adding a row alongside an in-flight PO
would orphan that PO's pricing/supplier reference — wrong model
of what adding a row does. A new row is independent: it gets its
own PO when the operator processes it, never mutates an existing
one.
The unrelated nonPending gate in setOrderQuote (preventing a
quote link change after items are past pending) stays — different
invariant.
exclude_from_invoice flag: when set, selling_price is forced to
0 regardless of what the caller passes — the flag is the source of
truth downstream, the price column is not consulted by the
invoice/delivery-note payload builders. The flag itself is
persisted in the secondary-field patch alongside sku/unit/
supplier/notes.
orderLocked return field kept for API compatibility — now always
false. Pre-existing callers reading the shape compile and read a
constant.
3 tests + 2 mutations prove the assertions guard real behavior:
deleting the flag-persistence line and the force-zero line each
break their target test.
Co-Authored-By: Claude <noreply@anthropic.com>
Added the boolean to src/lib/types.ts per the non-invoiceable
extras design. No behavior change yet — this is just the type.
Tasks 2+ wire up the operational flow.
Co-Authored-By: Claude <noreply@anthropic.com>
Two coupled corrections to delivery-note repeat detection.
Self-match: delivery notes have no line-item collection -- items are
order_items rows tagged with delivery_note_number. The Path A flow
stamps that number onto rows that KEEP their `order` relation, so a
processed order and its own DN are backed by the same database rows.
isExactItemMatch compared them against themselves and returned true
unconditionally. 149 live rows are in that state. Guarded both by DN
id and, for combined DNs whose `order` is empty, by inspecting the DN
rows' own order relation.
Candidate statuses: `draft` and `loaded` are real deliveries here.
The owner confirmed drafts simply never get advanced in the system,
and `loaded` is reachable directly from draft, so goods can go out
without ever passing through `sent`. Excluding both left a candidate
pool of 3 DNs out of 116, making the feature inert. Ordering matters:
the self-match guard had to land first, because the DN that exposed
the bug is itself a draft.
Cancelled stays excluded pending confirmation -- it is 84 of 116 and
may have been used to clear superseded delivery orders rather than to
mark abandonment.
Tests: a prior review showed by mutation that the existing tests
assert output shape but pin no scoping decision -- company-vs-customer,
the status filter and the tie-break could all be inverted with the
suite green. Added filter-inspecting and self-match tests, each
verified by mutation to fail when its guard is removed.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Blue Truck pill on the orders list, distinct from the amber quote
suggestion and the teal linked quote. Reads
potential_delivery_note_number (denormalized, no expand needed) —
the service writes the relation and the number in the same update
call so the list query doesn't pay for a second expanded relation
(see orders-service.ts:253 for why the codebase avoids that).
Additive — an order can show both a quote pill and a delivery-note
pill at once; they're independent facts (a repeat-order
observation, not a provenance link).
Added potential_delivery_note: string and
potential_delivery_note_number: string to the Order interface in
src/lib/types.ts so the page gets the new fields via full-record
return from getOrdersDashboardData (no fields: projection in the
list path).
Co-Authored-By: Claude <noreply@anthropic.com>
Thin wrapper around suggestDeliveryNoteForOrder(id). The route
mirrors the quote matcher's /quote-match endpoint for the case
where an order's items were edited after intake, or the order
predates the automatic intake check.
Co-Authored-By: Claude <noreply@anthropic.com>
Two independent try/catch blocks inside the existing runQuoteMatch
closure in createOrder. Each matcher (quote + delivery-note) is its
own scope, so a failure in one cannot starve the other. The
intake-path after()/E468 guard from Task 6 stays in place — this
adds the second matcher call alongside the first.
The 3-test block in createOrder delivery-note auto-detection proves
the independence in both directions: a quote matcher throw doesn't
prevent the delivery-note match, and vice versa. Mutation-tested by
merging the two try/catches — guards the design itself, not just
the wiring.
Co-Authored-By: Claude <noreply@anthropic.com>
Five new fields on the `orders` collection:
- potential_delivery_note (relation → delivery_notes, single) — the
DN whose items exactly matched this order's items
- potential_delivery_note_number (text) — denormalized copy of the
matched DN's delivery_note_number, written alongside the relation
so the orders list can render the number without a second `expand`
(PB issues a separate IN query per expanded relation —
orders-service.ts:253 documents why this is avoided here)
- delivery_note_match_confidence (number) — always 1 when set, kept
for shape parity with quote_match_confidence
- delivery_note_match_method (text) — 'exact_items' or 'no_match',
text not select for the same forward-compatibility reason
quote_match_method is text
- delivery_note_matching_attempted (bool) — audit flag
Idempotent — each step detects its own 'already done' state.
Verified by re-running after the first apply.
Plan-staleness fix: PB stores relation options FLAT at the top
level of the field object (collectionId / cascadeDelete /
minSelect / maxSelect), not nested under an `options` key. The
plan's snippet had the nested form and PB rejected it with
'fields.N.collectionId Cannot be blank.' Verified the correct
shape against the live orders.potential_quote field before fixing.
Co-Authored-By: Claude <noreply@anthropic.com>
Wraps the pure comparator with PB reads/writes. Same shape as
suggestQuoteForOrder:
- skip when order has no company (don't stamp attempted)
- write potential_delivery_note + number + confidence + method +
attempted:true on completion
- empty write when no candidate matched
Tie-break order:
1. priced quote match (status=delivery_note, selling_price == order)
2. most recent (created desc)
Co-Authored-By: Claude <noreply@anthropic.com>
Pure module — no I/O, mirrors the separation established by
order-quote-match.ts.
isExactItemMatch is multiset equality on (normalizeLine(description),
quantity). Empty sets return false (would otherwise vacuously flag
every zero-line order against every zero-line DN).
14 tests cover: exact match, qty diff, extra line on either side,
multiplicity enforcement, the empty-set case, normalization
collapsing whitespace + case, and punctuation-sensitive 'exact'.
Co-Authored-By: Claude <noreply@anthropic.com>
Closes the same vanishing-buyer-notes bug B12 fixed on the process
page, this time on the order detail page that operators see first.
- Inline row indicators (MessageSquare icon for a buyer note,
Paperclip + count for per-line attachments) inside the Description
TableCell. Hidden when the line has no signal. Click toggles a
QuoteLineContext panel below the row.
- QuoteLineContext panel wrapped in a Fragment-keyed extra row,
colSpan=8 (matches the eight TableHead columns: Description, Qty,
Selling, Supplier, Cost, Total, Status, Edit). The plan called
for colSpan=9, but the Driver column was removed 2026-08-24 and
the live count is 8.
- quoteAttachments intentionally empty in the detail-page panel —
order-level attachments have their own card below the table.
Migration off pb-helpers (AGENTS.md §'data access layer discipline'):
- /api/v1/orders/{id}/quote route now treats empty quote_id as the
unlink path (clears quote + potential_quote + matching fields),
and dropped assertAgentAuth so the page can call it from a
browser session (admin auth happens via the PB session cookie at
the PocketBase layer; the MCP forwarder still works without that
gate because the MCP route gates at its own boundary).
- /api/v1/orders/{id}/quote-match is a thin wrapper around
suggestQuoteForOrder (returns the new SuggestQuoteResult shape —
best.quoteId / best.quoteNumber, not the old best.quote.id /
best.quote.quote_number).
- Page migrated four pb-helpers calls: findMatchingQuotesForOrder →
POST quote-match, applyOrderQuoteMatch → merge into quote-match +
QuoteMatchCard accepts the result via SuggestionCard from the
fetched order, clearOrderQuoteMatch → POST quote with empty
quote_id, setOrderQuoteManually → POST quote with the picked id.
- runMatch signature simplified — accept-vs-suggest was the old
split; the new endpoint only ever suggests. 'Accept' now goes
through linkQuoteManually via POST /quote.
- Stale matcher block (4 functions + 3 helpers + re-exports +
imports) deleted from pb-helpers.ts. The pure scoring helpers now
import directly from @/lib/server/order-quote-match.
Known follow-up: QuoteMatchCard still reads from matchResult (a
QuoteMatchResult shape). Clearing matchResult after runMatch means
the SuggestionCard renders empty until the next fetchOrder lands.
Reads from order.expand.potential_quote after that. A future task
can rewrite the card to drop the in-memory result entirely.
Co-Authored-By: Claude <noreply@anthropic.com>
This is the actual fix for the vanishing-buyer-notes bug the matcher
service exists to prevent. Before this commit, the process page did
an exact/substring description match on every render — and silently
hid the buyer note whenever the PO's wording differed from the
quote's, even after the matcher had resolved a confident pair.
- Server-resolved linePairs now drives the per-item lookup in three
places (inline quote preview row, the price-edit sheet's matched
prop, and copyCostFromMatch).
- findMatchedQuoteItem — the local exact/substring guesser that was
the root cause — is deleted. No other callers exist.
- QuoteLineContext renders description (when different), buyer note,
per-line and quote-level attachments, plus the 'possible match'
banner + confirm button. Replaces a hand-rolled block that had
drifted from the orders detail page.
- QuoteLineNoMatch renders when the order has a quote relation but
this specific order line didn't pair to any quote line —
previously this case rendered nothing, which was indistinguishable
from 'the quote line had no note'.
- onConfirmPair POSTs to /api/v1/orders/{id}/quote-line (Task 10)
and re-runs fetchAll so the next render sees the pair as
'confident'. Only exposed for tier === 'possible'.
- The Pricing source grid stays inline — it's order-side data
(SKU / pricing_source / matched_price_list_id / pricing_notes
round-trip from quote_items onto order_items), not part of the
quote context, and is editable on the order.
Co-Authored-By: Claude <noreply@anthropic.com>
Shared presentation of a paired quote line — description (when it
differs from the order), buyer note, line attachments, quote
attachments, plus a 'possible match' warning banner for the
operator's confirm button.
Used by both the order detail table (Task 13) and the process page
(Task 12) so the two never drift. The process page used to own the
only copy; the detail page showed nothing.
tier='possible' framing is the load-bearing part: a buyer is never
shown a note from the wrong line without being told it might be
wrong.
Co-Authored-By: Claude <noreply@anthropic.com>
The order detail page and process page need the pairing, not the
matcher — until now the process page was doing an exact/substring
guess at render time and silently hiding buyer notes when the PO's
wording differed from the quote's.
- matched-attachments response gains linePairs (keyed by order_item_id,
carrying quote_item_id, confidence, tier). pairOrderLines is called
defensively — a pairing failure cannot kill the attachments
response (catch returns null → empty linePairs object, the rest of
the payload still serves).
- POST /api/v1/orders/[id]/quote-line writes the operator's confirm
decision (or unlink with empty quote_item_id) onto
order_items.quote_item. Guards against patching a line that
belongs to a different order (404 otherwise).
Both routes are additive — the existing matched-attachments fields are
unchanged, the MCP orders.list_attachments consumer keeps working.
Co-Authored-By: Claude <noreply@anthropic.com>
Pure move — bodies copied verbatim from process/page.tsx into
src/components/orders/attachment-list.tsx. The order detail page
(Task 13) will now import the same component instead of growing a
second copy.
The 4 icon imports (FileText, Image as ImageIcon, FileQuestion,
ExternalLink) became unused after the move and were removed from
process/page.tsx. Re-exported from the new file alongside the
MatchedAttachment type, attachmentHref helper, and inferKind helper.
No behaviour change. tsc clean. No new lint errors in the touched
files.
Co-Authored-By: Claude <noreply@anthropic.com>
Hermes (n8n) drops the AGENT_API_KEY on direct REST calls, so anything
n8n needs to run must exist as an MCP tool. This forwards the agent's
JSON-RPC call to POST /api/v1/orders/quote-match/sweep, mirroring the
existing orders.set_quote forwarding pattern.
Updated the tools/list expected-list test to include the new tool so
the catalog stays self-documenting.
Co-Authored-By: Claude <noreply@anthropic.com>
The matcher only runs on orders created from now on. This sweeps the
historical backlog plus any order whose lines changed after creation.
- sweepUnmatchedOrders in order-quote-link-service.ts walks
quote_matching_attempted = false && quote = '' (the codebase's
pattern for an empty relation, verified against orders-service.ts
usage) in batches, projecting only id (the wider order fields are
re-fetched inside suggestQuoteForOrder).
- bucketAgeGaps exposes the histogram that lets FUZZY_WINDOW_DAYS be
re-tuned from real data instead of the 90-day estimate.
- POST /api/v1/orders/quote-match/sweep is the agent-auth surface
with maxDuration=300 for the 500-order worst case.
Tests cover the filter shape, the field projection (load-bearing —
over-projection wastes wire bytes), the no-op on no-match path, the
fault tolerance (one row throwing doesn't kill the batch), and all
six histogram bucket boundaries including the ≤ N vs < N edges.
Co-Authored-By: Claude <noreply@anthropic.com>
The mock for next/server's after() detaches the callback regardless of
what production code does, which left the outer catch's fire-and-forget
fallback untested and the runQuoteMatch inner catch tested for nothing.
- New test 'falls back to an inline match when after() is unavailable'
forces after() to throw and asserts suggestQuoteForOrder was called
anyway, plus that the fallback log fired. Mutation: deleting the
'void runQuoteMatch()' line breaks it.
- 'never fails order creation when the matcher throws' now spies on
console.error and asserts the inner catch's swallow actually logged.
Mutation: deleting the inner console.error breaks it.
- The outer catch now logs [createOrder] after() unavailable... so a
silent switch to fire-and-forget (after upgrade, waitUntil missing on
deploy target) is impossible to miss in production logs.
- Comment names error code E468, Next 16.2.6, and
node_modules/next/dist/server/after/after.js, and corrects the
justification: createOrder is an exported service function reachable
from multiple layers, not 'a smoke script or another background job'.
Verified against the documented baseline — same single pre-existing
failure (splitOrderForContinuation > moves pending items...), no new
failures introduced.
Co-Authored-By: Claude <noreply@anthropic.com>
createOrder previously hard-coded quote_matching_attempted: false and
never scheduled a match, so ~85% of orders that correspond to an
existing quote arrived unmatched and stayed that way until an
operator opened the order and clicked a button. Fire
suggestQuoteForOrder(order.id) via next/server's after() once the
response has been sent, so intake latency is unaffected, and guard
both the matcher call and the after() call itself: after() throws
synchronously outside a request scope (confirmed by reading
node_modules/next/dist/server/after/after.js), so a caller without
one (e.g. a background script invoking createOrder directly) falls
back to firing the match inline instead of crashing order creation.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The previous commit's two "happy path" pairing tests never reset
pairOrderLines' mock call history — vitest.config.ts doesn't set
clearMocks, and the file's global beforeEach only clears the PB
store. A prior passing setOrderQuote test left toHaveBeenCalledWith
already satisfied on entry, so those two tests passed even with the
production call site deleted. Add mockClear() after the dynamic
import in both so they actually exercise the call they claim to.
Also: reworded the idempotent-path comment to note the strict-pending
gate runs first, so pairing only re-runs there while every line is
still pending (not a general refresh mechanism); fixed the
"don't write, don't stamp" line, which the pairing call now
contradicts (order_items.quote_item is a write); and replaced a
comment pointer to a nonexistent plan section with a standalone
statement of the deferred-signal gap.
setOrderQuote is the single choke point for creating orders.quote —
used by the UI, REST API, and Hermes/n8n. Call pairOrderLines(orderId,
quoteId) right after the hard link lands so confident order-line to
quote-line pairs persist automatically instead of needing a separate
manual step.
Pairing also runs on the idempotent no-op path (order already points
at the requested quote) — it's safe to repeat and lets an operator
refresh pairing by re-running the same call after editing order lines.
A pairing failure never fails the link itself (console.error only,
by design) — the hard link is the operator's important intent and
must land even if pairing can't complete.
pairOrderLines' no-overwrite guard only checked whether an order
line's own row already carried a quote_item, not whether the quote
line it was about to claim was already held by a different order
line. A description drift (or a hand-confirmed link) on one line let
a fresh confident match on another line silently double-assign the
same quote_item, so two parts would render the same estimator's note
and attachments — the exact failure this feature exists to prevent,
reached from the other direction. Fixed by seeding a claimed-quote-item
set from the fetched order rows before the write loop, and skipping
any confident pair that targets an already-claimed quote line.
unmatchedOrderItemIds now also excludes any line that already carries
a link, even when this run's pairing pass didn't re-propose it.
Also names the two field projections (PAIR_ORDER_ITEM_FIELDS,
PAIR_QUOTE_ITEM_FIELDS) next to the existing MATCHER_QUOTE_ITEM_FIELDS
constant, and adds a test that asserts on the actual `fields` string
passed to each getFullList call. Previously nothing distinguished
`fields: "id,description"` from `fields: "id,description,quote_item"`
at the order-items query — a one-token trim silently disabled the
no-overwrite guard (every row read as unlinked) with the full suite
staying green, since the existing behavioral tests supply `quote_item`
values directly in their fixtures rather than through the query. Verified
by re-running that exact mutation against the new test: it fails, and
neither pre-existing behavioral test catches it on its own.
Adds pairOrderLines to order-quote-link-service.ts: pairs an order's
lines against a quote's lines via pairQuoteLines, writes quote_item
only for confident (>=0.5 Jaccard) pairs, and never overwrites a
line's existing quote_item. Possible-tier pairs are returned but left
unwritten so an operator has to confirm them before a buyer sees a
note attached on a guess.
Reuses fetchQuoteItemsForQuotesAdmin (already used by the fuzzy pass
in this file) to fetch quote_items rather than reintroducing a raw
QUOTE_ITEMS_COLLECTION query. Writes stay sequential, matching the
existing bulk-update convention in orders-service.ts.
Six review findings on suggestQuoteForOrder, all bite hardest once
order intake and the backlog sweep start calling it:
1. fetchQuoteItemsForQuotesAdmin's `fields` string was a hardcoded
constant owned by the duplicate-quote scan. The matcher now passes
its own `fields` (an added, defaulted parameter) instead of
depending on that string never being trimmed out from under it —
losing `description`/`selling_price` would have collapsed every
confidence score toward zero with no exception and no failing
test.
2. The candidate-quote query in fuzzyPass had no `fields`, so it
pulled full quote records (email_body, ai_insights,
migration_meta) for up to 200 candidates, twice per order when the
window widens, to read five scalars. Added
`fields: "id,quote_number,company,customer,created"`.
3. findExactMatch's bare `catch {}` swallowed everything, not just
the "field doesn't exist on an older PB schema" case it claimed to
guard (all four fields exist per pb_schema-2.json). An expired
admin token or a PB blip during the sweep would silently fall
through to the fuzzy path, and writeSuggestion would then persist
quote_matching_attempted: true / quote_match_method: "no_match" -
permanently hiding an order that had a valid citation from the
sweep's retry filter. Narrowed to rethrow anything that isn't a
ClientResponseError with status 400.
4. Exact-identifier lookups (quote_reference_text, rfq_number are
customer free text) weren't scoped to the order's company, so a
reference-number collision across two customers could return a
confidence-1.0 suggestion pointing at the wrong company's quote.
Added `company = "..."` to the filter when the order has one.
5. SuggestQuoteResult.window used the literal "90d", hardcoding
FUZZY_WINDOW_DAYS. Renamed to "initial" so retuning the constant
can't make the sweep's reporting lie.
6. order-quote-link-service.test.ts's makePb forced every test to
redeclare the full collection map. Gave it a default map merged
with a per-test override and renamed useP to mockAdminPb, since
two more tasks add tests to this file.
Adds tests for #1 (matcher's quote_items fields include description
and selling_price), #2 (candidate query's fields), and #4 (a
same-reference quote belonging to another company is not returned).
fuzzyPass built a single `quote = "x" || quote = "y" || ...` OR-chain
across up to FUZZY_CANDIDATE_CAP (200) candidate quotes to fetch their
items. The predecessor in pb-helpers.ts documents exactly why that
doesn't scale: PB's filter expression has a max length, and a naive
OR-chain 400s past roughly 50 ids. There was no try/catch, so
getFullList's rejection propagated straight out of
suggestQuoteForOrder - the matcher failed outright for precisely the
high-volume companies where auto-matching matters most.
Reuse fetchQuoteItemsForQuotesAdmin (now exported from
quotes-service.ts) instead of a third copy of the same chunking logic.
It already does this for the duplicate-quote scan: try PB's `IN (...)`
syntax first, fall back to 80-id chunked OR-chains on rejection.
Adds a regression test that simulates PB rejecting an oversized filter
across 100 candidate quotes and asserts the fetch recovers via
multiple chunked calls rather than rejecting outright. Confirmed it
fails against the pre-fix code (uncaught rejection propagates out of
suggestQuoteForOrder) before verifying it passes against the fix.
Ports the PocketBase half of the order<->quote matcher off the
browser's PB singleton and onto getAdminPocketBase(), so matching can
run at order intake and from a backlog sweep instead of only on a
button click. Reuses the pure scoring in order-quote-match.ts
untouched (scoreOrderVsQuote, quoteWindowForOrder,
quoteToOrderAgeDays).
suggestQuoteForOrder tries the four exact-identifier fields first
(never date-limited), then falls back to a company/customer/
description/price fuzzy scan windowed to 90 days before the order
date, widening to 365 days only if that comes up empty.
Writes only the soft suggestion (potential_quote,
potential_quote_confidence, quote_matching_attempted,
quote_match_method) - never orders.quote, the hard link. Orders that
already carry a hard link are skipped untouched.
pb-helpers.ts's findMatchingQuotesForOrder is left in place; a later
task migrates its last UI caller and removes it.
Two findings from review of the quote-line-pairing task:
- quoteToOrderAgeDays: Math.round ties toward +Infinity, so a negative
half-day gap rounds to -0. Normalize to a clean 0.
- quoteWindowForOrder / quoteToOrderAgeDays relied on `new Date(...)`
parsing PocketBase's space-separated datetime form
("2026-08-29 10:00:00.000Z") the same as ISO 8601. That happens to
work on V8 but is implementation-defined per spec. Both now go
through a shared parseFlexibleDate helper that normalizes the
separator explicitly.
Adds tests pinning both behaviours; the existing 40 tests stay green.
Adds quoteWindowForOrder (pure) to constrain the fuzzy-match candidate
scan to a date window anchored on the order's own created date, plus
the forward grace period for quotes raised a few days after the PO.
Also adds quoteToOrderAgeDays, used by a later task's age-gap
histogram, with test coverage the plan omitted (normal, inverted, and
unparseable-input cases).
Code review found LINE_PAIR_POSSIBLE was decorative -- pairLinesByDescription
still filtered on a hardcoded 0.3 literal, so editing the constant wouldn't
change behaviour. Also adds a test pinned to an exact 0.5 Jaccard pair to
catch off-by-one mutations on the confident/possible tier boundary.
The original sample scored 0.222 Jaccard — below the 0.3 candidate
floor — so it would have been dropped rather than tiered. Verified
0.333 for the replacement.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
