# GetSiteStockSummary

## Overview

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

## Business Rules

- Requires `siteId`
- Optionally accepts `itemId` to filter to a specific item
- Sums quantities across all **active** storage locations in the site, 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 an empty summary when the site has no active storage locations (including the case where the siteId does not exist)

## Process Flow

```mermaid
flowchart TD
    A[Receive siteId and optional itemId] --> B[Resolve all active storage locations in site]
    B --> C{Any active locations?}
    C -->|No| D[Return empty summary]
    C -->|Yes| 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 — Site existence is inferred from the presence of active StorageLocations

## Error Scenarios

- None — returns an empty summary when no active locations exist under the site

## Test Cases

- returns aggregated quantities per item
- correctly sums across multiple locations
- filters by item when provided
- returns empty summary when site has no active locations
