# UpdateGoodsReceipt

## Permission Scope

goodsReceipt

## Overview

UpdateGoodsReceipt changes draft receipt quantities, receipt dates, line composition, or PO-line references before the receipt is posted. Lines can be added, removed, or have their `purchaseOrderLineId` assigned or changed while in draft.

## Business Rules

- Target goods receipt must exist
- Only receipts in `DRAFT` status can be updated
- Updated lines must satisfy the same validation rules as create (PO reference is optional; when present, same company/supplier/open-quantity checks apply)
- Posted receipts are immutable and must be corrected by a future compensating workflow instead of update

## Process Flow

```mermaid
flowchart TD
    A[Receive update request] --> B{Goods receipt exists?}
    B -->|No| C[Return GOODS_RECEIPT_NOT_FOUND]
    B -->|Yes| D{Status is DRAFT?}
    D -->|No| E[Return GOODS_RECEIPT_NOT_DRAFT]
    D -->|Yes| F{Updated lines valid?}
    F -->|No| G[Return validation error]
    F -->|Yes| H[Update draft receipt]
    H --> I[Return updated receipt]
```

## External Dependencies

- None

## Error Scenarios

- **GOODS_RECEIPT_NOT_FOUND**: Referenced goods receipt does not exist
- **GOODS_RECEIPT_NOT_DRAFT**: Goods receipt is not in `DRAFT` status
- **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

## Test Cases

- updates quantities on a draft goods receipt
- updates receipt date on a draft goods receipt
- returns error when goods receipt does not exist
- returns error when goods receipt is not draft
- returns error when updated line data is invalid
- returns error when an updated receipt quantity is not positive
- returns error when an updated receipt line has no open quantity remaining
- updates a draft goods receipt without providing lines
- returns error when a PO-unlinked line has non-positive quantity
- accepts PO-unlinked lines with valid quantity
- uses PO line defaults for itemId, unitId, and receiving site when not provided
