@tailor-platform/erp-kit 0.4.1 → 0.5.0

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

@@ -0,0 +1,39 @@
+# DeactivateStorageLocation
+
+## Overview
+
+deactivateStorageLocation transitions a storage location from ACTIVE to INACTIVE status. Deactivation does NOT cascade to child bins — each location must be deactivated individually.
+
+## Business Rules
+
+- Storage location must exist
+- Storage location must be in ACTIVE status
+- Deactivation does not automatically deactivate child bins
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate request] --> B{Location exists?}
+    B -->|No| C[Return error: STORAGE_LOCATION_NOT_FOUND]
+    B -->|Yes| D{Status is ACTIVE?}
+    D -->|No| E[Return error: STORAGE_LOCATION_NOT_ACTIVE]
+    D -->|Yes| F[Update status to INACTIVE]
+    F --> G[Return updated location]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **STORAGE_LOCATION_NOT_FOUND**: Referenced storage location does not exist
+- **STORAGE_LOCATION_NOT_ACTIVE**: Storage location is not in ACTIVE status
+
+## Test Cases
+
+- returns error when not found
+- returns error when already inactive
+- deactivates location
+- does not cascade to child bins

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

@@ -0,0 +1,38 @@
+# DeactivateWarehouse
+
+## Overview
+
+deactivateWarehouse transitions a warehouse from ACTIVE to INACTIVE status. Once deactivated, the warehouse no longer accepts new stock movements, but all historical records are preserved for auditing and reporting purposes.
+
+## Business Rules
+
+- Warehouse must exist
+- Warehouse must be in ACTIVE status
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate request] --> B{Warehouse exists?}
+    B -->|No| C[Return error: WAREHOUSE_NOT_FOUND]
+    B -->|Yes| D{Status is ACTIVE?}
+    D -->|No| E[Return error: WAREHOUSE_NOT_ACTIVE]
+    D -->|Yes| F[Update status to INACTIVE]
+    F --> G[Return updated warehouse]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **WAREHOUSE_NOT_FOUND**: Referenced warehouse does not exist
+- **WAREHOUSE_NOT_ACTIVE**: Warehouse is not in ACTIVE status
+
+## Test Cases
+
+- returns error when warehouse not found
+- returns error when warehouse already inactive
+- deactivates active warehouse
+- historical records preserved after deactivation

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

