@tailor-platform/erp-kit 0.4.1 → 0.5.0

package/src/modules/inventory/docs/features/stock-movement.md

@@ -0,0 +1,72 @@
+# Stock Movement
+
+## Overview
+
+Stock movements record the physical flow of goods across locations in the warehouse system. Every time inventory enters, leaves, or moves within the organization, a stock move record is created to capture the transaction. There are three movement types: goods receipts (inbound from suppliers), goods issues (outbound to customers or scrap), and internal transfers (between internal locations). Additionally, block and unblock operations shift stock between available and blocked states without physically moving it.
+
+Each movement follows a DRAFT to CONFIRMED to DONE state machine, ensuring that moves are reviewed before execution. When a movement reaches the DONE state, it automatically updates stock levels at both the source and destination locations via the stock-tracking feature. Virtual locations (supplier, customer, scrap) serve as logical endpoints for receipts and issues where no physical stock is tracked.
+
+## Business Purpose
+
+- Provide a complete audit trail of all inventory changes with who, what, when, where, and why
+- Enable goods receipt processing to increase on-hand stock when items arrive from suppliers
+- Enable goods issue processing to decrease on-hand stock when items are shipped to customers or scrapped
+- Support internal transfers to rebalance stock across warehouses, zones, or bin locations
+- Enforce a confirmation workflow so movements can be reviewed before stock levels are affected
+- Feed downstream processes such as inventory valuation, lot/batch tracking, and serial number tracking with movement data
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Create Movement] --> B[DRAFT]
+    B --> C{Action?}
+    C -->|Confirm| D[CONFIRMED]
+    C -->|Cancel| E[CANCELLED]
+    D --> F{Action?}
+    F -->|Execute| G[DONE]
+    F -->|Cancel| E
+    G --> H{Movement Type?}
+    H -->|Goods Receipt| I[Supplier Location *virtual*] --> I2[Warehouse Location]
+    H -->|Goods Issue| J[Warehouse Location] --> J2[Customer / Scrap Location *virtual*]
+    H -->|Internal Transfer| K[Source Location] --> K2[Destination Location]
+    I2 --> L[Update Stock Levels]
+    J2 --> L
+    K2 --> L
+```
+
+## Scenario Patterns
+
+- **Goods Receipt**: Items arrive from a supplier. A movement is created from the virtual supplier location to a warehouse receiving location, increasing on-hand stock at the destination once executed.
+- **Goods Issue (Sales)**: Items are shipped to a customer. A movement is created from a warehouse location to the virtual customer location, decreasing on-hand stock at the source once executed.
+- **Goods Issue (Scrap)**: Damaged or expired items are written off. A movement is created from a warehouse location to the virtual scrap location.
+- **Internal Transfer**: Items are relocated between warehouses or between zones within the same warehouse. Stock decreases at the source location and increases at the destination location.
+- **Draft Correction**: A movement in DRAFT status is found to have incorrect quantities or locations. The user updates the draft before confirming it.
+- **Stock Block**: Damaged or suspect items are blocked at a warehouse location. A block movement increases the blocked quantity and reduces available stock without physically moving the items. Requires a reason (e.g., damage, recall, quality hold).
+- **Stock Unblock**: After investigation, previously blocked items are released. An unblock movement decreases the blocked quantity and restores available stock.
+- **Cancellation Before Execution**: A confirmed movement is no longer needed (e.g., supplier shipment was rejected). The movement is cancelled before reaching DONE, so no stock levels are affected.
+- **Multi-line Movement**: A single receipt or shipment contains multiple items. Each item-location combination is recorded as a separate stock move line within the movement.
+
+## Test Cases
+
+- Stock movement follows DRAFT -> CONFIRMED -> DONE state machine
+- Movements in DRAFT or CONFIRMED state can be cancelled; DONE movements cannot be cancelled
+- Goods receipt creates a move from a virtual supplier location to a physical warehouse location
+- Goods issue creates a move from a physical warehouse location to a virtual customer or scrap location
+- Internal transfer creates a move between two physical warehouse locations
+- Executing a movement (transition to DONE) triggers stock level updates at both source and destination locations
+- Cancelling a movement does not affect stock levels
+- Each move line records item, quantity, unit of measure, source location, destination location, movement date, and reference
+- Quantity on a move line must be greater than zero
+- Source and destination locations must be different
+- Only items in ACTIVE status can be referenced in a stock movement
+- A goods issue cannot be executed if the source location has insufficient available (non-blocked) stock for the item
+- Block movement increases blocked quantity and is rejected if the requested quantity exceeds available stock
+- Unblock movement decreases blocked quantity and is rejected if the requested quantity exceeds currently blocked stock
+- Block and unblock movements require a reason code
+
+## Reference Links
+
+- [SAP Goods Movements (Material Documents)](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/f47baaae096c4cf58ad427a8f68493f6/4a28f2e8456c3040e10000000a42189e.html)
+- [Odoo Stock Move Model](https://www.odoo.com/documentation/17.0/developer/reference/backend/orm.html)
+- [Oracle Inventory Transactions](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/25a/fammi/inventory-transactions.html)

package/src/modules/inventory/docs/features/stock-tracking.md

@@ -0,0 +1,78 @@
+# Stock Tracking
+
+## Overview
+
+Stock Tracking provides real-time visibility into inventory quantities for every item at every storage location. The system maintains four core quantity types per item-location pair: on-hand (physically present), reserved (committed to outbound orders), incoming (expected from inbound orders), and blocked (unusable due to damage, recall, or other holds). Available quantity is derived as on-hand minus reserved minus blocked, giving an accurate picture of what can be promised to new demand.
+
+Quantities are updated automatically as stock movements are processed — goods receipts increase on-hand and clear incoming, goods issues decrease on-hand, reservations shift quantity between available and reserved, and block/unblock operations shift quantity between available and blocked. Each stock level record is scoped to a specific item and storage location, enabling granular tracking down to the bin level within a warehouse.
+
+## Business Purpose
+
+- Provides a single source of truth for current inventory positions across all warehouses and locations
+- Enables accurate available-to-promise calculations by separating on-hand from reserved and blocked quantities
+- Tracks incoming quantities so planners can see expected future supply without manual lookups
+- Supports multi-location visibility, allowing businesses to locate stock across warehouses, zones, and bins
+- Drives downstream decisions in sales (order promising), purchasing (reorder triggers), and manufacturing (material availability)
+- Maintains quantity accuracy through automatic updates from stock movements, eliminating manual ledger maintenance
+- Supports multi-unit-of-measure scenarios via UoM conversions from the primitives module
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Stock Movement Executed] --> B{Movement Type}
+    B -->|Goods Receipt| C[Increase On-Hand at Destination]
+    C --> C2[Decrease Incoming]
+    B -->|Goods Issue| D[Decrease On-Hand at Source]
+    B -->|Transfer| E[Decrease On-Hand at Source]
+    E --> F[Increase On-Hand at Destination]
+    B -->|Reservation| G[Increase Reserved]
+    B -->|Reservation Release| H[Decrease Reserved]
+    B -->|Block| BL[Increase Blocked]
+    B -->|Unblock| UB[Decrease Blocked]
+    C2 --> I[Recalculate Available Qty]
+    D --> I
+    F --> I
+    G --> I
+    H --> I
+    BL --> I
+    UB --> I
+    I --> J[Available = On-Hand - Reserved - Blocked]
+    J --> K[Stock Level Updated]
+```
+
+## Scenario Patterns
+
+- **Basic Stock Inquiry**: A warehouse operator checks the on-hand and available quantity of an item at a specific bin location before picking
+- **Available-to-Promise Check**: Sales checks available quantity (on-hand minus reserved minus blocked) across all locations to determine if a new order can be fulfilled
+- **Incoming Visibility**: A planner reviews incoming quantities to understand when expected purchase orders will replenish stock at a given warehouse
+- **Reservation Lifecycle**: A sales order reserves quantity, reducing available stock; upon shipment the reservation is released and on-hand is decremented via goods issue
+- **Multi-Location Lookup**: A transfer planner queries stock levels across multiple warehouses to identify the best source location for an internal transfer
+- **Stock Blocking**: A quality inspector or warehouse manager blocks a quantity of stock at a location due to damage, recall, or suspected defect; the blocked quantity is excluded from available stock and cannot be reserved or issued
+- **Stock Unblocking**: After investigation, blocked stock is released back to available inventory via an unblock operation
+- **Zero-Stock Detection**: The system identifies item-location pairs where available quantity has dropped to zero, signaling potential stockout risk
+- **UoM-Aware Tracking**: Stock is tracked in the item's base UoM; queries can request quantities converted to alternative UoMs using primitives module conversions
+
+## Test Cases
+
+- Stock level record is created per unique item-location pair on first movement
+- On-hand quantity increases when a goods receipt is processed for the item-location
+- On-hand quantity decreases when a goods issue is processed for the item-location
+- Incoming quantity increases when an inbound order is confirmed and decreases when the corresponding goods receipt is processed
+- Reserved quantity increases when stock is reserved and decreases when the reservation is released or fulfilled
+- Blocked quantity increases when stock is blocked and decreases when stock is unblocked
+- Available quantity always equals on-hand minus reserved minus blocked
+- Available quantity cannot go negative — reservation must be rejected if it would exceed available (on-hand minus reserved minus blocked)
+- Block operation must be rejected if the requested quantity would exceed available (on-hand minus reserved minus currently blocked)
+- Stock levels are tracked independently per storage location; a transfer decreases one location and increases another
+- Warehouse-level aggregation correctly sums quantities across all storage locations within the warehouse
+- Cross-warehouse query correctly sums quantities across all warehouses
+- Stock level quantities are stored in the item's base unit of measure
+- Concurrent stock movements to the same item-location produce correct final quantities (no lost updates)
+- Stock level record persists with zero quantities rather than being deleted, preserving location history
+
+## Reference Links
+
+- [SAP Inventory Management — Stock Overview](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/f18f0acdc5f04a35badc70e96e8d4549/4f36a7addfae4f32e10000000a11466f.html)
+- [Oracle Inventory — On-Hand Quantity](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/25a/famoh/inventory-on-hand-balances.html)
+- [NetSuite Inventory Management](https://www.netsuite.com/portal/resource/articles/inventory-management/inventory-management.shtml)

package/src/modules/inventory/docs/features/warehouse-management.md

@@ -0,0 +1,97 @@
+# Warehouse Management
+
+## Overview
+
+Warehouse Management defines the operational storage structure within an organization's physical facilities. A Warehouse represents a logical storage facility linked to an organizational Site, while StorageLocations (zones and bins) describe the internal layout within that warehouse. The organization module owns the Site entity (physical facility identity and address); the inventory module owns Warehouse and StorageLocation entities that layer operational storage concerns on top of a Site.
+
+Each warehouse tracks storage-relevant attributes such as storage conditions, capacity constraints, and operational status. StorageLocations form a tree hierarchy within a warehouse with a maximum depth of three levels: Warehouse → Zone → Bin. Zones group related areas (e.g., cold storage, bulk storage) and are direct children of the warehouse (parentId is null). Bins identify individual addressable slots where stock is placed and must reference a parent zone. Each StorageLocation carries a locationType of either 'zone' or 'bin'.
+
+Zone/bin management is optional. When granular location tracking is not needed, a warehouse with a single zone (and no bins) is sufficient for flat inventory operations. All other inventory features (stock tracking, stock movement, lot tracking, serial number tracking) reference StorageLocation.id as the spatial axis — stock quantities, lots, and serial numbers are always associated with a StorageLocation, never directly with a Warehouse.
+
+## Business Purpose
+
+Warehouses and storage locations serve as the spatial backbone for all inventory operations:
+
+- Map operational storage structures onto company-owned Sites, separating facility identity (organization) from storage layout (inventory)
+- Enable multi-warehouse operations across sites, supporting distributed inventory strategies
+- Provide granular bin-level addressing for stock placement and retrieval
+- Classify storage zones by condition (ambient, cold, hazardous) to enforce proper item placement
+- Track capacity at the warehouse and bin level to prevent over-storage and guide putaway decisions
+- Support stock movement routing by providing source and destination locations for transfers, receipts, and issues
+- Enable inventory counts and cycle counts scoped to specific zones or bins
+
+The lifecycle ensures:
+
+- Warehouses and storage locations are either ACTIVE (available for inventory operations) or INACTIVE (closed to new movements but preserved for historical records)
+- Deactivating a warehouse prevents new stock movements while retaining all historical transaction data
+- Storage locations can be individually deactivated without affecting the parent warehouse
+
+## Process Flow
+
+Warehouse and storage location setup follows a top-down configuration pattern:
+
+```mermaid
+flowchart TD
+    A[Select Organizational Site] --> B[Create Warehouse]
+    B --> C[Define Warehouse Attributes]
+    C --> D[Create Zones within Warehouse]
+    D --> E[Create Bins within Zones]
+    E --> F[Warehouse Ready for Operations]
+    F --> G{Zone/Bin no longer needed?}
+    G -->|Yes| H[Deactivate StorageLocation]
+    G -->|No| I[Continue Operations]
+    H --> J{Reopen location?}
+    J -->|Yes| K[Reactivate StorageLocation]
+    J -->|No| L[Location remains INACTIVE]
+```
+
+Warehouse lifecycle management:
+
+```mermaid
+stateDiagram-v2
+    [*] --> Active: createWarehouse
+    Active --> Inactive: deactivateWarehouse
+    Inactive --> Active: reactivateWarehouse
+```
+
+## Scenario Patterns
+
+- **Flat Warehouse Setup**: A small business creates a warehouse with a single zone and no bins. All stock movements and inventory tracking reference this single zone as the location. This is sufficient when granular bin-level tracking is not needed
+- **New Distribution Center Setup**: A company opens a new distribution site and creates a warehouse linked to that site. Zones are defined for receiving, bulk storage, picking, and shipping. Bins are created within each zone to provide addressable storage slots for inventory placement
+- **Cold Chain Warehouse**: A food distributor creates a warehouse with cold-storage zones maintained at specific temperature conditions. Items requiring refrigeration are directed to bins within these zones, ensuring compliance with storage requirements
+- **Multi-Warehouse Site**: A large manufacturing site operates multiple warehouses — one for raw materials, one for finished goods, and one for spare parts. Each warehouse is linked to the same site but has distinct zones and bin structures tailored to its purpose
+- **Warehouse Consolidation**: A company closes a regional warehouse by deactivating it after transferring all remaining stock to another facility. Historical movement records at the deactivated warehouse remain intact for audit purposes
+- **Zone Expansion**: An existing warehouse adds a new storage zone to accommodate increased inventory volume. New bins are created within the zone and immediately become available for stock placement
+- **Bin Deactivation for Maintenance**: A bin or zone is temporarily deactivated for maintenance or reconfiguration. No new stock can be placed there, but existing records and historical movements are preserved. Once maintenance completes, the location is reactivated
+- **Hazardous Materials Segregation**: A warehouse designates a specific zone for hazardous materials with appropriate storage condition classification, ensuring regulated items are stored separately from general inventory
+
+## Test Cases
+
+- A warehouse must reference an existing, ACTIVE site via siteId
+- A warehouse name is required and unique within the same site
+- Warehouse lifecycle follows ACTIVE <-> INACTIVE state machine
+- Deactivating a warehouse prevents new stock movements to/from that warehouse
+- Deactivating a warehouse does not delete or modify historical stock movement records
+- A storage location must reference an existing, ACTIVE warehouse via warehouseId
+- Each storage location has a locationType of 'zone' or 'bin'
+- A zone must be a direct child of the warehouse (parentId is null)
+- A bin must reference a parent zone within the same warehouse (parentId is a zone's id)
+- A bin cannot be a direct child of the warehouse; it must belong to a zone
+- Storage location name or code is required and unique within the same warehouse
+- Storage location lifecycle follows ACTIVE <-> INACTIVE state machine independently of its parent warehouse
+- Deactivating a zone does not automatically deactivate its child bins (explicit deactivation required)
+- Reactivating a storage location is only permitted if its parent warehouse is ACTIVE
+- A warehouse cannot be created under an INACTIVE or non-existent site
+- Multiple warehouses can exist for the same site
+- Storage condition classification (e.g., ambient, cold, hazardous) can be assigned to a warehouse or zone
+- Capacity attributes can be set on a warehouse or bin to track storage limits
+- Attempting to place stock into an INACTIVE storage location is rejected
+
+## Reference Links
+
+- [Stock Tracking](./stock-tracking.md) — tracks quantities per item per StorageLocation
+- [Stock Movement](./stock-movement.md) — uses StorageLocations as source and destination for goods flow
+- [Odoo Warehouses and Locations](https://www.odoo.com/documentation/19.0/applications/inventory_and_mrp/inventory/warehouses_storage.html)
+- [SAP Warehouse Structure](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/f1a0da84007f4621a36cf73cd38ee3d0/c4a850def48411d1a7020000e829fd11.html)
+- [Oracle Warehouse Management](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/25a/famwm/warehouse-management.html)
+- [Dynamics 365 Warehouse Configuration](https://learn.microsoft.com/en-us/dynamics365/supply-chain/warehousing/warehouse-configuration)

package/src/modules/inventory/docs/models/CostLayer.md

@@ -0,0 +1,37 @@
+# CostLayer
+
+## Description
+
+CostLayer represents an append-only record of inventory cost for FIFO (First In, First Out) valuation. Each cost layer is created when a goods receipt is executed for an item under a FIFO valuation policy, capturing the quantity received and its unit cost. When goods are issued, cost layers are consumed in oldest-first order, with the remainingQuantity field tracking the unconsumed portion.
+
+Cost layers are never modified after creation — only the remainingQuantity is decremented as stock is consumed.
+
+## Domain Model Definitions
+
+### Model type
+
+AppendOnly
+
+### Command Definitions
+
+- Cost layers are created internally by goods receipt execution under a FIFO valuation policy and consumed by goods issue execution
+
+### Query Definitions
+
+- [listCostLayers](../queries/ListCostLayers.md) - List cost layers by item or valuation policy for FIFO auditing
+
+### Models
+
+- CostLayer
+
+### Invariants
+
+- Created on goods receipt for items under a FIFO valuation policy
+- Consumed in oldest-first order on goods issue
+- Remaining quantity tracks the unconsumed portion of the original layer
+
+### Relationships
+
+- **References Item**: Each cost layer belongs to an Item from the item-management module
+- **References ValuationPolicy**: Each cost layer is associated with a FIFO valuation policy
+- **References StockMovement**: Each cost layer is linked to the stock movement that created it

package/src/modules/inventory/docs/models/InventoryAdjustment.md

@@ -0,0 +1,69 @@
+# InventoryAdjustment
+
+## Description
+
+InventoryAdjustment represents a correction to on-hand stock quantities at a specific storage location. Each adjustment has an `adjustmentType` that determines its behavior:
+
+- **CORRECTION**: Manual corrections to reconcile system records with physical reality — discrepancies from damage, theft, counting errors, receiving mistakes, or production variances. Confirmation generates a stock movement to/from a virtual "adjustment" location.
+- **SCRAP**: Controlled disposal of damaged, expired, defective, or obsolete stock. Confirmation moves stock to a virtual "scrap" location, reducing inventory valuation. For serial-tracked items, the serial number transitions to SCRAPPED state.
+
+Both types follow the same approval workflow: DRAFT → optionally PENDING_APPROVAL → APPROVED → CONFIRMED. Rejected adjustments can be revised back to DRAFT. Once confirmed, an adjustment is immutable — corrections require a new offsetting adjustment.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createInventoryAdjustment
+    Draft --> PendingApproval: submitInventoryAdjustment
+    Draft --> Confirmed: confirmInventoryAdjustment (no approval needed)
+    PendingApproval --> Approved: approveInventoryAdjustment
+    PendingApproval --> Rejected: rejectInventoryAdjustment
+    Rejected --> Draft: reviseInventoryAdjustment
+    Approved --> Confirmed: confirmInventoryAdjustment
+```
+
+### Command Definitions
+
+- [createInventoryAdjustment](../commands/CreateInventoryAdjustment.md) - Create a new inventory adjustment in DRAFT status
+- [submitInventoryAdjustment](../commands/SubmitInventoryAdjustment.md) - Submit a draft adjustment for approval
+- [approveInventoryAdjustment](../commands/ApproveInventoryAdjustment.md) - Approve a pending adjustment
+- [rejectInventoryAdjustment](../commands/RejectInventoryAdjustment.md) - Reject a pending adjustment
+- [reviseInventoryAdjustment](../commands/ReviseInventoryAdjustment.md) - Return a rejected adjustment to draft for revision
+- [confirmInventoryAdjustment](../commands/ConfirmInventoryAdjustment.md) - Confirm an approved or draft adjustment, applying the quantity change
+
+### Query Definitions
+
+- [getInventoryAdjustment](../queries/GetInventoryAdjustment.md) - Retrieve an inventory adjustment by id
+- [listInventoryAdjustments](../queries/ListInventoryAdjustments.md) - List inventory adjustments with optional filters
+
+### Models
+
+- InventoryAdjustment
+
+### Invariants
+
+- Reason code is required
+- adjustmentType is required (CORRECTION or SCRAP)
+- Draft adjustments do not affect on-hand quantities
+- Confirmation generates a stock movement to update stock levels
+- CORRECTION: stock movement to/from virtual adjustment location
+- SCRAP: stock movement to virtual scrap location; quantityDelta must be negative
+- SCRAP with serial number: serial transitions to SCRAPPED state on confirmation
+- Negative adjustment cannot reduce on-hand below zero (unless the organization permits negative stock)
+- Immutable after confirmation — corrections require a new offsetting adjustment
+- Rejected adjustments do not affect stock levels or valuation
+- Adjustments originating from a count session link back to the InventoryCount
+
+### Relationships
+
+- **References Item**: Each adjustment targets an Item from the item-management module
+- **References StorageLocation**: Each adjustment targets a specific storage location
+- **References InventoryCount (optional)**: Adjustments may be linked to an inventory count session (CORRECTION type only)
+- **References Lot (optional)**: For lot-tracked items, the specific lot being adjusted
+- **References SerialNumber (optional)**: For serial-tracked items, the specific serial number being adjusted

package/src/modules/inventory/docs/models/InventoryCount.md

@@ -0,0 +1,53 @@
+# InventoryCount
+
+## Description
+
+InventoryCount represents a physical inventory counting session used to verify system stock quantities against actual quantities on hand. Counts can be full (entire warehouse) or cycle (specific locations). The count follows a lifecycle from PLANNED through IN_PROGRESS to COMPLETED, with the option to cancel from either PLANNED or IN_PROGRESS states.
+
+Starting a count captures a snapshot of system quantities and optionally freezes stock movements for the counted locations. Completion unfreezes movements and finalizes the session.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Planned: createInventoryCount
+    Planned --> InProgress: startInventoryCount
+    InProgress --> Completed: completeInventoryCount
+    Planned --> Cancelled: cancelInventoryCount
+    InProgress --> Cancelled: cancelInventoryCount
+```
+
+### Command Definitions
+
+- [createInventoryCount](../commands/CreateInventoryCount.md) - Create a new inventory count session in PLANNED status
+- [startInventoryCount](../commands/StartInventoryCount.md) - Start the count, capturing system quantity snapshots and optionally freezing stock
+- [completeInventoryCount](../commands/CompleteInventoryCount.md) - Complete the count session after all lines are resolved
+- [cancelInventoryCount](../commands/CancelInventoryCount.md) - Cancel a planned or in-progress count session
+
+### Query Definitions
+
+- [getInventoryCount](../queries/GetInventoryCount.md) - Retrieve an inventory count session by id
+- [listInventoryCounts](../queries/ListInventoryCounts.md) - List inventory count sessions with optional filters
+
+### Models
+
+- InventoryCount
+
+### Invariants
+
+- Cannot be finalized until all count lines are in a terminal status (APPROVED or REJECTED)
+- Freezing stock blocks movements for the counted locations during the count
+- Unfreezing resumes movements after completion
+- A snapshot captures system quantities at the start of the count
+
+### Relationships
+
+- **Has many InventoryCountLine**: Each count session contains lines for individual item-location combinations
+- **References Warehouse (optional)**: A full count may target an entire warehouse
+- **References StorageLocation (optional)**: A cycle count may target specific storage locations

package/src/modules/inventory/docs/models/InventoryCountLine.md

@@ -0,0 +1,53 @@
+# InventoryCountLine
+
+## Description
+
+InventoryCountLine represents a single item-location combination within an inventory count session. Each line captures the system quantity (snapshot at count start) and the counted quantity (entered by the counter), with the variance computed as the difference. Lines follow a review workflow: PENDING → APPROVED/REJECTED/RECOUNT.
+
+Within-tolerance variances are auto-approved. Exceeding-tolerance variances require explicit approval. Approved variances generate inventory adjustments with the reason "inventory-count". Blind count mode hides system quantities from counters.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Pending: startInventoryCount (creates lines)
+    Pending --> Approved: approveCountLine (or auto-approve within tolerance)
+    Pending --> Rejected: rejectCountLine
+    Pending --> Recount: rejectCountLine (with recount)
+    Recount --> Pending: recordCountLine (re-enters count)
+    Rejected --> Pending: recordCountLine (re-counted)
+```
+
+### Command Definitions
+
+- [recordCountLine](../commands/RecordCountLine.md) - Record or re-record the counted quantity for a count line
+- [approveCountLine](../commands/ApproveCountLine.md) - Approve a count line variance
+- [rejectCountLine](../commands/RejectCountLine.md) - Reject a count line or request a recount
+
+### Query Definitions
+
+- Inventory count lines are included in inventory count queries
+
+### Models
+
+- InventoryCountLine
+
+### Invariants
+
+- Variance = countedQuantity - systemQuantity
+- Within-tolerance variances are auto-approved
+- Exceeding-tolerance variances require explicit approval
+- Approved variances generate inventory adjustments with reason "inventory-count"
+- Blind count mode hides system quantities from counters
+
+### Relationships
+
+- **Belongs to InventoryCount**: Each count line belongs to a single inventory count session
+- **References Item**: Each count line references an Item from the item-management module
+- **References StorageLocation**: Each count line targets a specific storage location

package/src/modules/inventory/docs/models/ItemValuation.md

@@ -0,0 +1,38 @@
+# ItemValuation
+
+## Description
+
+ItemValuation tracks the aggregate inventory value for a specific item under a specific valuation policy. It maintains the total quantity, total value, and a computed cost per unit (totalValue / totalQuantity). Item valuations are updated internally when stock movements are executed.
+
+Internal transfers do not change item-level valuation since stock remains within the same inventory system. Valuation changes emit events for downstream consumption by accounting and reporting modules.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- Item valuations are updated internally by stock movement execution
+
+### Query Definitions
+
+- [getItemValuation](../queries/GetItemValuation.md) - Retrieve the valuation for a specific item under a specific policy
+- [listItemValuations](../queries/ListItemValuations.md) - List item valuations with optional filters
+
+### Models
+
+- ItemValuation
+
+### Invariants
+
+- Unique per item-valuationPolicy pair
+- Cost per unit = totalValue / totalQuantity
+- Internal transfers do not change item-level valuation
+- Valuation changes emit events for downstream consumption
+
+### Relationships
+
+- **References Item**: Each item valuation belongs to an Item from the item-management module
+- **References ValuationPolicy**: Each item valuation is associated with a valuation policy

package/src/modules/inventory/docs/models/Lot.md

@@ -0,0 +1,45 @@
+# Lot
+
+## Description
+
+Lot (also known as batch) represents a production or procurement batch of an item, enabling forward and backward traceability. Each lot has a unique lot number per item and may carry manufacture date, expiration date, and supplier lot reference metadata. Lots track their consumption status: ACTIVE when stock remains, FULLY_CONSUMED when on-hand reaches zero across all locations.
+
+Goods receipts for lot-tracked items must specify a lot. Expired lots are excluded from picking operations.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createLot](../commands/CreateLot.md) - Create a new lot for a specific item
+- [updateLot](../commands/UpdateLot.md) - Update mutable fields (manufactureDate, expirationDate, supplierLotReference) before fully consumed
+
+### Query Definitions
+
+- [getLot](../queries/GetLot.md) - Retrieve a lot by id or lot number
+- [listLots](../queries/ListLots.md) - List lots with optional filtering by item, warehouse, and status
+- [listExpiringLots](../queries/ListExpiringLots.md) - List lots approaching or past their expiration date
+- [traceLotForward](../queries/TraceLotForward.md) - Trace a lot forward through downstream movements
+- [traceLotBackward](../queries/TraceLotBackward.md) - Trace a lot backward to its origin movements
+
+### Models
+
+- Lot
+
+### Invariants
+
+- Lot number must be unique per item
+- Lot number is immutable after creation
+- Manufacture date, expiration date, and supplier lot reference are updatable before fully consumed
+- Goods receipt for a lot-tracked item must specify a lot
+- Expired lots are excluded from picking
+- Lots with zero on-hand across all locations are marked FULLY_CONSUMED
+- Multiple active lots for the same item at the same location are allowed
+
+### Relationships
+
+- **References Item**: Each lot belongs to an Item from the item-management module
+- **Has many LotStockLevel**: A lot tracks stock levels across multiple storage locations

package/src/modules/inventory/docs/models/LotStockLevel.md

@@ -0,0 +1,34 @@
+# LotStockLevel
+
+## Description
+
+LotStockLevel tracks the on-hand quantity of a specific lot at a specific storage location. It provides the lot-level granularity needed for traceability and FEFO (First Expired, First Out) picking strategies. Lot stock levels are updated internally when stock movements referencing a lot are executed.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- Lot stock levels are updated internally by stock movement execution
+
+### Query Definitions
+
+- Lot stock levels are included in lot queries
+
+### Models
+
+- LotStockLevel
+
+### Invariants
+
+- Unique per lot-storageLocation pair
+- Goods issue cannot exceed the lot's on-hand quantity at the specified location
+- Internal transfer preserves the lot association
+
+### Relationships
+
+- **Belongs to Lot**: Each lot stock level belongs to a single lot
+- **References StorageLocation**: Each lot stock level tracks quantity at a specific storage location

package/src/modules/inventory/docs/models/SerialNumber.md

@@ -0,0 +1,53 @@
+# SerialNumber
+
+## Description
+
+SerialNumber represents a unique identifier assigned to an individual unit of an item, enabling unit-level traceability throughout the item's lifecycle. Serial numbers follow a state machine: AVAILABLE (in stock) → ISSUED (dispatched) → RETURNED (received back) → AVAILABLE (restocked) or SCRAPPED (disposed). SCRAPPED is a terminal state.
+
+Serial-tracked items always have a quantity of exactly 1 per serial number. State transitions are driven by stock movements rather than direct commands.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Available: assignSerialNumber
+    Available --> Issued: executeStockMovement (goods issue)
+    Issued --> Returned: executeStockMovement (return)
+    Returned --> Available: restock
+    Returned --> Scrapped: scrap
+    Available --> Scrapped: scrap
+```
+
+### Command Definitions
+
+- [assignSerialNumber](../commands/AssignSerialNumber.md) - Assign a serial number to an item at a storage location
+
+### Query Definitions
+
+- [getSerialNumber](../queries/GetSerialNumber.md) - Retrieve a serial number by id or serial number value
+- [listSerialNumbers](../queries/ListSerialNumbers.md) - List serial numbers by item, storage location, or status
+- [getSerialNumberHistory](../queries/GetSerialNumberHistory.md) - Retrieve the full movement history of a serial number
+
+### Models
+
+- SerialNumber
+
+### Invariants
+
+- Quantity is always exactly 1
+- Serial number must be unique per item type (different items may share the same serial number)
+- Serial number is immutable after assignment
+- SCRAPPED is a terminal state
+- ISSUED cannot transition directly to AVAILABLE — must pass through RETURNED
+- State transitions are driven by stock movements
+
+### Relationships
+
+- **References Item**: Each serial number belongs to an Item from the item-management module
+- **References StorageLocation**: Each serial number tracks its current storage location