@tailor-platform/erp-kit 0.4.1 → 0.5.0

package/src/modules/inventory/docs/commands/CancelInventoryCount.md

@@ -0,0 +1,49 @@
+# CancelInventoryCount
+
+## Overview
+
+cancelInventoryCount cancels an inventory count session that is in PLANNED or IN_PROGRESS status. Completed counts cannot be cancelled. Cancellation unfreezes any frozen stock movements for the counted locations and discards all count line data.
+
+## Business Rules
+
+- Inventory count must exist
+- Inventory count must be in PLANNED or IN_PROGRESS status (not COMPLETED or already CANCELLED)
+- Cancellation unfreezes stock movements if the count had frozen them
+- All count line data is discarded upon cancellation
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive cancel request] --> B{Count exists?}
+    B -->|No| C[Return error: COUNT_NOT_FOUND]
+    B -->|Yes| D{Status is COMPLETED?}
+    D -->|Yes| E[Return error: COUNT_ALREADY_COMPLETED]
+    D -->|No| F{Status is CANCELLED?}
+    F -->|Yes| G[Return error: COUNT_ALREADY_CANCELLED]
+    F -->|No| H{Count had frozen stock?}
+    H -->|Yes| I[Unfreeze stock movements for counted locations]
+    I --> J[Update status to CANCELLED]
+    H -->|No| J
+    J --> K[Return cancelled count]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COUNT_NOT_FOUND**: Referenced inventory count does not exist
+- **COUNT_ALREADY_COMPLETED**: Inventory count has already been completed and cannot be cancelled
+- **COUNT_ALREADY_CANCELLED**: Inventory count has already been cancelled
+
+## Test Cases
+
+- returns error when not found
+- returns error when COMPLETED
+- returns error when already cancelled
+- cancels PLANNED count
+- cancels IN_PROGRESS count
+- unfreezes stock movements when count had frozen them
+- discards count line data

package/src/modules/inventory/docs/commands/CancelStockMovement.md

@@ -0,0 +1,44 @@
+# CancelStockMovement
+
+## Overview
+
+cancelStockMovement cancels a stock movement that is in DRAFT or CONFIRMED status. Movements that have already been executed (DONE) cannot be cancelled. Cancellation does not affect any stock levels since stock is only modified during execution.
+
+## Business Rules
+
+- Stock movement must exist
+- Stock movement must be in DRAFT or CONFIRMED status (not DONE or already CANCELLED)
+- Cancellation does not affect stock levels
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive cancel request] --> B{Movement exists?}
+    B -->|No| C[Return error: STOCK_MOVEMENT_NOT_FOUND]
+    B -->|Yes| D{Status is DONE?}
+    D -->|Yes| E[Return error: STOCK_MOVEMENT_ALREADY_DONE]
+    D -->|No| F{Status is CANCELLED?}
+    F -->|Yes| G[Return error: STOCK_MOVEMENT_ALREADY_CANCELLED]
+    F -->|No| H[Update status to CANCELLED]
+    H --> I[Return cancelled movement]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **STOCK_MOVEMENT_NOT_FOUND**: Referenced stock movement does not exist
+- **STOCK_MOVEMENT_ALREADY_DONE**: Stock movement has already been executed and cannot be cancelled
+- **STOCK_MOVEMENT_ALREADY_CANCELLED**: Stock movement has already been cancelled
+
+## Test Cases
+
+- returns error when not found
+- returns error when DONE
+- returns error when already cancelled
+- cancels DRAFT movement
+- cancels CONFIRMED movement
+- does not affect stock levels

package/src/modules/inventory/docs/commands/CompleteInventoryCount.md

