# UpdateShipment

## Permission Scope

shipment

## Overview

UpdateShipment revises draft shipment details before posting. It supports correction of shipment lines, addresses, ship dates, carrier metadata, or tracking references.

## Business Rules

- Only DRAFT shipments may be updated directly.
- Updated shipment quantities must remain within remaining shippable order quantities.
- `updateLines` and `removeLineIds` must target a line that exists on the shipment.
- `updateLines` patches the existing line in place, so its id and `createdAt` are preserved.

## Process Flow

```mermaid
flowchart TD
    A[Receive update request] --> B[Load shipment]
    B --> C{Status is DRAFT?}
    C -->|No| D[Return SHIPMENT_NOT_EDITABLE]
    C -->|Yes| E[Validate updated shipment details]
    E --> F[Persist shipment changes]
    F --> G[Return updated shipment]
```

## External Dependencies

- [getShipment](../query/GetShipment.md) - Load current shipment state before applying changes.

## Error Scenarios

- **SHIPMENT_NOT_FOUND**: Referenced shipment does not exist.
- **SHIPMENT_NOT_EDITABLE**: Only DRAFT shipments may be updated.
- **INVALID_SHIPMENT_LINE**: Shipment line quantity or reference is invalid
- **LINE_NOT_FOUND**: Referenced line does not exist on the target document
- **EMPTY_SHIPMENT_LINES**: No shipment lines were provided

## Test Cases

- updates draft shipment metadata
- updates a line in place so its id and createdAt survive the edit
- adds a shipment line via addLines
- removes a shipment line via removeLineIds
- returns error when shipment does not exist
- returns error when updating a posted shipment
- returns error when an update targets a missing line
- returns error when a removal would leave the shipment without lines
- returns error when an added line exceeds remaining order quantity
- returns error when an added line references an invalid order line