@@ -0,0 +1,82 @@
+# ExecuteStockMovement
+
+## Overview
+
+executeStockMovement transitions a stock movement from CONFIRMED to DONE status. This is the critical command that actually updates stock levels in the system. It processes each move line, adjusting on-hand, incoming, blocked, and reserved quantities as appropriate for the movement type. It also updates lot stock levels and serial number states when applicable, and triggers inventory valuation recalculation.
+
+## Business Rules
+
+- Stock movement must exist and be in CONFIRMED status
+- For GOODS_ISSUE: source location must have sufficient available stock
+- For BLOCK: must have sufficient available stock to block
+- For UNBLOCK: must have sufficient blocked stock to unblock
+- Updates StockLevel quantities based on movement type
+- Updates LotStockLevel if a lot is specified on the move line
+- Transitions SerialNumber state based on movement type and current serial state:
+  - GOODS_RECEIPT (initial receipt): serial is assigned as AVAILABLE via AssignSerialNumber, not by this command
+  - GOODS_ISSUE: AVAILABLE → ISSUED
+  - GOODS_RECEIPT (customer return): ISSUED → RETURNED
+  - GOODS_RECEIPT (restock after return): RETURNED → AVAILABLE
+- SCRAP serial transitions (AVAILABLE → SCRAPPED, RETURNED → SCRAPPED) are handled by ConfirmInventoryAdjustment, not by this command
+- An ISSUED serial cannot transition directly to AVAILABLE; it must pass through RETURNED first
+- Triggers valuation recalculation after execution
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive execute request] --> B{Movement exists?}
+    B -->|No| C[Return error: STOCK_MOVEMENT_NOT_FOUND]
+    B -->|Yes| D{Status is CONFIRMED?}
+    D -->|No| E[Return error: STOCK_MOVEMENT_NOT_CONFIRMED]
+    D -->|Yes| F[Process each move line]
+    F --> G{Sufficient stock?}
+    G -->|No - available| H[Return error: INSUFFICIENT_STOCK]
+    G -->|No - blocked| I[Return error: INSUFFICIENT_BLOCKED_STOCK]
+    G -->|No - lot| J[Return error: LOT_STOCK_INSUFFICIENT]
+    G -->|Yes| K[Update stock levels]
+    K --> L{Lot specified?}
+    L -->|Yes| M[Update lot stock levels]
+    L -->|No| N{Serial specified?}
+    M --> N
+    N -->|Yes| O{Valid serial state?}
+    O -->|No| P[Return error: SERIAL_INVALID_STATE]
+    O -->|Yes| Q[Transition serial number state]
+    N -->|No| R[Trigger valuation recalculation]
+    Q --> R
+    R --> S[Update status to DONE]
+    S --> T[Return executed movement]
+```
+
+## External Dependencies
+
+- None (all internal inventory models: [StockLevel](../models/StockLevel.md), [LotStockLevel](../models/LotStockLevel.md), [SerialNumber](../models/SerialNumber.md), [ItemValuation](../models/ItemValuation.md))
+
+## Error Scenarios
+
+- **STOCK_MOVEMENT_NOT_FOUND**: Referenced stock movement does not exist
+- **STOCK_MOVEMENT_NOT_CONFIRMED**: Stock movement is not in CONFIRMED status
+- **INSUFFICIENT_STOCK**: Source location does not have enough available stock for goods issue or block
+- **INSUFFICIENT_BLOCKED_STOCK**: Source location does not have enough blocked stock for unblock
+- **LOT_STOCK_INSUFFICIENT**: Lot does not have sufficient stock at the location
+- **SERIAL_INVALID_STATE**: Serial number is not in a valid state for the movement type
+
+## Test Cases
+
+- returns error when not found
+- returns error when not CONFIRMED
+- returns error when insufficient available stock for goods issue
+- returns error when insufficient stock for block
+- returns error when insufficient blocked stock for unblock
+- returns error when lot stock insufficient for goods issue
+- executes goods receipt (increases on-hand, decreases incoming)
+- executes goods issue (decreases on-hand)
+- executes internal transfer (decreases source, increases destination)
+- executes block (increases blocked)
+- executes unblock (decreases blocked)
+- updates lot stock levels when lot specified
+- transitions serial from AVAILABLE to ISSUED on goods issue
+- transitions serial from ISSUED to RETURNED on goods receipt (customer return)
+- transitions serial from RETURNED to AVAILABLE on goods receipt (restock after return)
+- returns error when serial state is invalid for the movement type
+- triggers valuation recalculation

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

@@ -0,0 +1,42 @@
+# ReactivateStorageLocation
+
+## Overview
+
+reactivateStorageLocation transitions a storage location from INACTIVE back to ACTIVE status. The parent warehouse must still be in ACTIVE status for the location to be reactivated.
+
+## Business Rules
+
+- Storage location must exist
+- Storage location must be in INACTIVE status
+- Parent warehouse must be in ACTIVE status
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive reactivate request] --> B{Location exists?}
+    B -->|No| C[Return error: STORAGE_LOCATION_NOT_FOUND]
+    B -->|Yes| D{Status is INACTIVE?}
+    D -->|No| E[Return error: STORAGE_LOCATION_NOT_INACTIVE]
+    D -->|Yes| F{Warehouse ACTIVE?}
+    F -->|No| G[Return error: WAREHOUSE_INACTIVE]
+    F -->|Yes| H[Update status to ACTIVE]
+    H --> I[Return updated location]
+```
+
+## External Dependencies
+
+- None (internal warehouse reference via [Warehouse](../models/Warehouse.md))
+
+## Error Scenarios
+
+- **STORAGE_LOCATION_NOT_FOUND**: Referenced storage location does not exist
+- **STORAGE_LOCATION_NOT_INACTIVE**: Storage location is not in INACTIVE status
+- **WAREHOUSE_INACTIVE**: Parent warehouse is not in ACTIVE status
+
+## Test Cases
+
+- returns error when not found
+- returns error when already active
+- returns error when warehouse is inactive
+- reactivates inactive location

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