@@ -0,0 +1,47 @@
+# CompleteInventoryCount
+
+## Overview
+
+completeInventoryCount completes the inventory count process, transitioning it from IN_PROGRESS to COMPLETED status. All count lines must be in a terminal status (APPROVED or REJECTED) before the count can be completed. If stock was frozen during the count, it is unfrozen upon completion.
+
+## Business Rules
+
+- Count must be in IN_PROGRESS status
+- All count lines must be in terminal status (APPROVED or REJECTED)
+- Unfreezes stock movements if they were frozen during the count
+- Count becomes immutable after completion
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive complete request] --> B{Count exists?}
+    B -->|No| C[Return error: COUNT_NOT_FOUND]
+    B -->|Yes| D{Status is IN_PROGRESS?}
+    D -->|No| E[Return error: COUNT_NOT_IN_PROGRESS]
+    D -->|Yes| F{All lines resolved?}
+    F -->|No| G[Return error: UNRESOLVED_COUNT_LINES]
+    F -->|Yes| H{Stock was frozen?}
+    H -->|Yes| I[Unfreeze stock movements]
+    I --> J[Update status to COMPLETED]
+    H -->|No| J
+    J --> K[Return completed count]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COUNT_NOT_FOUND**: Referenced count does not exist
+- **COUNT_NOT_IN_PROGRESS**: Count is not in IN_PROGRESS status
+- **UNRESOLVED_COUNT_LINES**: One or more count lines are not in a terminal status (APPROVED or REJECTED)
+
+## Test Cases
+
+- returns error when not found
+- returns error when not in progress
+- returns error when unresolved lines exist
+- completes count
+- unfreezes stock after completion

package/src/modules/inventory/docs/commands/ConfirmInventoryAdjustment.md

