# 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 StockLevel quantities across all **active** storage locations in the site and StockReservation open reservation quantities for the site, grouped by item
- Returns aggregated records containing:
  - `itemId`
  - `totalOnHand` — sum of onHand across locations
  - `totalReserved` — sum of OPEN site-level reservation quantity, derived as `max(reservedQuantity - consumedQuantity, 0)`
  - `totalBlocked` — sum of blocked across locations
  - `totalAvailable` — sum of AVAILABLE stock type quantity across active locations minus OPEN site-level reservation quantity
- 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 StockLevel for active locations and StockReservation for site where itemId matches]
    E -->|No| G[SELECT StockLevel for active locations and StockReservation for site]
    F --> H[Aggregate by item and return 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