# ListCostLayers

## Overview

ListCostLayers lists cost layers for FIFO valuation auditing. It supports filtering by item, valuation policy, or both. Cost layers are returned in creation order (oldest first) to reflect FIFO consumption sequence.

## Business Rules

- Accepts optional filters (at least one required):
  - `itemId` — filter by specific item
  - `valuationPolicyId` — filter by specific valuation policy
- Returns cost layers ordered by creation date ascending (oldest first)
- Each record includes `quantity`, `unitCost`, `remainingQuantity`, and the referenced `inventoryLedgerId`
- Supports pagination via `limit` and `offset` parameters; returns `hasNextPage` to indicate more results
- Returns an empty list if no matching records exist

## Process Flow

```mermaid
flowchart TD
    A[Receive filter criteria] --> B{At least one filter provided?}
    B -->|No| C[Return error: NO_FILTER_PROVIDED]
    B -->|Yes| D{Which filters provided?}
    D -->|itemId| E[SELECT from CostLayer where itemId matches]
    D -->|valuationPolicyId| F[SELECT from CostLayer where valuationPolicyId matches]
    D -->|both| G[SELECT from CostLayer where itemId and valuationPolicyId match]
    E --> H[Order by createdAt ascending]
    F --> H
    G --> H
    H --> I{Records found?}
    I -->|Yes| J[Return list of CostLayer records]
    I -->|No| K[Return empty list]
```

## External Dependencies

- None

## Error Scenarios

- **NO_FILTER_PROVIDED**: At least one filter must be specified
- Returns empty list if no matching records exist

## Test Cases

- lists cost layers by item
- lists cost layers by valuation policy
- lists cost layers by both item and valuation policy
- returns results in oldest-first order
- returns empty list when no matches
- returns error when no filter is provided
