# CreateGoodsReceipt

## Overview

CreateGoodsReceipt creates a draft goods receipt against one purchase order with one or more targeted purchase-order lines.

## Business Rules

- Purchase order must exist and belong to the same company as the receipt
- Purchase order must not be cancelled or closed
- At least one receipt line is required
- Each receipt line must reference a valid purchase-order line with open quantity
- Each receipt line must record a received quantity greater than zero
- Goods receipts are created in `DRAFT` status

## Process Flow

```mermaid
flowchart TD
    A[Receive create request] --> B{Purchase order exists and is receivable?}
    B -->|No| C[Return purchase order error]
    B -->|Yes| D{At least one line?}
    D -->|No| E[Return EMPTY_RECEIPT_LINES]
    D -->|Yes| F{Each line references open PO quantity and qty > 0?}
    F -->|No| G[Return line validation error]
    F -->|Yes| H[Insert goods receipt in DRAFT]
    H --> I[Return created receipt]
```

## External Dependencies

- None

## Error Scenarios

- **PURCHASE_ORDER_NOT_FOUND**: Referenced purchase order does not exist
- **PURCHASE_ORDER_NOT_RECEIVABLE**: Purchase order is cancelled, closed, or otherwise unavailable for receipt
- **EMPTY_RECEIPT_LINES**: No goods-receipt lines were provided
- **PURCHASE_ORDER_LINE_NOT_FOUND**: Referenced purchase-order line does not exist
- **NO_OPEN_RECEIPT_QUANTITY**: Purchase-order line has no remaining open quantity to receive
- **INVALID_RECEIVED_QUANTITY**: Received quantity is zero or negative
- **COMPANY_SCOPE_MISMATCH**: Goods receipt company does not match the purchase order company

## Test Cases

- creates a draft goods receipt against an ordered purchase order
- creates a draft goods receipt against a partially received purchase order
- returns error when purchase order does not exist
- returns error when purchase order is cancelled or closed
- returns error when no receipt lines are provided
- returns error when a purchase-order line does not exist
- returns error when a receipt line has no open quantity
- returns error when received quantity is zero or negative
- returns error when goods receipt company does not match the purchase order company
