@tailor-platform/erp-kit 0.4.1 → 0.5.0

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

@@ -0,0 +1,41 @@
+# StockLevel
+
+## Description
+
+StockLevel tracks the current quantity of a specific item at a specific storage location. It maintains four quantity buckets: on-hand, reserved, incoming, and blocked. The available quantity is derived as on-hand minus reserved minus blocked. Stock levels are updated internally by stock movement execution, reservation operations, and block/unblock operations.
+
+Stock level records persist even when all quantities reach zero — they are never deleted.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- Stock levels are updated internally by stock movement execution, reservation, and block/unblock operations
+
+### Query Definitions
+
+- [getStockLevel](../queries/GetStockLevel.md) - Retrieve the stock level for a specific item at a specific location
+- [listStockLevels](../queries/ListStockLevels.md) - List stock levels with optional filters
+- [getWarehouseStockSummary](../queries/GetWarehouseStockSummary.md) - Retrieve aggregated stock summary for a warehouse
+
+### Models
+
+- StockLevel
+
+### Invariants
+
+- Unique per item-storageLocation pair
+- Available quantity = onHand - reserved - blocked
+- Available quantity cannot go negative (reservation or block rejected if it would exceed available)
+- Quantities are stored in the item's base unit of measure
+- Records persist with zero quantities and are not deleted
+- Concurrent movements must produce correct final quantities
+
+### Relationships
+
+- **References Item**: Each stock level references an Item from the item-management module
+- **References StorageLocation**: Each stock level belongs to a specific storage location

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

@@ -0,0 +1,44 @@
+# StockMoveLine
+
+## Description
+
+StockMoveLine represents a single line item within a stock movement, specifying the item, quantity, source location, and destination location for the movement. Lines may optionally reference a lot or serial number for tracked items. Stock move lines are managed as part of the parent StockMovement lifecycle.
+
+The interpretation of source and destination locations depends on the movement type: goods receipts move from a virtual supplier location to a warehouse location, goods issues move from a warehouse location to a virtual customer or scrap location, and internal transfers move between physical warehouse locations.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- Stock move lines are managed as part of the StockMovement lifecycle
+
+### Query Definitions
+
+- Stock move lines are included in stock movement queries
+
+### Models
+
+- StockMoveLine
+
+### Invariants
+
+- Quantity must be greater than 0
+- Source and destination locations must be different
+- Only ACTIVE items can be referenced
+- Goods receipt: source is a virtual supplier location, destination is a warehouse location
+- Goods issue: source is a warehouse location, destination is a virtual customer or scrap location
+- Internal transfer: both source and destination are physical warehouse locations
+- Goods issue is rejected if insufficient available stock at the source location
+
+### Relationships
+
+- **Belongs to StockMovement**: Each line belongs to a single stock movement
+- **References Item**: Each line references an Item from the item-management module
+- **References StorageLocation (source)**: The location stock is moved from
+- **References StorageLocation (destination)**: The location stock is moved to
+- **References Lot (optional)**: For lot-tracked items, the specific lot being moved
+- **References SerialNumber (optional)**: For serial-tracked items, the specific serial number being moved

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

