W125: Update receipt

Edits a previously-recorded PO receipt. Triggered from the Purchase Order Detail receipts section. Metadata-only edits (date, notes) are a fast path; any change to received quantities or unit costs rebuilds the ledger entries and re-runs the cost cascade so downstream values stay correct.

Steps

1. Load the receipt and parent PO. Call PurchaseOrders.getReceiptById.

2. Fast path for metadata-only edits. If only the date or notes changed, call PurchaseOrders.updateReceipt and return.

3. Rebuild ledger entries on quantity or cost edits. For the existing RECEIVE entries on this receipt (matched by source_id = receipt.id), insert paired REVERSE_RECEIVE entries to net them to zero. Then update the receipt header and items, and post fresh RECEIVE entries via the same logic as W122 step 4 with the new quantities and unit costs. The originals and their reverses both stay in the ledger; the new RECEIVE rows are the current truth.

4. Roll up costs on the PO header. Apply W122 step 5.

5. Recompute the PO status. Apply W122 step 6: Received if every line is fully received, Partial otherwise.

6. Re-run the cost cascade. (Materials POs only.) Apply W122 steps 7 through 9 so material averages, dependent work-order costs, and FG ledger costs reflect the new state.

Returns

The updated receipt.

Business rules

• Rebuild via reverse-then-insert. Step 3 writes reverses for the old rows then appends new rows; nothing is hard-deleted. The cascade reads net quantities from the ledger to recompute FIFO layers, so the reverses correctly retire the old layers.
• Atomic with cascade. Steps 3 through 6 share a single transaction.
• FG POs skip the materials cascade. Same rule as W122.

Errors

• NotFoundError. The receipt was not found.
• InvalidTransitionError. The parent PO is in a terminal status (Paid or Cancelled).