# ListTrialBalances

## Overview

ListTrialBalances retrieves a list of trial balance snapshots for a given company, with optional filters by accounting period and variant (PRE_CLOSE or POST_CLOSE). Results are sorted by generation timestamp descending. This query supports multi-period comparison, audit preparation, and period-end close workflows.

## Business Rules

- companyId is required — trial balances are always scoped to a company
- Optional filters:
  - `accountingPeriodId` — filter to a specific period
  - `variant` — filter by PRE_CLOSE or POST_CLOSE
  - `fiscalYearId` — filter to all periods within a fiscal year
- All filters can be combined; when multiple filters are provided, results must match all criteria (AND logic)
- Returns trial balance header records (generation parameters, variant, timestamp — line items are not included in list results for performance)
- Results are sorted by generatedAt timestamp descending (most recent first)
- Returns an empty list if no trial balances match the filters

## Process Flow

```mermaid
flowchart TD
    A[Receive input with companyId] --> B[Build query scoped to companyId]
    B --> C{Period filter provided?}
    C -->|Yes| D[Apply accounting period filter]
    C -->|No| E{Fiscal year filter provided?}
    D --> F{Variant filter provided?}
    E -->|Yes| G[Apply fiscal year filter via period lookup]
    E -->|No| F
    G --> F
    F -->|Yes| H[Apply variant filter]
    F -->|No| I[Sort by generatedAt descending]
    H --> I
    I --> J[Return trial balance list]
```

## External Dependencies

- None

## Error Scenarios

- **EMPTY_RESULT**: No records match the given criteria

## Test Cases

- returns all trial balances for a company
- returns trial balances filtered by accounting period
- returns trial balances filtered by variant
- returns trial balances filtered by fiscal year via subquery
- returns empty list when no trial balances match
