# UpdateProductionOrder

## Permission Scope

productionOrder

## Overview

UpdateProductionOrder revises mutable draft planning fields such as dates, quantity, and preferred BOM or routing before release freezes execution assumptions.

## Business Rules

- Target production order must exist.
- Only `DRAFT` orders are mutable through this command.
- Planned quantity must remain greater than zero.
- Optional BOM or routing references must remain within the same company and site scope.
- Updating a draft order does not create work orders or cost baselines.

## Process Flow

```mermaid
flowchart TD
    A[Receive update request] --> B{Order exists?}
    B -->|No| C[Return PRODUCTION_ORDER_NOT_FOUND]
    B -->|Yes| D{Status is DRAFT?}
    D -->|No| E[Return PRODUCTION_ORDER_NOT_MUTABLE]
    D -->|Yes| F[Validate revised planning fields]
    F --> G[Persist draft changes]
    G --> H[Return updated order]
```

## External Dependencies

- None

## Error Scenarios

- **PRODUCTION_ORDER_NOT_FOUND**: Referenced production order does not exist
- **PRODUCTION_ORDER_NOT_MUTABLE**: The order is not in `DRAFT`.
- **INVALID_PLANNED_QUANTITY**: Planned quantity is zero or negative.
- **CROSS_SCOPE_MASTER_REFERENCE**: BOM or routing reference belongs to another company or site.

## Test Cases

- updates draft planning fields on a production order
- returns error when the order does not exist
- returns error when the order is not in `DRAFT`
- returns error when planned quantity is not positive
- returns error when BOM or routing references are out of scope