# ListAllocationCycles

## Overview

ListAllocationCycles retrieves a list of allocation cycle records matching optional filter criteria. Callers can filter by companyId, type (ASSESSMENT or DISTRIBUTION), status (DRAFT, VALIDATED, EXECUTED, POSTED, REVERSED), and accountingPeriodId. This query supports allocation cycle browsing, period-end processing review, and allocation audit workflows.

## Business Rules

- Accepts optional filter parameters: `{ companyId, type, status, accountingPeriodId }`
- Returns a list of allocation cycles matching all provided filters (AND logic)
- When no filters are provided, returns all allocation cycles accessible to the caller
- Each returned allocation cycle includes header fields but does not include nested rules and results (use GetAllocationCycle for full details)
- Returns an empty list if no allocation cycles match the given filters
- Results are scoped to the caller's accessible companies

## Process Flow

```mermaid
flowchart TD
    A[Receive input with optional filters] --> B[Build query with provided filters]
    B --> C{companyId provided?}
    C -->|Yes| D[Add companyId filter]
    C -->|No| E[Skip companyId filter]
    D --> F{type provided?}
    E --> F
    F -->|Yes| G[Add type filter]
    F -->|No| H[Skip type filter]
    G --> I{status provided?}
    H --> I
    I -->|Yes| J[Add status filter]
    I -->|No| K[Skip status filter]
    J --> L{accountingPeriodId provided?}
    K --> L
    L -->|Yes| M[Add accountingPeriodId filter]
    L -->|No| N[Skip accountingPeriodId filter]
    M --> O[Execute query]
    N --> O
    O --> P[Return list of matching allocation cycles]
```

## External Dependencies

- None

## Error Scenarios

- **INVALID_TYPE_FILTER**: Provided type value is not valid for this entity type
- **INVALID_STATUS_FILTER**: Provided status value is not valid for this entity type
- **ACCOUNTING_PERIOD_NOT_FOUND**: Referenced accounting period does not exist

## Test Cases

- returns all allocation cycles when no filters are provided
- returns allocation cycles filtered by companyId
- returns allocation cycles filtered by type ASSESSMENT
- returns allocation cycles filtered by type DISTRIBUTION
- returns allocation cycles filtered by status POSTED
- returns allocation cycles filtered by accountingPeriodId
- returns allocation cycles matching multiple filters simultaneously
- returns an empty list when no allocation cycles match the given filters
- returns error when type filter is invalid
- returns error when status filter is invalid
- returns error when accountingPeriodId does not exist
