# README

<!-- This section should contain the following subsections in order: -->
<!-- 1. ## Overview (required) -->
<!-- 2. ## Key Features (required) -->
<!-- 3. ## Module Scope (required) -->
<!-- 4. ## Module Dependencies (required) -->

## Overview

The outbound-shipment module owns the warehouse dispatch document lifecycle for
goods leaving inventory. It captures each dispatch as an OutboundShipment header
with OutboundShipmentLine rows, moving the document from draft through posting
and cancellation. Source-document context lives at the line level, so one
shipment can consolidate demand from several sales or manufacturing orders.

`inventory` remains the owner of stock facts. When an outbound shipment is
posted, outbound-shipment calls inventory's posting API once to issue stock
(direction=OUT); inventory then produces the immutable InventoryLedger rows,
decrements balances, applies valuation, and consumes
matching reservations. Posted shipments are immutable; corrections are
represented by a separate reversal document when introduced.

For sales-order sources, `OutboundShipment` is also the shipment evidence linked
to the commercial commitment through line-level source references. Sales keeps
the order baseline and fulfillment progress projection, while outbound-shipment
owns the shipment document and inventory posting boundary.

## Key Features

- Outbound shipment document lifecycle from draft through posting and cancellation
- Outbound shipment lines with line-level, weak source document references
- Line-level source references to sales orders and manufacturing orders on a single dispatch
- Unit-conversion snapshots that normalize business quantities to the item's primary unit
- Posting workflow that issues stock through inventory's posting API and returns the resulting ledger entries

## Module Scope

### In Scope

- Outbound shipment document headers and their outbound lines
- DRAFT lifecycle validation for creation, update, and cancellation
- One-shot posting that triggers inventory stock issue via the inventory posting API
- Line-level source references to sales orders and manufacturing orders

### Out of Scope

- InventoryLedger, StockLevel, and valuation ownership, owned by `inventory`
- Reservation lifecycle; reservation consumption happens inside the inventory posting API
- Sales-order lifecycle and fulfillment progress projection, owned by `sales`
- Cross-module propagation from posted shipments into sales progress or billing workflows
- Reversal and correction documents for posted shipments (future scope)

### Scope Decision Rationale

Outbound shipments are dispatch documents, not stock master records. Keeping
them in a separate module avoids overloading inventory with outbound document
lifecycle while still letting posting create immutable stock facts in inventory
through a single posting call. Line-level source references keep the boundary
clean: a dispatch can cover multiple source orders without forcing a header-level
one-to-one link to any source module.

## Module Dependencies

- `inventory` - Stock issue through the posting API, and the InventoryLedger, StockLevel, and valuation facts it produces
- `item-management` - Item references and primary-unit snapshots on shipment lines
- `organization` - Company scope for outbound shipments