@@ -0,0 +1,72 @@
+# ConfirmInventoryAdjustment
+
+## Overview
+
+confirmInventoryAdjustment confirms an inventory adjustment, generating a stock movement and updating on-hand quantities and valuation. This command can be called from either DRAFT (bypassing the approval workflow) or APPROVED status. Once confirmed, the adjustment is immutable. The behavior varies by adjustmentType:
+
+- **CORRECTION**: Generates a stock movement to/from a virtual adjustment location.
+- **SCRAP**: Generates a stock movement to a virtual scrap location. Updates lot stock levels if a lot is specified. Transitions serial number to SCRAPPED state if a serial number is specified.
+
+## Business Rules
+
+- Adjustment must exist and be in DRAFT or APPROVED status
+- For negative adjustments: on-hand quantity must be sufficient (unless the organization permits negative stock)
+- CORRECTION: generates a stock movement to/from virtual adjustment location
+- SCRAP: generates a stock movement to virtual scrap location
+- SCRAP with lot: updates lot stock levels
+- SCRAP with serial number: transitions serial to SCRAPPED state
+- Updates on-hand quantity on the StockLevel record
+- Updates inventory valuation
+- Adjustment becomes immutable after confirmation
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive confirm request] --> B{Adjustment exists?}
+    B -->|No| C[Return error: ADJUSTMENT_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT or APPROVED?}
+    D -->|No| E[Return error: ADJUSTMENT_INVALID_STATUS]
+    D -->|Yes| F{Sufficient on-hand stock?}
+    F -->|No| H[Return error: INSUFFICIENT_ON_HAND]
+    F -->|Yes| I{adjustmentType?}
+    I -->|CORRECTION| J[Generate stock movement to/from virtual adjustment location]
+    I -->|SCRAP| K[Generate stock movement to virtual scrap location]
+    K --> K1{Lot specified?}
+    K1 -->|Yes| K2[Update lot stock levels]
+    K2 --> K3{Serial specified?}
+    K1 -->|No| K3
+    K3 -->|Yes| K4[Transition serial to SCRAPPED]
+    K3 -->|No| L
+    K4 --> L
+    J --> L[Update on-hand quantity]
+    L --> M[Update inventory valuation]
+    M --> N[Update status to CONFIRMED]
+    N --> O[Return confirmed adjustment]
+```
+
+## External Dependencies
+
+- None (internal models: [StockMovement](../models/StockMovement.md), [StockLevel](../models/StockLevel.md), [LotStockLevel](../models/LotStockLevel.md), [SerialNumber](../models/SerialNumber.md), [ItemValuation](../models/ItemValuation.md))
+
+## Error Scenarios
+
+- **ADJUSTMENT_NOT_FOUND**: Referenced adjustment does not exist
+- **ADJUSTMENT_INVALID_STATUS**: Adjustment is not in DRAFT or APPROVED status
+- **INSUFFICIENT_ON_HAND**: Negative adjustment would reduce on-hand below zero
+
+## Test Cases
+
+- returns error when not found
+- returns error when already confirmed
+- returns error when negative adjustment exceeds on-hand
+- confirms CORRECTION from DRAFT (no approval)
+- confirms CORRECTION from APPROVED
+- confirms SCRAP from DRAFT
+- confirms SCRAP from APPROVED
+- CORRECTION generates stock movement to virtual adjustment location
+- SCRAP generates stock movement to virtual scrap location
+- SCRAP updates lot stock when applicable
+- SCRAP transitions serial to SCRAPPED when applicable
+- updates on-hand quantity
+- updates inventory valuation

package/src/modules/inventory/docs/commands/ConfirmStockMovement.md

@@ -0,0 +1,43 @@
+# ConfirmStockMovement
+
+## Overview
+
+confirmStockMovement transitions a stock movement from DRAFT to CONFIRMED status. All move lines are revalidated before confirmation to ensure data integrity. A confirmed movement is ready for execution.
+
+## Business Rules
+
+- Stock movement must exist
+- Stock movement must be in DRAFT status
+- All move lines must pass validation (items active, locations valid, quantities valid)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive confirm request] --> B{Movement exists?}
+    B -->|No| C[Return error: STOCK_MOVEMENT_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return error: STOCK_MOVEMENT_NOT_DRAFT]
+    D -->|Yes| F{All lines valid?}
+    F -->|No| G[Return validation error]
+    F -->|Yes| H[Update status to CONFIRMED]
+    H --> I[Return confirmed movement]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **STOCK_MOVEMENT_NOT_FOUND**: Referenced stock movement does not exist
+- **STOCK_MOVEMENT_NOT_DRAFT**: Stock movement is not in DRAFT status
+
+## Test Cases
+
+- returns error when not found
+- returns error when not DRAFT
+- returns error when no move lines
+- returns error when item not active
+- returns error when destination location not found
+- confirms valid movement

package/src/modules/inventory/docs/commands/CreateInventoryAdjustment.md

@@ -0,0 +1,75 @@
+# CreateInventoryAdjustment
+
+## Overview
+
+createInventoryAdjustment creates a new inventory adjustment record in DRAFT status. The `adjustmentType` determines the behavior:
+
+- **CORRECTION** (default): Manual corrections to on-hand quantities. quantityDelta can be positive or negative.
+- **SCRAP**: Controlled disposal of unusable stock. quantityDelta must be negative.
+
+## Business Rules
+
+- adjustmentType is required (CORRECTION or SCRAP, defaults to CORRECTION)
+- itemId is required and must reference an existing item
+- storageLocationId is required and must reference an existing storage location
+- quantityDelta is required
+- For CORRECTION: quantityDelta can be positive or negative
+- For SCRAP: quantityDelta must be negative
+- reasonCode is required
+- inventoryCountId is optional (links adjustment to a specific count, CORRECTION only)
+- lotId is optional (must reference an existing lot if provided)
+- serialNumberId is optional (must reference an existing serial number if provided)
+- Adjustment is created in DRAFT status
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Item exists?}
+    B -->|No| C[Return error: ITEM_NOT_FOUND]
+    B -->|Yes| D{Location exists?}
+    D -->|No| E[Return error: STORAGE_LOCATION_NOT_FOUND]
+    D -->|Yes| F{reasonCode provided?}
+    F -->|No| G[Return error: REASON_CODE_REQUIRED]
+    F -->|Yes| FA{adjustmentType is SCRAP?}
+    FA -->|Yes| FB{quantityDelta negative?}
+    FB -->|No| FC[Return error: SCRAP_QUANTITY_MUST_BE_NEGATIVE]
+    FB -->|Yes| H
+    FA -->|No| H{lotId provided?}
+    H -->|Yes| I{Lot exists?}
+    I -->|No| J[Return error: LOT_NOT_FOUND]
+    I -->|Yes| K{serialNumberId provided?}
+    H -->|No| K
+    K -->|Yes| L{Serial number exists?}
+    L -->|No| M[Return error: SERIAL_NUMBER_NOT_FOUND]
+    L -->|Yes| N[Create adjustment in DRAFT]
+    K -->|No| N
+    N --> O[Return created adjustment]
+```
+
+## External Dependencies
+
+- [item-management::Item](../../../item-management/docs/models/Item.md) - Validates that the referenced item exists
+
+## Error Scenarios
+
+- **ITEM_NOT_FOUND**: Referenced item does not exist
+- **STORAGE_LOCATION_NOT_FOUND**: Referenced storage location does not exist
+- **REASON_CODE_REQUIRED**: No reason code was provided
+- **SCRAP_QUANTITY_MUST_BE_NEGATIVE**: SCRAP type adjustment must have a negative quantityDelta
+- **LOT_NOT_FOUND**: Referenced lot does not exist
+- **SERIAL_NUMBER_NOT_FOUND**: Referenced serial number does not exist
+
+## Test Cases
+
+- returns error when item not found
+- returns error when location not found
+- returns error when reason code missing
+- returns error when SCRAP type with positive quantityDelta
+- returns error when lot not found
+- returns error when serial number not found
+- creates CORRECTION adjustment with positive quantityDelta
+- creates CORRECTION adjustment with negative quantityDelta
+- creates SCRAP adjustment with negative quantityDelta
+- creates adjustment linked to inventory count
+- defaults adjustmentType to CORRECTION when not specified

