# ListCostCenters

## Overview

ListCostCenters retrieves a list of cost center records matching optional filter criteria. Callers can filter by companyId, category (overhead, production, administration, sales, research), and hierarchyNodeId to find cost centers assigned to a specific node in the hierarchy. This query supports cost center browsing, allocation rule setup, and budget planning.

## Business Rules

- Accepts optional filter parameters: `{ companyId, category, hierarchyNodeId }`
- Returns a list of cost centers matching all provided filters (AND logic)
- When no filters are provided, returns all cost centers accessible to the caller
- Each returned cost center includes all master data fields and hierarchy node assignment
- Returns an empty list if no cost centers 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{category provided?}
    E --> F
    F -->|Yes| G[Add category filter]
    F -->|No| H[Skip category filter]
    G --> I{hierarchyNodeId provided?}
    H --> I
    I -->|Yes| J[Add hierarchyNodeId filter]
    I -->|No| K[Skip hierarchyNodeId filter]
    J --> L[Execute query]
    K --> L
    L --> M[Return list of matching cost centers]
```

## External Dependencies

- None

## Error Scenarios

- **INVALID_CATEGORY_FILTER**: Provided category value is not a recognized category for this entity
- **HIERARCHY_NODE_NOT_FOUND**: Referenced hierarchy node does not exist or does not belong to the same company

## Test Cases

- returns all cost centers when no filters are provided
- returns cost centers filtered by companyId
- returns cost centers filtered by category
- returns cost centers filtered by hierarchyNodeId
- returns cost centers matching multiple filters simultaneously
- returns an empty list when no cost centers match the given filters
- returns error when category filter is invalid
- returns error when hierarchyNodeId does not exist
