# Shipment

## Description

Shipment is the sales-side fulfillment document that proves which order quantities were shipped, when they shipped, and from which site. It is the commercial handoff to inventory execution and the billing evidence for shipment-gated invoicing policies.

## Domain Model Definitions

### Model type

Stateful

#### State Transitions

```mermaid
stateDiagram-v2
    [*] --> Draft: createShipment
    Draft --> Posted: postShipment
```

| Operation | From | To | Command |
|-----------|------|----|---------|
| post | DRAFT | POSTED | [postShipment](../commands/PostShipment.md) |

### Command Definitions

- [createShipment](../commands/CreateShipment.md) - Create a draft shipment against open sales-order lines.
- [updateShipment](../commands/UpdateShipment.md) - Correct draft shipment details such as quantities, addresses, or tracking data before posting.
- [postShipment](../commands/PostShipment.md) - Post the shipment, update order progress, and emit the outbound inventory handoff.

### Query Definitions

- [getShipment](../queries/GetShipment.md) - Retrieve one shipment with posted quantities, addresses, and tracking context.
- [listShipmentsBySalesOrder](../queries/ListShipmentsBySalesOrder.md) - List shipments associated with a selected sales order.

### Models

- Shipment
- ShipmentLine

### Invariants

- Every shipment belongs to exactly one company and references exactly one sales order.
- Only DRAFT shipments may be edited directly.
- Only POSTED shipment quantities contribute to sales-order shipped progress or shipment-gated invoice eligibility.
- For stock items, posting emits exactly one outbound shipment handoff for each posted shipment line.

### Relationships

- **Owns ShipmentLine**: Each shipment contains one or more shipment lines tied to order lines.
- **References SalesOrder**: `salesOrderId` identifies the originating commercial commitment.
- **References Site (cross-module)**: `shipFromSiteId` comes from organization and records fulfillment origin.
- **References inventory handoff contract**: Posting produces the `OutboundShipmentHandoff` payload for downstream stock execution.
