# 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
