W137: Create receipt against work order

Records production output from a work order. Triggered from Work Order Detail receipts section. The WO equivalent of the PO receipt: consumes inputs from both ledgers using the recipe snapshot and produces finished goods into the FG ledger, all in one transaction.

Steps

1. Confirm the WO and capture context. Call WorkOrders.getWoById; reject if the WO is Cancelled. Capture woNumber and workSiteLocationId.

2. Create the receipt header. Call WorkOrders.createReceipt with receiptDate and notes.

3. Post each output line, its input consumption, and its production entry. For every received output line: call WorkOrders.addReceiptItem. Load the line's recipe snapshot via WorkOrders.listInputsByItem(woItemId). For each snapshot row:

   • Material input: write MaterialsInventory.recordConsumption with quantity = snapshot.quantity × receivedQuantity / wo_item.quantity, locationId = workSiteLocationId, ref = woNumber, unitCost = FIFO weighted-average for that material at the work-site location at consume time (oldest layers consumed first).
   • SKU sub-assembly input: write FinishedGoodsInventory.recordConsumption with the equivalent shape, unitCost = FIFO weighted-average for the input SKU at the work-site location at consume time. Then write FinishedGoodsInventory.recordProduction (event type PRODUCE) for the output SKU with quantity = receivedQuantity, locationId = workSiteLocationId, ref = woNumber, unitCost = wo_item.materialUnitCost + wo_item.conversionCost (the snapshot's current cost values).

4. Advance the WO status. If cumulative received per line meets or exceeds expected, transition to Received; otherwise transition to Partial. Call WorkOrders.updateWo.

Returns

The new receipt with its received-item rows.

Business rules

• Atomic. Steps 2 through 4 share a single transaction; consumption, production, and status advance commit together.
• Consumption is computed from the snapshot. BOM edits after WO creation are invisible to receipts; the recipe (identity and quantity) is frozen on the WO. Cost values on the snapshot may have been updated by W027's cascade since creation; whatever they are at consume time is what gets stamped.
• Over-production is allowed. Receipts may exceed expected quantity; the WO simply lands in Received.
• Consume costing is a v1 gap. Per the spec, CONSUME unitCost should be the FIFO weighted-average at consume time and PRODUCE unitCost should include materialUnitCost; v1 stamps 0 on CONSUME and conversionCost only on PRODUCE, pending the cost-cascade work.
• No stock guard in v1. Consumption draws from the work-site location's on-hand without blocking on insufficient stock; the materials and FG ledgers can go negative on under-stock. Stock protection is a future concern.
• Receipt-driven transition. The Partial / Received transition in step 4 bypasses the manual map; it is computed from the ledger.

Errors

• NotFoundError. The WO was not found.
• InvalidTransitionError. The WO is Cancelled.
• ValidationError. A receipt line references a woItemId that doesn't belong to this WO.