# UpdateSalesOrder

## Permission Scope

salesOrder

## Overview

UpdateSalesOrder revises mutable sales-order fields while the order is still editable. It supports draft correction of addresses, external payment-term reference, commercial notes, and line composition before the order is submitted or revised through a future explicit workflow.

## Business Rules

- The selected account must match the document company and be available for transactions.

- Only DRAFT orders may be updated directly by this command.
- Each `updateLines` or `removeLineIds` entry must target a line that already exists on the order.
- `updateLines` patches a line in place, so its id and createdAt are preserved across the edit.
- Updated order lines must still satisfy item, quantity, and pricing validity rules.
- Every item chosen by an `addLines` entry or an `updateLines` patch must hold a [SalesItem](../model/SalesItem.md) record, and the line's `requiresPhysicalFulfillment` is re-frozen from that record; lines whose item is untouched keep the value they already froze.
- The order must retain at least one line after the update completes.
- Commercial snapshots frozen at confirmation cannot be changed through this command.

## Process Flow

```mermaid
flowchart TD
    A[Receive update request] --> B[Load sales order]
    B --> C{Status is DRAFT?}
    C -->|No| D[Return ORDER_NOT_EDITABLE]
    C -->|Yes| E[Validate updated fields and lines]
    E --> F[Persist order and line changes]
    F --> G[Return updated sales order id]
```

## External Dependencies

- [business-partner::GetCustomerAccount](../../../business-partner/docs/query/GetCustomerAccount.md) - Revalidate customer changes when customer context is edited.
- [item-management::GetItem](../../../item-management/docs/query/GetItem.md) - Revalidate changed item references on lines.

## Error Scenarios

- **CUSTOMER_NOT_ACTIVE**: Referenced customer is not in ACTIVE status

- **CUSTOMER_NOT_FOUND**: Referenced customer does not exist.

- **SALES_ORDER_NOT_FOUND**: Referenced sales order does not exist.
- **ORDER_NOT_EDITABLE**: Only DRAFT orders may be updated directly.
- **LINE_NOT_FOUND**: Referenced line does not exist on the target document
- **ITEM_NOT_SELLABLE**: Referenced item holds no selling record and cannot be sold
- **INVALID_ORDER_LINE**: Order line is missing quantity, price, or item context
- **EMPTY_ORDER_NOT_ALLOWED**: Sales order has no lines

## Test Cases

- rejects missing, inactive, and cross-company customer accounts
- allows an active replacement account even when its partner is inactive

- updates mutable draft order header fields
- updates a line in place so its id survives the edit
- adds an order line via addLines
- removes an order line via removeLineIds
- returns error when the order does not exist
- returns error when updating a non-draft order
- returns error when an update targets a missing line
- returns error when a removal would leave the order without lines
- returns error when an added line references an inactive item
- returns error when an added line references an item with no selling record
- re-freezes the fulfillment expectation when an update patch changes the line item
- returns error when an added line has invalid content