# UpdatePurchaseOrder

## Overview

UpdatePurchaseOrder revises mutable commercial data on a draft purchase order, including lines, supplier-facing price overrides, payment term selection, and receiving context.

## Business Rules

- Target purchase order must exist
- Only orders in `DRAFT` status can be updated
- Updated lines must satisfy the same validation rules as create
- Draft buyers may override a defaulted supplier price while retaining the matched-rule reference for audit
- Updating a purchase order never changes already ordered, received, or billed documents

## Process Flow

```mermaid
flowchart TD
    A[Receive update request] --> B{Purchase order exists?}
    B -->|No| C[Return PURCHASE_ORDER_NOT_FOUND]
    B -->|Yes| D{Status is DRAFT?}
    D -->|No| E[Return PURCHASE_ORDER_NOT_DRAFT]
    D -->|Yes| F{Updated lines and references valid?}
    F -->|No| G[Return validation error]
    F -->|Yes| H[Update draft order and lines]
    H --> I[Return updated order]
```

## External Dependencies

- [business-partner::GetPartner](../../../business-partner/docs/queries/GetPartner.md) - Re-validate supplier identity and role when supplier-facing data changes
- [item-management::GetItem](../../../item-management/docs/queries/GetItem.md) - Re-validate item references on changed lines
- [organization::GetSite](../../../organization/docs/queries/GetSite.md) - Re-validate receiving site references

## Error Scenarios

- **PURCHASE_ORDER_NOT_FOUND**: Target purchase order does not exist
- **PURCHASE_ORDER_NOT_DRAFT**: Purchase order is not in `DRAFT` status
- **ITEM_NOT_FOUND**: Referenced item does not exist
- **ITEM_NOT_ACTIVE**: Referenced item is inactive
- **INVALID_QUANTITY**: Ordered quantity is zero or negative
- **INVALID_UNIT_PRICE**: Unit price is negative
- **RECEIVING_SITE_NOT_FOUND**: Referenced receiving site does not exist
- **RECEIVING_SITE_REQUIRED**: A physical-receipt line has no receiving site
- **PAYMENT_TERM_INACTIVE**: Selected payment term is inactive for new draft use

## Test Cases

- updates supplier-facing data on a draft purchase order
- updates line pricing while preserving matched price-rule reference
- returns error when purchase order does not exist
- returns error when purchase order is not in draft
- returns error when updated line data is invalid
- returns error when an updated line item is inactive
- returns error when an updated line quantity is not positive
- returns error when an updated line unit price is negative
- returns error when an updated receiving site does not exist
- returns error when a physical-receipt line has no receiving site
- returns error when selected payment term is inactive