@@ -0,0 +1,52 @@
+# StockMovement
+
+## Description
+
+StockMovement represents a planned or executed movement of stock within the inventory system. Movements follow a lifecycle from DRAFT through CONFIRMED to DONE, with the option to cancel from DRAFT or CONFIRMED states. Movement types include goods receipt, goods issue, internal transfer, block, and unblock.
+
+Executing a movement (transitioning to DONE) triggers the actual stock level updates. Cancelling a movement does not reverse any stock level changes. Block and unblock movements require a reason code.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createStockMovement
+    Draft --> Confirmed: confirmStockMovement
+    Confirmed --> Done: executeStockMovement
+    Draft --> Cancelled: cancelStockMovement
+    Confirmed --> Cancelled: cancelStockMovement
+```
+
+### Command Definitions
+
+- [createStockMovement](../commands/CreateStockMovement.md) - Create a new stock movement in DRAFT status
+- [updateStockMovement](../commands/UpdateStockMovement.md) - Update mutable fields of a draft stock movement
+- [confirmStockMovement](../commands/ConfirmStockMovement.md) - Confirm a draft stock movement for execution
+- [executeStockMovement](../commands/ExecuteStockMovement.md) - Execute a confirmed movement, triggering stock level updates
+- [cancelStockMovement](../commands/CancelStockMovement.md) - Cancel a draft or confirmed stock movement
+
+### Query Definitions
+
+- [getStockMovement](../queries/GetStockMovement.md) - Retrieve a stock movement by id with all movement lines
+- [listStockMovements](../queries/ListStockMovements.md) - List stock movements with optional filters
+
+### Models
+
+- StockMovement
+
+### Invariants
+
+- DONE movements cannot be cancelled
+- Cancelling a movement does not affect stock levels
+- Executing a movement (transitioning to DONE) triggers stock level updates
+- Block and unblock movements require a reason code
+
+### Relationships
+
+- **Has many StockMoveLine**: Each stock movement contains one or more movement lines specifying items and quantities

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

@@ -0,0 +1,55 @@
+# StorageLocation
+
+## Description
+
+StorageLocation represents a specific area within a warehouse where stock is stored. Locations follow a hierarchical structure: zones are top-level locations (parentId is null) and bins are nested under zones. The maximum depth is three levels (warehouse → zone → bin). Each location has a lifecycle state machine (ACTIVE ↔ INACTIVE) and can specify storage conditions and capacity.
+
+Stock cannot be placed into an INACTIVE location. Deactivating a zone does not automatically deactivate its child bins.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Active: createStorageLocation
+    Active --> Inactive: deactivateStorageLocation
+    Inactive --> Active: reactivateStorageLocation
+```
+
+### Command Definitions
+
+- [createStorageLocation](../commands/CreateStorageLocation.md) - Create a new storage location (zone or bin) within a warehouse
+- [updateStorageLocation](../commands/UpdateStorageLocation.md) - Update mutable fields (name, code, storageCondition, capacity) of a storage location
+- [deactivateStorageLocation](../commands/DeactivateStorageLocation.md) - Deactivate a storage location to prevent new stock placement
+- [reactivateStorageLocation](../commands/ReactivateStorageLocation.md) - Reactivate a previously deactivated storage location
+
+### Query Definitions
+
+- [getStorageLocation](../queries/GetStorageLocation.md) - Retrieve a storage location by id with stock levels
+- [listStorageLocations](../queries/ListStorageLocations.md) - List storage locations with optional filters
+
+### Models
+
+- StorageLocation
+
+### Invariants
+
+- Name or code must be unique within the same warehouse
+- A zone has a null parentId
+- A bin must have a parent zone within the same warehouse
+- Maximum depth is 3 levels (warehouse → zone → bin)
+- Reactivation is only allowed if the parent warehouse is ACTIVE
+- Deactivating a zone does NOT auto-deactivate child bins
+- Placing stock into an INACTIVE location is rejected
+
+### Relationships
+
+- **Belongs to Warehouse**: Each storage location belongs to a single warehouse
+- **Self-referential parent**: Bins reference a parent zone via parentId
+- **Has many StockLevel**: A storage location tracks stock levels for multiple items
+- **Referenced by StockMoveLine**: Stock move lines reference storage locations as source or destination

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

@@ -0,0 +1,38 @@
+# ValuationPolicy
+
+## Description
+
+ValuationPolicy defines the costing method used to value inventory for a set of items. Supported costing methods are FIFO (First In, First Out), AVCO (Weighted Average Cost), and STANDARD_COST (fixed standard cost rate). When using STANDARD_COST, the standard cost rate must be specified.
+
+Updating the standard cost rate on a STANDARD_COST policy triggers a revaluation event for all items associated with the policy.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createValuationPolicy](../commands/CreateValuationPolicy.md) - Create a new valuation policy with a costing method
+- [updateValuationPolicy](../commands/UpdateValuationPolicy.md) - Update a valuation policy (e.g., change standard cost rate)
+
+### Query Definitions
+
+- [getValuationPolicy](../queries/GetValuationPolicy.md) - Retrieve a valuation policy by id
+- [listValuationPolicies](../queries/ListValuationPolicies.md) - List valuation policies, optionally filtered by costing method
+
+### Models
+
+- ValuationPolicy
+
+### Invariants
+
+- Name is required
+- Standard cost rate is required when costing method is STANDARD_COST
+- Updating the standard cost rate triggers a revaluation event
+
+### Relationships
+
+- **Has many ItemValuation**: A valuation policy is associated with multiple item valuations
+- **Has many CostLayer**: For FIFO policies, cost layers are tracked under the valuation policy

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

