# 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
- returns error when no filter is provided
- includes computed available quantity
