# ListLots

## Overview

ListLots retrieves a paginated list of lots with optional filtering by itemId, siteId, and status. It supports general-purpose lot browsing, operator-driven FEFO picking decisions, and lot selection during goods issue operations. Results are sortable by expirationDate, manufactureDate, or lotNumber.

## Business Rules

- Optionally accepts `itemId` to filter lots belonging to a specific item
- Optionally accepts `siteId` to filter lots that have stock in a specific site (via LotStockLevel, resolved through StorageLocations under the site)
- Optionally accepts `status` to filter by lot status (ACTIVE or FULLY_CONSUMED)
- Supports sorting by `expirationDate`, `manufactureDate`, or `lotNumber`
- Default sort is `expirationDate` ascending (soonest first) for FEFO support
- Supports pagination via `limit` and `offset`
- Returns an empty list if no lots match the criteria

## Process Flow

```mermaid
flowchart TD
    A[Receive optional filters] --> B[SELECT from Lot]
    B --> C{itemId provided?}
    C -->|Yes| D[Filter by itemId]
    C -->|No| E{siteId provided?}
    D --> E
    E -->|Yes| F[Resolve StorageLocations under site, join LotStockLevel, filter by those location ids]
    E -->|No| G{status provided?}
    F --> G
    G -->|Yes| H[Filter by status]
    G -->|No| I[Apply sort order and pagination]
    H --> I
    I --> J{Results found?}
    J -->|Yes| K[Return list of Lot records]
    J -->|No| L[Return empty list]
```

## External Dependencies

- None

## Error Scenarios

- Returns empty list if no lots match the criteria

## Test Cases

- returns all lots when no filters provided
- filters by itemId
- filters by siteId via lot stock levels
- filters by ACTIVE status
- filters by FULLY_CONSUMED status
- combines multiple filters
- sorts by expiration date ascending by default
- sorts by manufacture date when specified
- sorts by lot number when specified
- returns empty list when no lots match
- supports pagination with limit and offset
