# ReserveStock

## Permission Scope

stockOperation

## 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 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