@@ -0,0 +1,50 @@
+# Warehouse
+
+## Description
+
+Warehouse represents a physical storage facility within a site. Each warehouse belongs to exactly one site and has a lifecycle state machine (ACTIVE ↔ INACTIVE). Warehouses can specify storage conditions (ambient, cold, hazardous) and optional capacity. Multiple warehouses may exist under the same site, but each must have a unique name within that site.
+
+Deactivating a warehouse prevents new stock movements into or out of the warehouse but preserves all historical data.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Active: createWarehouse
+    Active --> Inactive: deactivateWarehouse
+    Inactive --> Active: reactivateWarehouse
+```
+
+### Command Definitions
+
+- [createWarehouse](../commands/CreateWarehouse.md) - Create a new warehouse under a site in ACTIVE status
+- [updateWarehouse](../commands/UpdateWarehouse.md) - Update mutable fields (name, storageCondition, capacity) of an existing warehouse
+- [deactivateWarehouse](../commands/DeactivateWarehouse.md) - Deactivate a warehouse to prevent new stock movements
+- [reactivateWarehouse](../commands/ReactivateWarehouse.md) - Reactivate a previously deactivated warehouse
+
+### Query Definitions
+
+- [getWarehouse](../queries/GetWarehouse.md) - Retrieve a warehouse by id with storage locations
+- [listWarehouses](../queries/ListWarehouses.md) - List warehouses with optional filters
+
+### Models
+
+- Warehouse
+
+### Invariants
+
+- Name must be unique within the same site
+- Must reference an ACTIVE site
+- Multiple warehouses per site are allowed
+- Deactivating a warehouse prevents new stock movements but preserves history
+
+### Relationships
+
+- **References Site**: Each warehouse references a Site from the organization module
+- **Has many StorageLocation**: A warehouse contains multiple storage locations (zones and bins)

package/src/modules/inventory/docs/queries/GetInventoryAdjustment.md

@@ -0,0 +1,40 @@
+# GetInventoryAdjustment
+
+## Overview
+
+GetInventoryAdjustment retrieves a single inventory adjustment by id. It returns the full record including current status, reason code, quantity change, and references to the associated item, storage location, and optional lot or serial number. This serves as the detail view for reviewing or approving an adjustment.
+
+## Business Rules
+
+- Requires `id`
+- Returns the full InventoryAdjustment record including:
+  - `adjustmentType` (CORRECTION or SCRAP)
+  - Current status (Draft, PendingApproval, Approved, Rejected, Confirmed)
+  - `itemId`, `storageLocationId`, `quantityDelta`, `reasonCode`
+  - Optional `lotId`, `serialNumberId`, `inventoryCountId`
+- Returns null if no matching adjustment is found
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive id] --> B[SELECT from InventoryAdjustment where id matches]
+    B --> C{Adjustment found?}
+    C -->|Yes| D[Return InventoryAdjustment record]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INVENTORY_ADJUSTMENT_NOT_FOUND**: No adjustment matches the given id — caller receives null
+
+## Test Cases
+
+- returns adjustment when found
+- returns null when not found
+- includes status and reason code
+- includes optional lot and serial number references

package/src/modules/inventory/docs/queries/GetInventoryCount.md

@@ -0,0 +1,43 @@
+# GetInventoryCount
+
+## Overview
+
+GetInventoryCount retrieves a single inventory count document with all its count lines. This serves as the detail view for a specific physical inventory count, including variance calculations and line-level status.
+
+## Business Rules
+
+- Requires `id`
+- Returns the full InventoryCount record with nested InventoryCountLine records
+- Each count line includes:
+  - Expected quantity (from system)
+  - Counted quantity (from physical count)
+  - Variance (counted - expected)
+  - Line status: `pending`, `approved`, `rejected`, or `recount`
+- Returns error if the inventory count document is not found
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive id] --> B[SELECT from InventoryCount where id matches]
+    B --> C{Count found?}
+    C -->|Yes| D[Include all InventoryCountLine records]
+    D --> E[Compute variance for each line]
+    E --> F[Return InventoryCount with lines]
+    C -->|No| G[Return COUNT_NOT_FOUND error]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COUNT_NOT_FOUND**: No inventory count document matches the given id
+
+## Test Cases
+
+- returns count with lines when found
+- includes variance for each line
+- returns error when not found
+- includes line status (pending/approved/rejected/recount)

package/src/modules/inventory/docs/queries/GetItemValuation.md

@@ -0,0 +1,42 @@
+# GetItemValuation
+
+## Overview
+
+GetItemValuation retrieves the current valuation summary for an item — total quantity, total value, and cost per unit. It includes the costing method from the associated valuation policy.
+
+## Business Rules
+
+- Requires `itemId` and `valuationPolicyId`
+- Returns a single ItemValuation record containing:
+  - `totalQuantity` — total inventory quantity for the item
+  - `totalValue` — total monetary value of inventory
+  - `costPerUnit` — computed as `totalValue / totalQuantity`
+  - `costingMethod` — the costing method from the valuation policy (e.g., FIFO, weighted average, standard cost)
+- Includes valuation policy details in the response
+- Returns error if no valuation record exists for the item
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive itemId and valuationPolicyId] --> B[SELECT from ItemValuation where itemId and valuationPolicyId match]
+    B --> C{Valuation found?}
+    C -->|Yes| D[Include valuation policy details]
+    D --> E[Return ItemValuation record]
+    C -->|No| F[Return ITEM_VALUATION_NOT_FOUND error]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ITEM_VALUATION_NOT_FOUND**: No valuation record exists for the specified item
+
+## Test Cases
+
+- returns valuation when found
+- includes costing method from policy
+- returns error when not found
+- costPerUnit equals totalValue divided by totalQuantity

package/src/modules/inventory/docs/queries/GetLot.md

@@ -0,0 +1,42 @@
+# GetLot
+
+## Overview
+
+GetLot retrieves a single lot by id or by lotNumber + itemId combination. The input is a union type — callers specify either an id or a lotNumber-itemId pair. This serves as the core lot lookup for traceability, expiration checks, and lot lifecycle commands.
+
+## Business Rules
+
+- Accepts one of two lookup variants:
+  - `{ id }` — retrieves by unique identifier
+  - `{ lotNumber, itemId }` — retrieves by lot number and item combination
+- Returns the full Lot record including current stock across locations (associated LotStockLevel records)
+- Returns null if no matching lot is found
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input] --> B{Which field?}
+    B -->|id| C[SELECT from Lot where id = input.id]
+    B -->|lotNumber + itemId| D[SELECT from Lot where lotNumber = input.lotNumber AND itemId = input.itemId]
+    C --> E{Lot found?}
+    D --> E
+    E -->|Yes| F[Include associated LotStockLevel records]
+    F --> G[Return Lot record]
+    E -->|No| H[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **LOT_NOT_FOUND**: No lot matches the given criteria — caller receives null
+
+## Test Cases
+
+- returns lot when found by id
+- returns lot when found by lotNumber and itemId
+- returns null when not found
+- includes lot stock levels across locations

package/src/modules/inventory/docs/queries/GetSerialNumber.md

@@ -0,0 +1,43 @@
+# GetSerialNumber
+
+## Overview
+
+GetSerialNumber retrieves a serial number record by id or by serialNumber + itemId combination. The input is a union type — callers specify either an id or a serialNumber-itemId pair. It includes the current state and storage location of the serial number.
+
+## Business Rules
+
+- Accepts one of two lookup variants:
+  - `{ id }` — retrieves by unique identifier
+  - `{ serialNumber, itemId }` — retrieves by serial number and item combination
+- Returns the full SerialNumber record including:
+  - Current status (e.g., available, reserved, in-use, scrapped)
+  - Current `storageLocationId`
+- Returns null if no matching serial number is found
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input] --> B{Which field?}
+    B -->|id| C[SELECT from SerialNumber where id = input.id]
+    B -->|serialNumber + itemId| D[SELECT from SerialNumber where serialNumber = input.serialNumber AND itemId = input.itemId]
+    C --> E{Serial found?}
+    D --> E
+    E -->|Yes| F[Return SerialNumber record with status and location]
+    E -->|No| G[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **SERIAL_NUMBER_NOT_FOUND**: No serial number matches the given criteria — caller receives null
+
+## Test Cases
+
+- returns serial when found by id
+- returns serial when found by serialNumber and itemId
+- returns null when not found
+- includes current status and location

package/src/modules/inventory/docs/queries/GetSerialNumberHistory.md

@@ -0,0 +1,50 @@
+# GetSerialNumberHistory
+
+## Overview
+
+GetSerialNumberHistory retrieves the full transaction history for a serial number — all state transitions, stock movements, and location changes. This provides a complete audit trail ordered chronologically.
+
+## Business Rules
+
+- Requires `serialNumberId`
+- Returns an ordered list of history entries, each containing:
+  - `timestamp` — when the event occurred
+  - `fromState` — previous serial number status
+  - `toState` — new serial number status
+  - `stockMovementId` — reference to the associated stock movement
+  - `fromLocationId` — previous storage location
+  - `toLocationId` — new storage location
+- Queries all StockMoveLine records referencing this serial number
+- Results are ordered by movement date ascending (oldest first)
+- Returns error if the serial number does not exist
+- Returns an empty history for a newly created serial with no movements
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive serialNumberId] --> B{Serial number exists?}
+    B -->|No| C[Return SERIAL_NUMBER_NOT_FOUND error]
+    B -->|Yes| D[SELECT from StockMoveLine where serialNumberId matches]
+    D --> E[JOIN with StockMovement for dates and references]
+    E --> F[Order by movement date ascending]
+    F --> G{Records found?}
+    G -->|Yes| H[Return ordered list of history entries]
+    G -->|No| I[Return empty history]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **SERIAL_NUMBER_NOT_FOUND**: The specified serial number does not exist
+
+## Test Cases
+
+- returns full history ordered by date
+- includes state transitions
+- includes location changes
+- returns error when serial not found
+- returns empty history for newly created serial

package/src/modules/inventory/docs/queries/GetStockLevel.md

@@ -0,0 +1,42 @@
+# GetStockLevel
+
+## Overview
+
+GetStockLevel retrieves the stock level for a specific item at a specific storage location. The input requires both an itemId and a storageLocationId. It returns the on-hand, reserved, incoming, blocked, and computed available quantity. This serves as the core stock inquiry for availability checks, reservation validation, and replenishment decisions.
+
+## Business Rules
+
+- Requires both `itemId` and `storageLocationId`
+- Returns a single StockLevel record containing:
+  - `onHand` — physical quantity present
+  - `reserved` — quantity allocated to outbound orders
+  - `incoming` — quantity expected from inbound orders
+  - `blocked` — quantity held for quality or other reasons
+  - `availableQuantity` — computed as `onHand - reserved - blocked`
+- Returns null if no stock level record exists for the item-location pair
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive itemId and storageLocationId] --> B[SELECT from StockLevel where itemId and storageLocationId match]
+    B --> C{Record found?}
+    C -->|Yes| D[Compute availableQuantity = onHand - reserved - blocked]
+    D --> E[Return StockLevel record]
+    C -->|No| F[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **STOCK_LEVEL_NOT_FOUND**: No stock level record exists for the given item-location pair — caller receives null
+
+## Test Cases
+
+- returns stock level when found
+- returns null when not found
+- correctly computes available quantity
+- available equals onHand minus reserved minus blocked

package/src/modules/inventory/docs/queries/GetStockMovement.md

@@ -0,0 +1,41 @@
+# GetStockMovement
+
+## Overview
+
+GetStockMovement retrieves a single stock movement by id with all its movement lines. It returns the full record including current status, movement type, and nested StockMoveLine records with item, quantity, and location details.
+
+## Business Rules
+
+- Requires `id`
+- Returns the full StockMovement record with nested StockMoveLine records
+- Each movement line includes:
+  - `itemId`, `quantity`
+  - `sourceStorageLocationId` and/or `destinationStorageLocationId` depending on movement type
+  - Optional `lotId`, `serialNumberId`
+- Returns null if no matching stock movement is found
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive id] --> B[SELECT from StockMovement where id matches]
+    B --> C{Movement found?}
+    C -->|Yes| D[Include all StockMoveLine records]
+    D --> E[Return StockMovement with lines]
+    C -->|No| F[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **STOCK_MOVEMENT_NOT_FOUND**: No stock movement matches the given id — caller receives null
+
+## Test Cases
+
+- returns stock movement when found
+- returns null when not found
+- includes all movement lines
+- includes source and destination locations per line

package/src/modules/inventory/docs/queries/GetStorageLocation.md

@@ -0,0 +1,40 @@
+# GetStorageLocation
+
+## Overview
+
+GetStorageLocation retrieves a single storage location by id. It returns the full record including current status, hierarchy information (parent zone), storage condition, capacity, and stock levels at this location.
+
+## Business Rules
+
+- Requires `id`
+- Returns the full StorageLocation record including:
+  - Current status (Active, Inactive)
+  - `name`, `code`, `warehouseId`, `parentId`, `storageCondition`, `capacity`
+  - Associated StockLevel records at this location
+- Returns null if no matching storage location is found
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive id] --> B[SELECT from StorageLocation where id matches]
+    B --> C{Storage location found?}
+    C -->|Yes| D[Include associated StockLevel records]
+    D --> E[Return StorageLocation record]
+    C -->|No| F[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **STORAGE_LOCATION_NOT_FOUND**: No storage location matches the given id — caller receives null
+
+## Test Cases
+
+- returns storage location when found
+- returns null when not found
+- includes associated stock levels
+- includes parent zone reference for bins