Goods Receipt Against Purchase Order

then on-hand increments atomically, PO line status updates to partially/fully received, AP is notified with grn_{id} reference, and response time <2 s

auto-generate GRN number with grn_{snowflake} prefix

PO-to-GRN three-way match (PO qty, GRN qty, invoice qty);
support partial receipts across multiple shipments;
barcode/RFID scan input for item identification;
auto-generate GRN number with grn_{snowflake} prefix;
record received-by user, timestamp, and carrier reference;
flag over-receipt (>PO qty) for supervisor approval;
update on-hand quantity atomically in a single DB transaction;
notify AP module on GRN confirmation;
response time <2 s for PO lookup.

Given an open PO with line items and quantities;
when warehouse receiver submits a GRN with scanned item codes and received quantities;
then on-hand increments atomically, PO line status updates to partially/fully received, AP is notified with grn_{id} reference, and response time <2 s;
(negative) when received qty exceeds PO qty without supervisor approval then 422 OVER_RECEIPT_REQUIRES_APPROVAL.

goods_receipt_note { id: string, external_id: string, po_id: string, entity_id: string, received_by: string, carrier_ref: string, status: enum(DRAFT,CONFIRMED,VOIDED), received_at: timestamp };
grn_line { grn_id: string, po_line_id: string, item_id: string, received_qty: int, uom: string, over_receipt_flag: bool };
parent purchase_order updated on confirmation;
(reference, product may differ).

POST /v1/goods-receipt-notes { po_id, lines:[{po_line_id, item_id, received_qty, uom, lot_number?}], carrier_ref, external_id } -> 201 { id, status, grn_lines };
GET /v1/goods-receipt-notes/{id};
POST /v1/goods-receipt-notes/{id}/confirm -> 200 { status: CONFIRMED };
emits inventory.grn_confirmed event;
idempotent via external_id.

DRAFT -> CONFIRMED;
terminal VOIDED;
guard: over-receipt blocks CONFIRMED without supervisor approval;
confirmed GRN is immutable;
void only before AP voucher created.