# Return mistaken collections to the pool

Collection Confirm has a **Return to pool** button on each line and a
**Return PO to collection pool** button at the bottom of each PO card.
The PO button affects only the collected lines shown on that card, not
other lines on the customer order. Both open a confirmation listing the
affected items before making any changes.

The reset clears driver assignment, collection dates, collected and
assigned quantities, collection problem flags and the previous AI check.
Order quantities, costs, SKUs, photos and notes are retained. Customer
lines return to `item_status = collection_pool`; stock lines return to
`status = collection_pool` with `quantity_received = 0`. An unbooked stock
header marked `received` reopens to `sent` so it leaves the accountant's
booking queue until collection is confirmed again.

Items already invoiced, dispatched, delivered or booked into stock are
refused. Refused lines are reported separately if some lines can return.
The browser reloads the queue after the operation. Normal confirmation
stays available; Add to POS controls are hidden but their underlying
handlers and endpoints remain.

## Deployment

Deploy **both** the app and `pocketbase/pb_hooks/collection_return.pb.js`.
The hook is listed in `pocketbase/pb_hooks/DEPLOY`; publish the committed
hooks folder with `npm run pb:hooks:publish` using the workflow in
`scripts/pb-hooks/README.md`. No collection fields or select values need
to be added.

The authenticated capability endpoint
`GET /api/wfdash/collection-return-guard` must return `{ "version": 1 }`.
Until the hook is deployed the app refuses resets with HTTP 503. It must
never fall back to an unguarded update.

Each return uses a PB batch transaction. The hook rechecks row revisions,
stock parent revisions, invoice metadata and stock ledger entries inside
that transaction before allowing the writes. It also guards the opposite
race: a stale customer confirmation cannot advance a returned/assigned
line, and a stock booking cannot insert a receipt after the PO reopens.
Existing PB audit hooks record customer field changes; no extra app audit
notes are added.

## Validation

Run the tests under `src/components/collection-confirm`,
`src/app/(app)/collection-confirm`, `src/app/api/v1/collection-confirm`,
and `src/lib/server/collection-return*.test.ts`. The hook tests evaluate
the real JS file in a mocked PB environment; they do not change live data.
After deployment, verify a mistaken collection returns to the pool with
zero collected quantity and can be assigned to a driver again.