W114: Update purchase order

Edits a PO's header fields, including status and lifecycle timestamps. Triggered from the Purchase Order Detail page.

Steps

1. Load the PO. Call PurchaseOrders.getPoById to confirm existence.

2. Apply the header patch. Call PurchaseOrders.updatePo with the patch. Patchable fields: status, placedAt, shipDate, expectedDeliveryDate, receivedAt, paidAt, cancelledAt, shippingCosts, setupCosts, otherCosts, notes.

3. Reconcile the inventory ledger to the new status. Run the status → ledger reconciliation projector. It ensures an ORDER entry per line item (materials or FG ledger per targetType) exists whenever the status is not Planning or Cancelled, and emits REVERSE_ORDER when a transition back to Planning — or to terminal Cancelled — makes those entries no longer desired. The projector is idempotent: a status patch that doesn't change the desired set writes nothing. RECEIVE stays receipt-driven (W122).

Returns

The updated PO.

Business rules

• Some header fields are immutable. poNumber, vendorId, targetType, and shipToLocationId are not patchable.
• Status is patched directly. Any of the seven org.po_status values is accepted; a validated manual-transition map is a v1 gap. Partial / Received are normally computed by the receipt workflow (W122).
• Status drives the ledger. Step 3 reconciles ORDER entries to the new status (seeded once status leaves Planning, reversed on Cancelled) via the idempotent projector. RECEIVE remains receipt-driven (W122), so the two paths don't double-count.

Errors

• NotFoundError. The PO was not found.