# ListBudgets

## Overview

ListBudgets retrieves a list of budget records matching optional filter criteria. Callers can filter by companyId, fiscalYearId, costObjectType (cost center, profit center, or internal order), costObjectId, status (DRAFT, SUBMITTED, APPROVED, ACTIVE, CLOSED), and planVersionId. This query supports budget browsing, budget vs. actual reporting setup, and budget administration workflows.

## Business Rules

- Accepts optional filter parameters: `{ companyId, fiscalYearId, costObjectType, costObjectId, status, planVersionId }`
- Returns a list of budgets matching all provided filters (AND logic)
- When no filters are provided, returns all budgets accessible to the caller
- Each returned budget includes header fields but does not include nested line items (use GetBudget for full details)
- Returns an empty list if no budgets 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{fiscalYearId provided?}
    E --> F
    F -->|Yes| G[Add fiscalYearId filter]
    F -->|No| H[Skip fiscalYearId filter]
    G --> I{costObjectType provided?}
    H --> I
    I -->|Yes| J[Add costObjectType filter]
    I -->|No| K[Skip costObjectType filter]
    J --> L{costObjectId provided?}
    K --> L
    L -->|Yes| M[Add costObjectId filter]
    L -->|No| N[Skip costObjectId filter]
    M --> O{status provided?}
    N --> O
    O -->|Yes| P[Add status filter]
    O -->|No| Q[Skip status filter]
    P --> R{planVersionId provided?}
    Q --> R
    R -->|Yes| S[Add planVersionId filter]
    R -->|No| T[Skip planVersionId filter]
    S --> U[Execute query]
    T --> U
    U --> V[Return list of matching budgets]
```

## External Dependencies

- None

## Error Scenarios

- **INVALID_STATUS_FILTER**: Provided status value is not valid for this entity type
- **INVALID_COST_OBJECT_TYPE_FILTER**: Provided costObjectType is not a recognized cost object type

## Test Cases

- returns all budgets when no filters are provided
- returns budgets filtered by companyId
- returns budgets filtered by fiscalYearId
- returns budgets filtered by costObjectType
- returns budgets filtered by costObjectId
- returns budgets filtered by status ACTIVE
- returns budgets filtered by planVersionId
- returns budgets matching multiple filters simultaneously
- returns an empty list when no budgets match the given filters
- returns error when status filter is invalid
- returns error when costObjectType filter is invalid
