@tailor-platform/erp-kit 0.4.0 → 0.5.0

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

@@ -0,0 +1,38 @@
+# GetValuationPolicy
+
+## Overview
+
+GetValuationPolicy retrieves a single valuation policy by its id. It returns the full policy record including the costing method (FIFO, AVCO, or STANDARD_COST) and the standard cost rate when applicable. This query supports policy lookup for item valuation configuration and auditing.
+
+## Business Rules
+
+- Requires `id` as input
+- Returns the full ValuationPolicy record including:
+  - `name` — policy name
+  - `costingMethod` — one of FIFO, AVCO, STANDARD_COST
+  - `standardCostRate` — present only when costingMethod is STANDARD_COST
+- Returns null if no valuation policy exists for the given id
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive id] --> B[SELECT from ValuationPolicy where id matches]
+    B --> C{Record found?}
+    C -->|Yes| D[Return ValuationPolicy record]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **VALUATION_POLICY_NOT_FOUND**: No valuation policy exists for the given id — caller receives null
+
+## Test Cases
+
+- returns valuation policy when found by id
+- returns null when not found
+- includes costing method and standard cost rate

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

@@ -0,0 +1,40 @@
+# GetWarehouse
+
+## Overview
+
+GetWarehouse retrieves a single warehouse by id. It returns the full record including current status, storage condition, capacity, and the list of storage locations within the warehouse.
+
+## Business Rules
+
+- Requires `id`
+- Returns the full Warehouse record including:
+  - Current status (Active, Inactive)
+  - `name`, `siteId`, `storageCondition`, `capacity`
+  - Associated StorageLocation records
+- Returns null if no matching warehouse is found
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive id] --> B[SELECT from Warehouse where id matches]
+    B --> C{Warehouse found?}
+    C -->|Yes| D[Include associated StorageLocation records]
+    D --> E[Return Warehouse record]
+    C -->|No| F[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **WAREHOUSE_NOT_FOUND**: No warehouse matches the given id — caller receives null
+
+## Test Cases
+
+- returns warehouse when found
+- returns null when not found
+- includes associated storage locations
+- includes storage condition and capacity

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

@@ -0,0 +1,50 @@
+# GetWarehouseStockSummary
+
+## Overview
+
+GetWarehouseStockSummary aggregates stock quantities across all storage locations within a warehouse for each item. It provides a warehouse-level inventory overview and supports optional filtering to a specific item.
+
+## Business Rules
+
+- Requires `warehouseId`
+- Optionally accepts `itemId` to filter to a specific item
+- Sums quantities across all **active** storage locations in the warehouse, grouped by item
+- Returns aggregated records containing:
+  - `itemId`
+  - `totalOnHand` — sum of onHand across locations
+  - `totalReserved` — sum of reserved across locations
+  - `totalIncoming` — sum of incoming across locations
+  - `totalBlocked` — sum of blocked across locations
+  - `totalAvailable` — sum of available across locations
+- Excludes inactive storage locations from aggregation
+- Returns error if warehouse does not exist
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive warehouseId and optional itemId] --> B{Warehouse exists?}
+    B -->|No| C[Return WAREHOUSE_NOT_FOUND error]
+    B -->|Yes| D[Resolve all active storage locations in warehouse]
+    D --> E{itemId provided?}
+    E -->|Yes| F[SELECT and SUM from StockLevel where storageLocationId in active locations AND itemId matches, GROUP BY itemId]
+    E -->|No| G[SELECT and SUM from StockLevel where storageLocationId in active locations, GROUP BY itemId]
+    F --> H[Return aggregated records]
+    G --> H
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **WAREHOUSE_NOT_FOUND**: The specified warehouse does not exist
+
+## Test Cases
+
+- returns aggregated quantities per item
+- correctly sums across multiple locations
+- filters by item when provided
+- returns error when warehouse not found
+- excludes inactive storage locations

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