package/src/modules/inventory/docs/commands/CreateInventoryCount.md

@@ -0,0 +1,49 @@
+# CreateInventoryCount
+
+## Overview
+
+createInventoryCount creates a new inventory count document in PLANNED status. Inventory counts are used to verify physical stock against system records. Counts can be full (entire warehouse) or cycle (specific storage locations).
+
+## Business Rules
+
+- countType is required and must be one of: FULL, CYCLE
+- Location scope is required — either warehouseId or storageLocationId must be specified
+- plannedDate is required
+- Count is created in PLANNED status
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Valid countType?}
+    B -->|No| C[Return error: INVALID_COUNT_TYPE]
+    B -->|Yes| D{warehouseId provided?}
+    D -->|Yes| E{Warehouse exists?}
+    E -->|No| F[Return error: WAREHOUSE_NOT_FOUND]
+    E -->|Yes| G[Create count in PLANNED status]
+    D -->|No| H{storageLocationId provided?}
+    H -->|Yes| I{Location exists?}
+    I -->|No| J[Return error: STORAGE_LOCATION_NOT_FOUND]
+    I -->|Yes| G
+    H -->|No| K[Return error: location scope required]
+    G --> L[Return created count]
+```
+
+## External Dependencies
+
+- None (internal models: [Warehouse](../models/Warehouse.md), [StorageLocation](../models/StorageLocation.md))
+
+## Error Scenarios
+
+- **WAREHOUSE_NOT_FOUND**: Referenced warehouse does not exist
+- **STORAGE_LOCATION_NOT_FOUND**: Referenced storage location does not exist
+- **INVALID_COUNT_TYPE**: countType is not FULL or CYCLE
+
+## Test Cases
+
+- returns error when warehouse not found
+- returns error when invalid count type
+- returns error when no location scope provided
+- returns error when storage location not found
+- creates full count
+- creates cycle count for specific location

package/src/modules/inventory/docs/commands/CreateLot.md

@@ -0,0 +1,40 @@
+# CreateLot
+
+## Overview
+
+createLot creates a new lot/batch record for a lot-tracked item. Lots enable tracking of groups of items that share common characteristics such as manufacturing date, expiration date, and supplier lot references. Each lot is uniquely identified by its lot number within a specific item.
+
+## Business Rules
+
+- lotNumber is required and must be unique per item
+- itemId is required and must reference an existing item
+- manufactureDate and expirationDate are optional
+- supplierLotReference is optional
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Item exists?}
+    B -->|No| C[Return error: ITEM_NOT_FOUND]
+    B -->|Yes| D{lotNumber unique for item?}
+    D -->|No| E[Return error: DUPLICATE_LOT_NUMBER]
+    D -->|Yes| F[Create lot record]
+    F --> G[Return created lot]
+```
+
+## External Dependencies
+
+- [item-management::Item](../../../item-management/docs/models/Item.md) - Validates that the referenced item exists
+
+## Error Scenarios
+
+- **ITEM_NOT_FOUND**: Referenced item does not exist
+- **DUPLICATE_LOT_NUMBER**: A lot with the same number already exists for this item
+
+## Test Cases
+
+- returns error when item not found
+- returns error when lot number already exists for item
+- creates lot with all attributes
+- creates lot with minimal attributes

