# 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 inbound-shipment module owns the goods-receipt document lifecycle. It
captures inbound shipments as receiving documents through a small DRAFT,
CANCELLED, and POSTED lifecycle. Source-document context lives at the line
level, so a single inbound shipment can cover lines drawn from more than one
purchase order.

Inbound shipments are stock-moving receiving documents, not ledger records.
Inventory owns the ledger, balances, and valuation; this module owns the
receiving document lifecycle. When an inbound shipment is posted, the module
posts the resulting stock effects through inventory's `postInventoryLedger`
API in the same transaction, so the receiving document and its stock ledger
rows are committed together. Posted inbound shipments are immutable;
corrections are represented by separate documents when introduced.

## Key Features

- Inbound shipment document lifecycle from draft through posting and cancellation
- Line-level received quantities with unit-conversion snapshots to the item primary unit
- Line-level weak source document references so one shipment can cover multiple purchase orders
- One-shot posting that hands inbound stock movements to inventory in a single transactional call
- Boundary queries that expose posted purchase receipt evidence and quantities for supplier bill matching

## Module Scope

### In Scope

- Inbound shipment headers and inbound shipment lines
- Draft receiving document capture, revision, and soft cancellation
- Unit-conversion boundary between source/business units and the item primary unit
- Optional inbound valuation snapshot per line for posting
- One-shot posting of inbound stock movements through inventory's posting API
- Boundary queries for purchase receipt evidence and received quantity totals

### Out of Scope

- Inventory ledger, stock balances, and valuation ownership
- Supply-plan consumption and other stock effects, which happen inside the inventory posting API
- Purchase order processing and supplier bill matching, owned by `purchase`
- Goods issue, transfer, and stock adjustment execution, owned by `inventory`

### Scope Decision Rationale

The goods-receipt document is a receiving operational document, not a stock
ledger record. Extracting it from inventory keeps the receiving lifecycle
separate from inventory's ledger, balances, and valuation ownership, while
inventory's posting API remains the single writer of stock facts. Holding
source references at the line level lets one physical shipment reconcile
against several purchase orders without splitting the receiving document.

## Module Dependencies

- `inventory` - Stock posting through `postInventoryLedger`, plus StorageLocation references
- `item-management` - Item references and primary-unit snapshots on shipment lines
- `purchase` - Drives inbound shipments and reads receipt matching evidence
- `account-payable` - Reads posted receipt quantities for three-way matching