# UpdatePurchaseOrder

## Permission Scope

purchaseOrder

## 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 with `orderStatus` = `DRAFT` can be updated
- Header-level receiving site may be updated and must reference a valid site if provided
- Updated lines must satisfy the same validation rules as create (including item ACTIVE requirement — this is still a pre-order phase where inactive items should not enter new procurement)
- Line-level receiving site overrides are validated independently; if not provided, the header default applies
- 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**: Referenced 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 not in ACTIVE status
- **INVALID_QUANTITY**: Quantity is zero or negative
- **INVALID_UNIT_PRICE**: Unit price is negative or otherwise invalid
- **RECEIVING_SITE_NOT_FOUND**: Referenced receiving site does not exist
- **PAYMENT_TERM_NOT_FOUND**: Referenced purchase payment term does not exist
- **PAYMENT_TERM_INACTIVE**: Referenced purchase payment term is inactive

## Test Cases

- updates supplier-facing data on a draft purchase order
- 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 header receiving site does not exist
- returns error when line receiving site does not exist
- returns error when selected payment term does not exist
- returns error when selected payment term is inactive
- inserts lines with receivingSiteId as null when not provided
