# GoodsReceipt

## Description

GoodsReceipt is the purchase-side confirmation that ordered goods or services were received from the supplier. It records one receipt event against one purchase order with one or more receipt lines, updates purchase-order receiving progress, and optionally emits a downstream inventory handoff for stock items.

The model intentionally separates procurement confirmation from warehouse execution. Purchase owns the fact that the supplier fulfilled part of the commitment; inventory owns the resulting stock movement and physical storage consequences.

## Domain Model Definitions

### Model type

Stateful

#### State Transitions

```mermaid
stateDiagram-v2
    [*] --> Draft: createGoodsReceipt
    Draft --> Draft: updateGoodsReceipt
    Draft --> Posted: postGoodsReceipt
    Draft --> Cancelled: cancelGoodsReceipt
```

### Command Definitions

- [createGoodsReceipt](../commands/CreateGoodsReceipt.md) - Create a draft receipt against open purchase-order lines
- [updateGoodsReceipt](../commands/UpdateGoodsReceipt.md) - Correct draft receipt quantities, dates, or line composition before posting
- [postGoodsReceipt](../commands/PostGoodsReceipt.md) - Validate tolerance, post the receipt, update order progress, and emit the inbound handoff
- [cancelGoodsReceipt](../commands/CancelGoodsReceipt.md) - Cancel a draft receipt before it affects purchase-order fulfillment

### Query Definitions

- [getGoodsReceipt](../queries/GetGoodsReceipt.md) - Retrieve a goods receipt with all receipt lines and handoff metadata

### Models

- GoodsReceipt
- GoodsReceiptLine
- InboundReceiptHandoff

### Invariants

- Every goods receipt belongs to exactly one company, one supplier, and one purchase order
- Every receipt line references one open purchase-order line and records a received quantity greater than zero
- Only `POSTED` receipts contribute to purchase-order received quantities and 3-way bill matching
- A receipt cannot post against a cancelled or closed purchase order
- Over-receipt beyond configured tolerance is invalid unless an explicit override path is recorded by policy
- Service or non-stock receipt lines do not require downstream warehouse execution even when the procurement receipt is posted
- Posted receipts are immutable; future corrections must use a compensating workflow instead of mutating receipt history in place
- The minimum `InboundReceiptHandoff` payload contains purchase-order reference, purchase-order-line reference, goods-receipt reference, received quantity, unit of measure, receipt date, destination site, and destination storage location when stock execution requires it

### Relationships

- **Belongs To PurchaseOrder**: Each receipt posts against one [PurchaseOrder](./PurchaseOrder.md)
- **Has Many GoodsReceiptLines**: Each receipt contains one or more line-level receipt confirmations
- **References Item**: Receipt lines trace back to one [Item](../../../item-management/docs/models/Item.md) through the purchase-order line
- **May Emit InboundReceiptHandoff**: Posted stock receipts hand off to inventory execution using [CreateStockMovement](../../../inventory/docs/commands/CreateStockMovement.md) or an equivalent downstream adapter
