W112: List purchase orders

Returns PO header rows for the Purchase Orders page, hydrated with vendor name and both cost rollups so the page can render expected and actual totals without a follow-up call. Filters are supplied by the caller.

Steps

1. List the POs. Call PurchaseOrders.listPos(filters). The L2 op returns each header plus two computed cost fields:

   • expectedTotal = sum(po_items.quantity × po_items.unit_cost) + shippingCosts + setupCosts (what the PO was quoted at).
   • actualTotal = sum(po_receipt_items.quantity × po_receipt_items.unit_cost) + shippingCosts + setupCosts (what receipts have actually rolled up).

2. Batch-hydrate vendors. Collect distinct vendor ids and call Vendors.listByIds once to attach names. Avoids N+1 fetches at L4.

Returns

PO header rows with vendor name, expectedTotal, and actualTotal attached.

Business rules

• Tenant scoping is automatic. All reads use the request's app.org_id; no cross-tenant leakage is possible.
• The page picks which total to show. Frontend convention: show expectedTotal while the PO is pre-receipt, actualTotal from Partial onward. The workflow returns both either way.

Errors

None.