# GetChartOfAccounts

## Overview

GetChartOfAccounts retrieves a single Chart of Accounts record by id or by companyId. The input is a union type — callers specify exactly one lookup field. This serves as the core CoA lookup for existence checks, company-scoped retrieval, and all CoA lifecycle commands.

## Business Rules

- Accepts one of two lookup variants:
  - `{ id }` — retrieves by unique identifier
  - `{ companyId, status? }` — retrieves the CoA for a specific company, optionally filtered by status (e.g., pass `ACTIVE` to find the current active CoA for uniqueness checks during activation)
- When looking up by companyId without a status filter, returns the most recently created CoA
- Returns the full CoA record including all fields (id, companyId, name, description, baseCurrencyId, status, timestamps)
- Returns null if no matching CoA is found
- All comparisons are exact

## Process Flow

```mermaid
flowchart TD
    A[Receive input] --> B{Which variant?}
    B -->|id| C[SELECT from ChartOfAccounts where id = input.id]
    B -->|companyId| D{Status filter provided?}
    D -->|Yes| D1[SELECT from ChartOfAccounts where companyId = input.companyId AND status = input.status]
    D -->|No| D2[SELECT from ChartOfAccounts where companyId = input.companyId ORDER BY createdAt DESC LIMIT 1]
    C --> E{CoA found?}
    D1 --> E
    D2 --> E
    E -->|Yes| F[Return CoA record]
    E -->|No| G[Return null]
```

## External Dependencies

- None

## Error Scenarios

- **CHART_OF_ACCOUNTS_NOT_FOUND**: No CoA matches the given criteria — caller receives null

## Test Cases

- returns CoA when found by id
- returns null when CoA not found by id
- returns CoA when found by companyId
- returns null when CoA not found by companyId
- returns CoA when found by companyId with status filter
- returns null when no CoA matches companyId and status filter