package/src/modules/inventory/docs/commands/CreateStockMovement.md

@@ -0,0 +1,76 @@
+# CreateStockMovement
+
+## Overview
+
+createStockMovement creates a new stock movement in DRAFT status with one or more move lines. Stock movements track the physical flow of goods through the warehouse system and support multiple movement types: goods receipt, goods issue, internal transfer, block, and unblock.
+
+## Business Rules
+
+- movementType is required and must be one of: GOODS_RECEIPT, GOODS_ISSUE, INTERNAL_TRANSFER, BLOCK, UNBLOCK
+- At least one move line is required
+- Each move line: quantity must be greater than zero
+- Each move line: source location must not equal destination location
+- Each move line: referenced item must be in ACTIVE status
+- BLOCK and UNBLOCK movement types require a reasonCode
+- For lot-tracked items, each move line must specify a lotId
+- Movement is created in DRAFT status
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Valid movementType?}
+    B -->|No| C[Return error: INVALID_MOVEMENT_TYPE]
+    B -->|Yes| D{Move lines provided?}
+    D -->|No| E[Return error: EMPTY_MOVE_LINES]
+    D -->|Yes| F{Validate each line}
+    F --> G{Item exists and ACTIVE?}
+    G -->|No - not found| H[Return error: ITEM_NOT_FOUND]
+    G -->|No - inactive| I[Return error: ITEM_NOT_ACTIVE]
+    G -->|Yes| J{Quantity > 0?}
+    J -->|No| K[Return error: INVALID_QUANTITY]
+    J -->|Yes| L{Source ≠ destination?}
+    L -->|No| M[Return error: SAME_SOURCE_DESTINATION]
+    L -->|Yes| N{Location exists?}
+    N -->|No| O[Return error: STORAGE_LOCATION_NOT_FOUND]
+    N -->|Yes| P{Lot-tracked item?}
+    P -->|Yes| Q{lotId provided?}
+    Q -->|No| R[Return error: LOT_REQUIRED_FOR_TRACKED_ITEM]
+    Q -->|Yes| S{Block/unblock type?}
+    P -->|No| S
+    S -->|Yes| T{reasonCode provided?}
+    T -->|No| U[Return error: REASON_CODE_REQUIRED]
+    T -->|Yes| V[Create movement + lines in DRAFT]
+    S -->|No| V
+    V --> W[Return created movement]
+```
+
+## External Dependencies
+
+- [item-management::Item](../../../item-management/docs/models/Item.md) - Validates that each referenced item exists, is in ACTIVE status, and checks whether the item is lot-tracked
+
+## Error Scenarios
+
+- **INVALID_MOVEMENT_TYPE**: movementType is not a recognized value
+- **EMPTY_MOVE_LINES**: No move lines were provided
+- **ITEM_NOT_FOUND**: Referenced item does not exist
+- **ITEM_NOT_ACTIVE**: Referenced item is not in ACTIVE status
+- **INVALID_QUANTITY**: Move line quantity is zero or negative
+- **SAME_SOURCE_DESTINATION**: Source and destination locations are the same
+- **STORAGE_LOCATION_NOT_FOUND**: Referenced storage location does not exist
+- **REASON_CODE_REQUIRED**: Block or unblock movement type requires a reason code
+- **LOT_REQUIRED_FOR_TRACKED_ITEM**: Move line references a lot-tracked item but no lotId was provided
+
+## Test Cases
+
+- returns error when no move lines
+- returns error when invalid movement type
+- returns error when item not found
+- returns error when item not active
+- returns error when quantity is zero or negative
+- returns error when source equals destination
+- returns error when storage location not found
+- returns error when block without reason code
+- creates movement in DRAFT status
+- returns error when lot-tracked item has no lotId
+- creates movement with multiple lines

package/src/modules/inventory/docs/commands/CreateStorageLocation.md

@@ -0,0 +1,66 @@
+# CreateStorageLocation
+
+## Overview
+
+createStorageLocation establishes a new storage location (zone or bin) within a warehouse. Zones are top-level divisions within a warehouse, while bins are subdivisions within a zone. This hierarchy enables granular stock tracking and placement.
+
+## Business Rules
+
+- warehouseId is required and must reference an existing ACTIVE warehouse
+- locationType is required and must be either 'zone' or 'bin'
+- For zones: parentId must be null
+- For bins: parentId is required and must reference a zone in the same warehouse
+- Name and code must be unique within the warehouse
+- storageCondition and capacity are optional
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Warehouse exists?}
+    B -->|No| C[Return error: WAREHOUSE_NOT_FOUND]
+    B -->|Yes| D{Warehouse ACTIVE?}
+    D -->|No| E[Return error: WAREHOUSE_INACTIVE]
+    D -->|Yes| F{Valid locationType?}
+    F -->|No| G[Return error: INVALID_LOCATION_TYPE]
+    F -->|Yes| H{locationType is bin?}
+    H -->|Yes| I{parentId provided?}
+    I -->|No| J[Return error: PARENT_ZONE_NOT_FOUND]
+    I -->|Yes| K{Parent exists and is a zone?}
+    K -->|No - not zone| L[Return error: PARENT_NOT_A_ZONE]
+    K -->|No - not found| J
+    K -->|Yes| M{Parent in same warehouse?}
+    M -->|No| N[Return error: PARENT_IN_DIFFERENT_WAREHOUSE]
+    M -->|Yes| O{Name/code unique in warehouse?}
+    H -->|No| O
+    O -->|No| P[Return error: DUPLICATE_LOCATION_NAME]
+    O -->|Yes| Q[Create storage location]
+    Q --> R[Return created location]
+```
+
+## External Dependencies
+
+- None (internal warehouse reference via [Warehouse](../models/Warehouse.md))
+
+## Error Scenarios
+
+- **WAREHOUSE_NOT_FOUND**: Referenced warehouse does not exist
+- **WAREHOUSE_INACTIVE**: Referenced warehouse is not in ACTIVE status
+- **INVALID_LOCATION_TYPE**: locationType is not 'zone' or 'bin'
+- **PARENT_ZONE_NOT_FOUND**: Bin's parent zone does not exist
+- **PARENT_NOT_A_ZONE**: Parent location is a bin, not a zone
+- **PARENT_IN_DIFFERENT_WAREHOUSE**: Parent zone belongs to a different warehouse
+- **DUPLICATE_LOCATION_NAME**: A location with the same name or code already exists in the warehouse
+
+## Test Cases
+
+- returns error when warehouse not found
+- returns error when warehouse inactive
+- returns error when invalid location type
+- returns error when bin has no parent
+- returns error when bin parent is another bin
+- returns error when parent zone is in different warehouse
+- returns error when location name already exists
+- creates zone with null parentId
+- creates bin with parent zone
+- creates location with storage condition

