# GetWarehouseStockSummary

## Overview

GetWarehouseStockSummary aggregates stock quantities across all storage locations within a warehouse for each item. It provides a warehouse-level inventory overview and supports optional filtering to a specific item.

## Business Rules

- Requires `warehouseId`
- Optionally accepts `itemId` to filter to a specific item
- Sums quantities across all **active** storage locations in the warehouse, grouped by item
- Returns aggregated records containing:
  - `itemId`
  - `totalOnHand` — sum of onHand across locations
  - `totalReserved` — sum of reserved across locations
  - `totalIncoming` — sum of incoming across locations
  - `totalBlocked` — sum of blocked across locations
  - `totalAvailable` — sum of available across locations
- Excludes inactive storage locations from aggregation
- Returns error if warehouse does not exist

## Process Flow

```mermaid
flowchart TD
    A[Receive warehouseId and optional itemId] --> B{Warehouse exists?}
    B -->|No| C[Return WAREHOUSE_NOT_FOUND error]
    B -->|Yes| D[Resolve all active storage locations in warehouse]
    D --> E{itemId provided?}
    E -->|Yes| F[SELECT and SUM from StockLevel where storageLocationId in active locations AND itemId matches, GROUP BY itemId]
    E -->|No| G[SELECT and SUM from StockLevel where storageLocationId in active locations, GROUP BY itemId]
    F --> H[Return aggregated records]
    G --> H
```

## External Dependencies

- None

## Error Scenarios

- **WAREHOUSE_NOT_FOUND**: The specified warehouse does not exist

## Test Cases

- returns aggregated quantities per item
- correctly sums across multiple locations
- filters by item when provided
- returns error when warehouse not found
- excludes inactive storage locations
