# PostShipment

## Permission Scope

shipment

## Overview

PostShipment turns a draft shipment into immutable fulfillment evidence. It updates sales-order shipped progress and emits the outbound inventory handoff for stock lines.

## Business Rules

- Only DRAFT shipments may be posted.
- Posted quantities cannot exceed the remaining shippable quantity on each referenced order line unless a future override flow is introduced.
- Stock lines must emit the outbound inventory handoff exactly once at posting time.

## Process Flow

```mermaid
flowchart TD
    A[Receive post request] --> B[Load draft shipment]
    B --> C[Validate posted quantities and order status]
    C --> D[Update sales-order shipped progress]
    D --> E[Emit outbound shipment handoff]
    E --> F[Set shipment status to POSTED]
    F --> G[Return posted shipment]
```

## External Dependencies

- [getShipment](../queries/GetShipment.md) - Load shipment details and referenced lines.
- [inventory::ReserveStock](../../../inventory/docs/commands/ReserveStock.md) - Downstream inventory execution contract reference.

## Error Scenarios

- **SHIPMENT_NOT_FOUND**: Referenced shipment does not exist.
- **INVALID_SHIPMENT_STATUS**: Only DRAFT shipments may be posted.
- **OVER_SHIPMENT_NOT_ALLOWED**: Posted quantity exceeds remaining open quantity.

## Test Cases

- posts a shipment and updates order shipped progress
- emits downstream inventory handoff for stock lines
- throws when shipment quantity exceeds remaining order quantity
- throws when posting a non-draft shipment