@@ -0,0 +1,42 @@
+# ReactivateWarehouse
+
+## Overview
+
+reactivateWarehouse transitions a warehouse from INACTIVE back to ACTIVE status, allowing it to resume accepting stock movements and other inventory operations. The referenced site must still be active.
+
+## Business Rules
+
+- Warehouse must exist
+- Warehouse must be in INACTIVE status
+- Referenced site must still be in ACTIVE status
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive reactivate request] --> B{Warehouse exists?}
+    B -->|No| C[Return error: WAREHOUSE_NOT_FOUND]
+    B -->|Yes| D{Status is INACTIVE?}
+    D -->|No| E[Return error: WAREHOUSE_NOT_INACTIVE]
+    D -->|Yes| F{Site still ACTIVE?}
+    F -->|No| G[Return error: SITE_INACTIVE]
+    F -->|Yes| H[Update status to ACTIVE]
+    H --> I[Return updated warehouse]
+```
+
+## External Dependencies
+
+- [organization::Site](../../../organization/docs/models/Site.md) - Validates that the referenced site is still active
+
+## Error Scenarios
+
+- **WAREHOUSE_NOT_FOUND**: Referenced warehouse does not exist
+- **WAREHOUSE_NOT_INACTIVE**: Warehouse is not in INACTIVE status
+- **SITE_INACTIVE**: Referenced site is no longer in ACTIVE status
+
+## Test Cases
+
+- returns error when warehouse not found
+- returns error when warehouse already active
+- returns error when site is inactive
+- reactivates inactive warehouse

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

@@ -0,0 +1,52 @@
+# RecordCountLine
+
+## Overview
+
+recordCountLine records the physically counted quantity for a specific count line during an inventory count. The variance between the system snapshot and the counted quantity is automatically calculated. Count lines in RECOUNT status (after a previous rejection) or REJECTED status (re-counted after rejection) can also be recorded.
+
+## Business Rules
+
+- Inventory count must be in IN_PROGRESS status
+- Count line must be in PENDING, RECOUNT, or REJECTED status
+- countedQuantity is required
+- Variance is automatically calculated as countedQuantity minus system snapshot quantity
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive record request] --> B{Count exists?}
+    B -->|No| C[Return error: COUNT_NOT_FOUND]
+    B -->|Yes| D{Count IN_PROGRESS?}
+    D -->|No| E[Return error: COUNT_NOT_IN_PROGRESS]
+    D -->|Yes| F{Count line exists?}
+    F -->|No| G[Return error: COUNT_LINE_NOT_FOUND]
+    F -->|Yes| H{Line status PENDING, RECOUNT, or REJECTED?}
+    H -->|No| I[Return error: COUNT_LINE_INVALID_STATUS]
+    H -->|Yes| J[Record countedQuantity]
+    J --> K[Calculate variance]
+    K --> L[Update count line]
+    L --> M[Return updated count line]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COUNT_NOT_FOUND**: Referenced count does not exist
+- **COUNT_NOT_IN_PROGRESS**: Count is not in IN_PROGRESS status
+- **COUNT_LINE_NOT_FOUND**: Referenced count line does not exist
+- **COUNT_LINE_INVALID_STATUS**: Count line is not in PENDING, RECOUNT, or REJECTED status
+
+## Test Cases
+
+- returns error when count not found
+- returns error when count not in progress
+- returns error when count line not found
+- returns error when line not pending
+- records counted quantity
+- calculates variance correctly
+- allows recording for RECOUNT status lines
+- allows recording for REJECTED status lines

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

@@ -0,0 +1,42 @@
+# RejectCountLine
+
+## Overview
+
+rejectCountLine rejects a count line, optionally requesting a recount. The line can be transitioned to either REJECTED (terminal) or RECOUNT (allows re-recording of the counted quantity) status.
+
+## Business Rules
+
+- Count line must be in PENDING status
+- Can optionally set the line to RECOUNT status instead of REJECTED
+- RECOUNT status allows the line to be re-recorded
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive reject request] --> B{Count line exists?}
+    B -->|No| C[Return error: COUNT_LINE_NOT_FOUND]
+    B -->|Yes| D{Line status PENDING?}
+    D -->|No| E[Return error: COUNT_LINE_NOT_PENDING]
+    D -->|Yes| F{Recount requested?}
+    F -->|Yes| G[Update status to RECOUNT]
+    F -->|No| H[Update status to REJECTED]
+    G --> I[Return updated line]
+    H --> I
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COUNT_LINE_NOT_FOUND**: Referenced count line does not exist
+- **COUNT_LINE_NOT_PENDING**: Count line is not in PENDING status
+
+## Test Cases
+
+- returns error when not found
+- returns error when not pending
+- rejects line
+- sets line to RECOUNT status

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

@@ -0,0 +1,38 @@
+# RejectInventoryAdjustment
+
+## Overview
+
+rejectInventoryAdjustment rejects a pending inventory adjustment, transitioning it from PENDING_APPROVAL to REJECTED status. A rejected adjustment does not affect stock levels and cannot be confirmed.
+
+## Business Rules
+
+- Adjustment must exist
+- Adjustment must be in PENDING_APPROVAL status
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive reject request] --> B{Adjustment exists?}
+    B -->|No| C[Return error: ADJUSTMENT_NOT_FOUND]
+    B -->|Yes| D{Status is PENDING_APPROVAL?}
+    D -->|No| E[Return error: ADJUSTMENT_NOT_PENDING_APPROVAL]
+    D -->|Yes| F[Update status to REJECTED]
+    F --> G[Return updated adjustment]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ADJUSTMENT_NOT_FOUND**: Referenced adjustment does not exist
+- **ADJUSTMENT_NOT_PENDING_APPROVAL**: Adjustment is not in PENDING_APPROVAL status
+
+## Test Cases
+
+- returns error when not found
+- returns error when not pending
+- rejects adjustment
+- rejected adjustment does not affect stock

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

@@ -0,0 +1,37 @@
+# ReleaseReservation
+
+## Overview
+
+releaseReservation releases a previously reserved quantity of stock, restoring it to available status. This is used when a reservation is no longer needed, such as when a sales order is cancelled or fulfilled through a different mechanism.
+
+## Business Rules
+
+- A stock level record must exist for the item-location pair
+- The current reserved quantity must be sufficient for the release amount
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive release request] --> B{Stock level exists?}
+    B -->|No| C[Return error: STOCK_LEVEL_NOT_FOUND]
+    B -->|Yes| D{Reserved >= release amount?}
+    D -->|No| E[Return error: INSUFFICIENT_RESERVED_STOCK]
+    D -->|Yes| F[Decrease reserved quantity]
+    F --> G[Return updated stock level]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **STOCK_LEVEL_NOT_FOUND**: No stock level record exists for the item-location pair
+- **INSUFFICIENT_RESERVED_STOCK**: Release amount exceeds the currently reserved quantity
+
+## Test Cases
+
+- returns error when stock level not found
+- returns error when release exceeds reserved
+- releases reservation successfully

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

@@ -0,0 +1,49 @@
+# ReserveStock
+
+## Overview
+
+reserveStock reserves a quantity of stock at a specific item-location pair, reducing the available quantity. Reserved stock remains on-hand but is earmarked for a specific purpose (e.g., a sales order) and cannot be used for other transactions.
+
+## Business Rules
+
+- Item must exist
+- Storage location must exist
+- A stock level record must exist for the item-location pair
+- Requested quantity must not exceed available stock (onHand - reserved - blocked)
+- Increases reservedQuantity on the StockLevel record
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive reserve 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{Stock level exists?}
+    F -->|No| G[Return error: STOCK_LEVEL_NOT_FOUND]
+    F -->|Yes| H{Available >= requested?}
+    H -->|No| I[Return error: INSUFFICIENT_AVAILABLE_STOCK]
+    H -->|Yes| J[Increase reserved quantity]
+    J --> K[Return updated stock level]
+```
+
+## 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
+- **STOCK_LEVEL_NOT_FOUND**: No stock level record exists for the item-location pair
+- **INSUFFICIENT_AVAILABLE_STOCK**: Available stock is less than the requested reservation quantity
+
+## Test Cases
+
+- returns error when item not found
+- returns error when location not found
+- returns error when no stock level exists
+- returns error when insufficient available stock
+- reserves stock successfully
+- updates available quantity correctly

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