@@ -0,0 +1,49 @@
+# ListCostLayers
+
+## Overview
+
+ListCostLayers lists cost layers for FIFO valuation auditing. It supports filtering by item, valuation policy, or both. Cost layers are returned in creation order (oldest first) to reflect FIFO consumption sequence.
+
+## Business Rules
+
+- Accepts optional filters (at least one required):
+  - `itemId` — filter by specific item
+  - `valuationPolicyId` — filter by specific valuation policy
+- Returns cost layers ordered by creation date ascending (oldest first)
+- Each record includes `quantity`, `unitCost`, `remainingQuantity`, and the referenced `stockMovementId`
+- Returns an empty list if no matching records exist
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive filter criteria] --> B{At least one filter provided?}
+    B -->|No| C[Return error: NO_FILTER_PROVIDED]
+    B -->|Yes| D{Which filters provided?}
+    D -->|itemId| E[SELECT from CostLayer where itemId matches]
+    D -->|valuationPolicyId| F[SELECT from CostLayer where valuationPolicyId matches]
+    D -->|both| G[SELECT from CostLayer where itemId and valuationPolicyId match]
+    E --> H[Order by createdAt ascending]
+    F --> H
+    G --> H
+    H --> I{Records found?}
+    I -->|Yes| J[Return list of CostLayer records]
+    I -->|No| K[Return empty list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **NO_FILTER_PROVIDED**: At least one filter must be specified
+- Returns empty list if no matching records exist
+
+## Test Cases
+
+- lists cost layers by item
+- lists cost layers by valuation policy
+- lists cost layers by both item and valuation policy
+- returns results in oldest-first order
+- returns empty list when no matches

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

@@ -0,0 +1,51 @@
+# ListExpiringLots
+
+## Overview
+
+ListExpiringLots lists lots with expiration dates within a specified threshold. It supports expiration alerting and FEFO (First Expired, First Out) picking decisions. Results are sorted by expiration date ascending so the soonest-expiring lots appear first.
+
+## Business Rules
+
+- Requires `daysUntilExpiry` — the number of days from now to use as the expiration threshold
+- Optionally accepts `itemId` to filter to a specific item
+- Optionally accepts `warehouseId` to filter to lots with stock in a specific warehouse
+- Filters lots where `expirationDate <= now + daysUntilExpiry`
+- Excludes fully consumed lots (lots with zero remaining stock)
+- Returns results sorted by `expirationDate` ascending (soonest first)
+- Returns an empty list if no expiring lots match the criteria
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive daysUntilExpiry and optional filters] --> B[Compute threshold date = now + daysUntilExpiry]
+    B --> C[SELECT from Lot where expirationDate <= threshold]
+    C --> D[Exclude fully consumed lots]
+    D --> E{itemId provided?}
+    E -->|Yes| F[Filter by itemId]
+    E -->|No| G{warehouseId provided?}
+    F --> G
+    G -->|Yes| H[Filter by lots with stock in warehouse]
+    G -->|No| I[Sort by expirationDate ascending]
+    H --> I
+    I --> J{Results found?}
+    J -->|Yes| K[Return list of Lot records]
+    J -->|No| L[Return empty list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- Returns empty list if no expiring lots match the criteria
+
+## Test Cases
+
+- returns lots expiring within threshold
+- sorts by expiration date ascending
+- excludes fully consumed lots
+- filters by item when provided
+- filters by warehouse when provided
+- returns empty list when no expiring lots

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

@@ -0,0 +1,47 @@
+# ListInventoryAdjustments
+
+## Overview
+
+ListInventoryAdjustments lists inventory adjustments filtered by status, storage location, item, or date range. It returns summary-level records ordered by creation date descending.
+
+## Business Rules
+
+- Accepts optional filters:
+  - `adjustmentType` — filter by type (CORRECTION or SCRAP)
+  - `status` — filter by adjustment status (e.g., Draft, PendingApproval, Approved, Rejected, Confirmed)
+  - `storageLocationId` — filter by storage location
+  - `itemId` — filter by item
+  - `dateFrom` — filter adjustments created on or after this date
+  - `dateTo` — filter adjustments created on or before this date
+- Results are ordered by `createdAt` descending (most recent first)
+- Returns an empty list if no matching records exist
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive optional filters] --> B[Build query from provided filters]
+    B --> C[Apply status, storageLocationId, itemId, date range filters as provided]
+    C --> D[Order by createdAt descending]
+    D --> E{Records found?}
+    E -->|Yes| F[Return list of InventoryAdjustment records]
+    E -->|No| G[Return empty list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- Returns empty list if no matching records exist
+
+## Test Cases
+
+- lists adjustments by adjustmentType
+- lists adjustments by status
+- lists adjustments by storage location
+- lists adjustments by item
+- lists adjustments by date range
+- returns empty list when no matches
+- orders by creation date descending

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

@@ -0,0 +1,57 @@
+# ListInventoryCounts
+
+## Overview
+
+ListInventoryCounts lists inventory count documents filtered by status, type, or date range. It returns summary-level records without count lines — use GetInventoryCount for full detail. Results are ordered by planned date descending.
+
+## Business Rules
+
+- Accepts optional filters:
+  - `status` — filter by count status (e.g., draft, in-progress, completed, cancelled)
+  - `countType` — filter by count type (e.g., full, cycle, ad-hoc)
+  - `warehouseId` — filter by warehouse
+  - `dateFrom` — filter counts with planned date on or after this date
+  - `dateTo` — filter counts with planned date on or before this date
+- Returns InventoryCount records **without** nested count lines
+- Results are ordered by `plannedDate` descending (most recent first)
+- Returns an empty list if no matching records exist
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive optional filters] --> B[Build query from provided filters]
+    B --> C{status provided?}
+    C -->|Yes| D[Add status filter]
+    C -->|No| E{countType provided?}
+    D --> E
+    E -->|Yes| F[Add countType filter]
+    E -->|No| G{warehouseId provided?}
+    F --> G
+    G -->|Yes| H[Add warehouseId filter]
+    G -->|No| I{dateFrom or dateTo provided?}
+    H --> I
+    I -->|Yes| J[Add date range filter]
+    I -->|No| K[Order by plannedDate descending]
+    J --> K
+    K --> L{Records found?}
+    L -->|Yes| M[Return list of InventoryCount records]
+    L -->|No| N[Return empty list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- Returns empty list if no matching records exist
+
+## Test Cases
+
+- lists counts by status
+- lists counts by type
+- lists counts by warehouse
+- lists counts by date range
+- returns empty list when no matches
+- orders by planned date descending

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

@@ -0,0 +1,44 @@
+# ListItemValuations
+
+## Overview
+
+ListItemValuations lists valuation summaries for multiple items. It supports inventory value reporting by allowing filters on specific items or valuation policies.
+
+## Business Rules
+
+- Optionally accepts `itemIds` — an array of item UUIDs to filter by
+- Optionally accepts `valuationPolicyId` — filter by a specific valuation policy
+- Returns a list of ItemValuation records, each with computed `costPerUnit` (`totalValue / totalQuantity`)
+- Returns an empty list if no matching records exist
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive optional filters] --> B{itemIds provided?}
+    B -->|Yes| C[SELECT from ItemValuation where itemId in itemIds]
+    B -->|No| D{valuationPolicyId provided?}
+    C --> D
+    D -->|Yes| E[Filter by valuationPolicyId]
+    D -->|No| F[No additional filter]
+    E --> G[Compute costPerUnit for each record]
+    F --> G
+    G --> H{Records found?}
+    H -->|Yes| I[Return list of ItemValuation records]
+    H -->|No| J[Return empty list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- Returns empty list if no matching records exist
+
+## Test Cases
+
+- lists all item valuations
+- filters by item IDs
+- filters by valuation policy
+- returns empty list when no matches

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

@@ -0,0 +1,57 @@
+# ListLots
+
+## Overview
+
+ListLots retrieves a paginated list of lots with optional filtering by itemId, warehouseId, and status. It supports general-purpose lot browsing, operator-driven FEFO picking decisions, and lot selection during goods issue operations. Results are sortable by expirationDate, manufactureDate, or lotNumber.
+
+## Business Rules
+
+- Optionally accepts `itemId` to filter lots belonging to a specific item
+- Optionally accepts `warehouseId` to filter lots that have stock in a specific warehouse (via LotStockLevel)
+- Optionally accepts `status` to filter by lot status (ACTIVE or FULLY_CONSUMED)
+- Supports sorting by `expirationDate`, `manufactureDate`, or `lotNumber`
+- Default sort is `expirationDate` ascending (soonest first) for FEFO support
+- Supports pagination via `limit` and `offset`
+- Returns an empty list if no lots match the criteria
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive optional filters] --> B[SELECT from Lot]
+    B --> C{itemId provided?}
+    C -->|Yes| D[Filter by itemId]
+    C -->|No| E{warehouseId provided?}
+    D --> E
+    E -->|Yes| F[Join LotStockLevel, filter by warehouseId]
+    E -->|No| G{status provided?}
+    F --> G
+    G -->|Yes| H[Filter by status]
+    G -->|No| I[Apply sort order and pagination]
+    H --> I
+    I --> J{Results found?}
+    J -->|Yes| K[Return list of Lot records]
+    J -->|No| L[Return empty list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- Returns empty list if no lots match the criteria
+
+## Test Cases
+
+- returns all lots when no filters provided
+- filters by itemId
+- filters by warehouseId via lot stock levels
+- filters by ACTIVE status
+- filters by FULLY_CONSUMED status
+- combines multiple filters
+- sorts by expiration date ascending by default
+- sorts by manufacture date when specified
+- sorts by lot number when specified
+- returns empty list when no lots match
+- supports pagination with limit and offset

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

@@ -0,0 +1,44 @@
+# ListSerialNumbers
+
+## Overview
+
+ListSerialNumbers lists serial numbers filtered by item, storage location, or status. It supports recall execution, warehouse counting, and serial-tracked inventory browsing. At least one filter must be provided.
+
+## Business Rules
+
+- Accepts optional filters (at least one required):
+  - `itemId` — filter by specific item
+  - `storageLocationId` — filter by specific storage location
+  - `status` — filter by serial number status (AVAILABLE, ISSUED, RETURNED, SCRAPPED)
+- Returns a list of SerialNumber records, each with current status and storage location
+- Returns an empty list if no matching records exist
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive filter criteria] --> B{At least one filter provided?}
+    B -->|No| C[Return error: NO_FILTER_PROVIDED]
+    B -->|Yes| D[Build query with provided filters]
+    D --> E[SELECT from SerialNumber where filters match]
+    E --> F{Records found?}
+    F -->|Yes| G[Return list of SerialNumber records]
+    F -->|No| H[Return empty list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **NO_FILTER_PROVIDED**: At least one filter must be specified
+- Returns empty list if no matching records exist
+
+## Test Cases
+
+- lists serial numbers by item
+- lists serial numbers by storage location
+- lists serial numbers by status
+- combines multiple filters
+- returns empty list when no matches

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

@@ -0,0 +1,49 @@
+# ListStockLevels
+
+## Overview
+
+ListStockLevels lists stock levels filtered by item, storage location, or warehouse. It supports multi-location visibility for transfer planning and stock inquiry. At least one filter must be provided.
+
+## Business Rules
+
+- Accepts optional filters (at least one required):
+  - `itemId` — filter by specific item
+  - `storageLocationId` — filter by specific storage location
+  - `warehouseId` — filter by warehouse, including all storage locations within that warehouse
+- Returns a list of StockLevel records, each with computed `availableQuantity` (`onHand - reserved - blocked`)
+- When filtering by `warehouseId`, includes stock levels from all storage locations belonging to that warehouse
+- Returns an empty list if no matching records exist
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive filter criteria] --> B{Which filters provided?}
+    B -->|itemId| C[SELECT from StockLevel where itemId matches]
+    B -->|storageLocationId| D[SELECT from StockLevel where storageLocationId matches]
+    B -->|warehouseId| E[Resolve all storageLocationIds in warehouse]
+    E --> F[SELECT from StockLevel where storageLocationId in resolved list]
+    C --> G[Compute availableQuantity for each record]
+    D --> G
+    F --> G
+    G --> H{Records found?}
+    H -->|Yes| I[Return list of StockLevel records]
+    H -->|No| J[Return empty list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **NO_FILTER_PROVIDED**: At least one filter must be specified
+- Returns empty list if no matching records exist
+
+## Test Cases
+
+- lists stock levels by item across all locations
+- lists stock levels by storage location
+- lists stock levels by warehouse (aggregates all locations)
+- returns empty list when no matches
+- includes computed available quantity

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

@@ -0,0 +1,47 @@
+# ListStockMovements
+
+## Overview
+
+ListStockMovements lists stock movements filtered by status, movement type, warehouse, or date range. It returns summary-level records without movement lines — use GetStockMovement for full detail. Results are ordered by creation date descending.
+
+## Business Rules
+
+- Accepts optional filters:
+  - `status` — filter by movement status (e.g., Draft, Confirmed, Done, Cancelled)
+  - `movementType` — filter by type (e.g., goods_receipt, goods_issue, internal_transfer, block, unblock)
+  - `warehouseId` — filter by warehouse (movements involving any storage location in the warehouse)
+  - `dateFrom` — filter movements created on or after this date
+  - `dateTo` — filter movements created on or before this date
+- Returns StockMovement records **without** nested movement lines
+- Results are ordered by `createdAt` descending (most recent first)
+- Returns an empty list if no matching records exist
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive optional filters] --> B[Build query from provided filters]
+    B --> C[Apply status, movementType, warehouseId, date range filters as provided]
+    C --> D[Order by createdAt descending]
+    D --> E{Records found?}
+    E -->|Yes| F[Return list of StockMovement records]
+    E -->|No| G[Return empty list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- Returns empty list if no matching records exist
+
+## Test Cases
+
+- lists movements by status
+- lists movements by movement type
+- lists movements by warehouse
+- lists movements by date range
+- returns empty list when no matches
+- orders by creation date descending
+- does not include movement lines

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

@@ -0,0 +1,47 @@
+# ListStorageLocations
+
+## Overview
+
+ListStorageLocations lists storage locations filtered by warehouse, status, or parent location. It supports browsing the warehouse hierarchy (zones and bins). Results are ordered by name ascending.
+
+## Business Rules
+
+- Accepts optional filters (at least one required):
+  - `warehouseId` — filter by warehouse
+  - `status` — filter by location status (e.g., Active, Inactive)
+  - `parentId` — filter by parent zone (null returns top-level zones only)
+- Returns StorageLocation records **without** nested stock levels
+- Results are ordered by `name` ascending
+- Returns an empty list if no matching records exist
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive filter criteria] --> B{At least one filter provided?}
+    B -->|No| C[Return error: NO_FILTER_PROVIDED]
+    B -->|Yes| D[Build query from provided filters]
+    D --> E[Apply warehouseId, status, parentId filters as provided]
+    E --> F[Order by name ascending]
+    F --> G{Records found?}
+    G -->|Yes| H[Return list of StorageLocation records]
+    G -->|No| I[Return empty list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **NO_FILTER_PROVIDED**: At least one filter must be specified
+- Returns empty list if no matching records exist
+
+## Test Cases
+
+- lists storage locations by warehouse
+- lists storage locations by status
+- lists top-level zones when parentId is null
+- lists bins under a specific zone
+- returns empty list when no matches
+- orders by name ascending

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

@@ -0,0 +1,38 @@
+# ListValuationPolicies
+
+## Overview
+
+ListValuationPolicies lists all valuation policies, optionally filtered by costing method. It supports policy browsing for configuration management and item assignment.
+
+## Business Rules
+
+- Optionally accepts `costingMethod` — filter by FIFO, AVCO, or STANDARD_COST
+- Returns a list of ValuationPolicy records
+- Returns an empty list if no matching records exist
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive optional costingMethod filter] --> B{costingMethod provided?}
+    B -->|Yes| C[SELECT from ValuationPolicy where costingMethod matches]
+    B -->|No| D[SELECT all from ValuationPolicy]
+    C --> E{Records found?}
+    D --> E
+    E -->|Yes| F[Return list of ValuationPolicy records]
+    E -->|No| G[Return empty list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- Returns empty list if no matching records exist
+
+## Test Cases
+
+- lists all valuation policies
+- filters by costing method
+- returns empty list when no matches