# ListCostElements

## Overview

ListCostElements retrieves a list of cost element records matching optional filter criteria. Callers can filter by companyId, type (PRIMARY or SECONDARY), category (overhead, material, labor, depreciation for primary; assessment, distribution, internal_activity_allocation, settlement for secondary), and status (DRAFT, ACTIVE, INACTIVE). This query supports cost element catalog browsing, allocation rule configuration, and budget line item setup.

## Business Rules

- Accepts optional filter parameters: `{ companyId, type, category, status }`
- Returns a list of cost elements matching all provided filters (AND logic)
- When no filters are provided, returns all cost elements accessible to the caller
- Each returned cost element includes all fields (code, name, type, category, status, validity period, GL account reference, companyId, description)
- Returns an empty list if no cost elements 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{category provided?}
    H --> I
    I -->|Yes| J[Add category filter]
    I -->|No| K[Skip category filter]
    J --> L{status provided?}
    K --> L
    L -->|Yes| M[Add status filter]
    L -->|No| N[Skip status filter]
    M --> O[Execute query]
    N --> O
    O --> P[Return list of matching cost elements]
```

## 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
- **INVALID_CATEGORY_FILTER**: Provided category value is not a recognized category for this entity

## Test Cases

- returns all cost elements when no filters are provided
- returns cost elements filtered by companyId
- returns cost elements filtered by type PRIMARY
- returns cost elements filtered by type SECONDARY
- returns cost elements filtered by category
- returns cost elements filtered by status ACTIVE
- returns cost elements matching multiple filters simultaneously
- returns an empty list when no cost elements match the given filters
- returns error when type filter is invalid
- returns error when status filter is invalid
- returns error when category filter is invalid