@@ -0,0 +1,38 @@
+# ReviseInventoryAdjustment
+
+## Overview
+
+reviseInventoryAdjustment transitions a rejected inventory adjustment back to DRAFT status, allowing the user to modify and resubmit it. This supports the workflow where a rejected adjustment is corrected (e.g., updated reason code, revised quantity) rather than abandoned.
+
+## Business Rules
+
+- Adjustment must exist
+- Adjustment must be in REJECTED status
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive revise request] --> B{Adjustment exists?}
+    B -->|No| C[Return error: ADJUSTMENT_NOT_FOUND]
+    B -->|Yes| D{Status is REJECTED?}
+    D -->|No| E[Return error: ADJUSTMENT_NOT_REJECTED]
+    D -->|Yes| F[Update status to DRAFT]
+    F --> G[Return updated adjustment]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ADJUSTMENT_NOT_FOUND**: Referenced adjustment does not exist
+- **ADJUSTMENT_NOT_REJECTED**: Adjustment is not in REJECTED status
+
+## Test Cases
+
+- returns error when not found
+- returns error when not in REJECTED status
+- transitions rejected adjustment back to DRAFT
+- revised adjustment can be modified and resubmitted

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

@@ -0,0 +1,47 @@
+# StartInventoryCount
+
+## Overview
+
+startInventoryCount initiates the count process, transitioning the count from PLANNED to IN_PROGRESS status. It snapshots the current system on-hand quantities for each item-location pair within the count scope and creates individual count lines. Optionally, stock movements can be frozen for the counted scope during the count.
+
+## Business Rules
+
+- Count must exist
+- Count must be in PLANNED status
+- Snapshots current on-hand quantity for each item-location pair
+- Optionally freezes stock movements for the counted scope
+- Creates an InventoryCountLine for each item-location pair in scope
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive start request] --> B{Count exists?}
+    B -->|No| C[Return error: COUNT_NOT_FOUND]
+    B -->|Yes| D{Status is PLANNED?}
+    D -->|No| E[Return error: COUNT_NOT_PLANNED]
+    D -->|Yes| F[Snapshot system quantities]
+    F --> G{Freeze requested?}
+    G -->|Yes| H[Block stock movements for scope]
+    H --> I[Create count lines for each item-location]
+    G -->|No| I
+    I --> J[Update status to IN_PROGRESS]
+    J --> K[Return started count]
+```
+
+## External Dependencies
+
+- None (internal models: [StockLevel](../models/StockLevel.md), [InventoryCountLine](../models/InventoryCountLine.md))
+
+## Error Scenarios
+
+- **COUNT_NOT_FOUND**: Referenced count does not exist
+- **COUNT_NOT_PLANNED**: Count is not in PLANNED status
+
+## Test Cases
+
+- returns error when not found
+- returns error when not planned
+- starts count and snapshots quantities
+- creates count lines for all items at location
+- optionally freezes stock movements

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

@@ -0,0 +1,37 @@
+# SubmitInventoryAdjustment
+
+## Overview
+
+submitInventoryAdjustment submits an inventory adjustment for approval, transitioning it from DRAFT to PENDING_APPROVAL status. This enables a review workflow before adjustments are confirmed and applied to stock levels.
+
+## Business Rules
+
+- Adjustment must exist
+- Adjustment must be in DRAFT status
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive submit request] --> B{Adjustment exists?}
+    B -->|No| C[Return error: ADJUSTMENT_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return error: ADJUSTMENT_NOT_DRAFT]
+    D -->|Yes| F[Update status to PENDING_APPROVAL]
+    F --> G[Return updated adjustment]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ADJUSTMENT_NOT_FOUND**: Referenced adjustment does not exist
+- **ADJUSTMENT_NOT_DRAFT**: Adjustment is not in DRAFT status
+
+## Test Cases
+
+- returns error when not found
+- returns error when not DRAFT
+- submits for approval

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

@@ -0,0 +1,41 @@
+# UpdateLot
+
+## Overview
+
+updateLot modifies the mutable fields of a lot record, including manufactureDate, expirationDate, and supplierLotReference. The lotNumber is immutable after creation and cannot be changed.
+
+## Business Rules
+
+- Lot must exist
+- Lot must not be in FULLY_CONSUMED status
+- lotNumber is immutable after creation
+- Can update manufactureDate, expirationDate, and supplierLotReference
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Lot exists?}
+    B -->|No| C[Return error: LOT_NOT_FOUND]
+    B -->|Yes| D{Status is FULLY_CONSUMED?}
+    D -->|Yes| E[Return error: LOT_FULLY_CONSUMED]
+    D -->|No| F[Update mutable fields]
+    F --> G[Return updated lot]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **LOT_NOT_FOUND**: Referenced lot does not exist
+- **LOT_FULLY_CONSUMED**: Lot is in FULLY_CONSUMED status and cannot be updated
+
+## Test Cases
+
+- returns error when lot not found
+- returns error when lot is FULLY_CONSUMED
+- updates expiration date
+- updates supplier lot reference
+- lot number cannot be changed

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

@@ -0,0 +1,45 @@
+# UpdateStockMovement
+
+## Overview
+
+updateStockMovement modifies a stock movement that is still in DRAFT status. Fields can be updated and move lines can be added or removed. The same validation rules from creation apply to any changed fields.
+
+## Business Rules
+
+- Stock movement must exist
+- Stock movement must be in DRAFT status
+- Same validation rules as creation apply to changed fields and new lines
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update 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[Apply changes and validate]
+    F --> G[Update movement record]
+    G --> H[Return updated 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 in DRAFT
+- returns error when line item not active
+- returns error when line quantity is zero or negative
+- returns error when source equals destination
+- returns error when location not found
+- updates movement date
+- adds new move line
+- removes move line