# ListExpiringLots

## Overview

ListExpiringLots lists lots with expiration dates within a specified threshold. It supports expiration alerting and FEFO (First Expired, First Out) picking decisions. Results are sorted by expiration date ascending so the soonest-expiring lots appear first.

## Business Rules

- Requires `daysUntilExpiry` — the number of days from now to use as the expiration threshold
- Optionally accepts `itemId` to filter to a specific item
- Optionally accepts `warehouseId` to filter to lots with stock in a specific warehouse
- Filters lots where `expirationDate <= now + daysUntilExpiry`
- Excludes fully consumed lots (lots with zero remaining stock)
- Returns results sorted by `expirationDate` ascending (soonest first)
- Supports pagination via `limit` and `offset` parameters; returns `hasNextPage` to indicate more results
- Returns an empty list if no expiring lots match the criteria

## Process Flow

```mermaid
flowchart TD
    A[Receive daysUntilExpiry and optional filters] --> B[Compute threshold date = now + daysUntilExpiry]
    B --> C[SELECT from Lot where expirationDate <= threshold]
    C --> D[Exclude fully consumed lots]
    D --> E{itemId provided?}
    E -->|Yes| F[Filter by itemId]
    E -->|No| G{warehouseId provided?}
    F --> G
    G -->|Yes| H[Filter by lots with stock in warehouse]
    G -->|No| I[Sort by expirationDate ascending]
    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 expiring lots match the criteria

## Test Cases

- returns lots expiring within threshold
- sorts by expiration date ascending
- excludes fully consumed lots
- filters by item when provided
- filters by warehouse when provided
- returns empty list when no expiring lots
