# PostGoodsReceipt

## Overview

PostGoodsReceipt validates a draft receipt, updates cumulative received quantities on the referenced purchase-order lines, transitions the purchase order to the correct receiving state, and emits the inbound inventory handoff when required.

## Business Rules

- Target goods receipt must exist
- Only receipts in `DRAFT` status can be posted
- Each receipt line must still reference open purchase-order quantity
- Over-receipt beyond configured tolerance is blocked unless an explicit override path is provided
- Only posted goods receipts count toward 3-way supplier bill matching
- Stock-item lines emit the `InboundReceiptHandoff` exactly once; service lines do not require inventory execution

## Process Flow

```mermaid
flowchart TD
    A[Receive post request] --> B{Goods receipt exists and is DRAFT?}
    B -->|No| C[Return not found or invalid status]
    B -->|Yes| D{Receipt lines still have open quantity and are within tolerance?}
    D -->|No| E[Return receipt validation error]
    D -->|Yes| F[Increase PO line received quantities]
    F --> G[Set goods receipt to POSTED]
    G --> H{Stock line present?}
    H -->|Yes| I[Emit inbound receipt handoff]
    H -->|No| J[Skip inventory handoff]
    I --> K[Roll up PO receiving status]
    J --> K
    K --> L[Return posted receipt]
```

## External Dependencies

- [inventory::CreateStockMovement](../../../inventory/docs/commands/CreateStockMovement.md) - Downstream stock execution target for stock-item receipts

## Error Scenarios

- **GOODS_RECEIPT_NOT_FOUND**: Target goods receipt does not exist
- **GOODS_RECEIPT_NOT_DRAFT**: Goods receipt is not in `DRAFT` status
- **PURCHASE_ORDER_NOT_RECEIVABLE**: Purchase order is cancelled or closed
- **NO_OPEN_RECEIPT_QUANTITY**: Purchase-order line has no remaining open quantity to receive
- **OVER_RECEIPT_TOLERANCE_EXCEEDED**: Received quantity exceeds allowed tolerance
- **INACTIVE_EXECUTION_REFERENCE**: Supplier or item is no longer valid for execution
- **INVENTORY_HANDOFF_FAILED**: Downstream inventory handoff could not be recorded

## Test Cases

- posts a valid goods receipt and increases purchase-order received quantity
- transitions purchase order to partially received when open quantity remains
- transitions purchase order to received when all quantity is posted
- emits inventory handoff once for a stock-item receipt
- skips inventory handoff for a service receipt
- returns error when goods receipt does not exist
- returns error when goods receipt is not draft
- returns error when posting exceeds tolerance
- returns error when inventory handoff fails
- returns error when purchase order is no longer receivable
- returns error when posting a receipt line with no open quantity remaining
- returns error when execution references are inactive