package/src/modules/inventory/docs/commands/CreateValuationPolicy.md

@@ -0,0 +1,45 @@
+# CreateValuationPolicy
+
+## Overview
+
+createValuationPolicy creates a new valuation policy that defines the costing method used to calculate inventory value. Supported costing methods are FIFO (First In, First Out), AVCO (Average Cost), and STANDARD_COST (fixed standard cost rate).
+
+## Business Rules
+
+- Name is required
+- costingMethod is required and must be one of: FIFO, AVCO, STANDARD_COST
+- standardCostRate is required when costingMethod is STANDARD_COST
+- standardCostRate is not required for FIFO or AVCO methods
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Name provided?}
+    B -->|No| C[Return error: name required]
+    B -->|Yes| D{Valid costingMethod?}
+    D -->|No| E[Return error: INVALID_COSTING_METHOD]
+    D -->|Yes| F{costingMethod is STANDARD_COST?}
+    F -->|Yes| G{standardCostRate provided?}
+    G -->|No| H[Return error: STANDARD_COST_RATE_REQUIRED]
+    G -->|Yes| I[Create valuation policy]
+    F -->|No| I
+    I --> J[Return created policy]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INVALID_COSTING_METHOD**: costingMethod is not a recognized value (must be FIFO, AVCO, or STANDARD_COST)
+- **STANDARD_COST_RATE_REQUIRED**: costingMethod is STANDARD_COST but no standardCostRate was provided
+
+## Test Cases
+
+- returns error when invalid costing method
+- returns error when standard cost without rate
+- creates FIFO policy
+- creates AVCO policy
+- creates standard cost policy with rate

package/src/modules/inventory/docs/commands/CreateWarehouse.md

@@ -0,0 +1,47 @@
+# CreateWarehouse
+
+## Overview
+
+createWarehouse establishes a new warehouse linked to an organizational site. The warehouse is created in ACTIVE status and is immediately available for storage location creation and stock operations. Each warehouse must have a unique name within its associated site.
+
+## Business Rules
+
+- Name is required and must be unique within the same site
+- siteId is required and must reference an existing ACTIVE site
+- storageCondition is optional
+- capacity is optional
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Validate name provided?}
+    B -->|No| C[Return error: name required]
+    B -->|Yes| D{Site exists?}
+    D -->|No| E[Return error: SITE_NOT_FOUND]
+    D -->|Yes| F{Site ACTIVE?}
+    F -->|No| G[Return error: SITE_INACTIVE]
+    F -->|Yes| H{Name unique within site?}
+    H -->|No| I[Return error: DUPLICATE_WAREHOUSE_NAME]
+    H -->|Yes| J[Create warehouse with ACTIVE status]
+    J --> K[Return created warehouse]
+```
+
+## External Dependencies
+
+- [organization::Site](../../../organization/docs/models/Site.md) - Validates that the referenced site exists and is active
+
+## Error Scenarios
+
+- **SITE_NOT_FOUND**: Referenced site does not exist
+- **SITE_INACTIVE**: Referenced site exists but is not in ACTIVE status
+- **DUPLICATE_WAREHOUSE_NAME**: A warehouse with the same name already exists at the given site
+
+## Test Cases
+
+- returns error when site not found
+- returns error when site is inactive
+- returns error when warehouse name already exists at site
+- creates warehouse with ACTIVE status
+- creates warehouse with optional storage condition
+- creates warehouse with optional capacity