# FinancialStatement

## Description

FinancialStatement represents a generated financial report — Balance Sheet (statement of financial position), Profit & Loss (income statement), or Cash Flow Statement. Each statement is scoped to a single company, denominated in the company's base currency, and structured according to the account group hierarchy defined in coa-management. A statement is created in DRAFT status from trial balance data and can be regenerated (replaced) until finalized. Once FINALIZED, the statement is immutable. The statement contains FinancialStatementLineItem records organized by account group sections with subtotals and totals.

## Domain Model Definitions

### Model type

Stateful

#### State Transitions

```mermaid
stateDiagram-v2
    [*] --> Draft: generateFinancialStatement
    Draft --> Draft: regenerateFinancialStatement
    Draft --> Finalized: finalizeFinancialStatement
    Finalized --> [*]
```

| Operation | From | To | Command |
|-----------|------|----|---------|
| finalize | DRAFT | FINALIZED | [finalizeFinancialStatement](../commands/FinalizeFinancialStatement.md) |

### Command Definitions

- [generateFinancialStatement](../commands/GenerateFinancialStatement.md) - Generate a financial statement from trial balance data in DRAFT status
- [regenerateFinancialStatement](../commands/RegenerateFinancialStatement.md) - Regenerate a DRAFT statement with updated trial balance data
- [finalizeFinancialStatement](../commands/FinalizeFinancialStatement.md) - Finalize a DRAFT statement, making it immutable

### Query Definitions

- [GetFinancialStatement](../queries/GetFinancialStatement.md) - Retrieve a financial statement by id with all line items
- [ListFinancialStatements](../queries/ListFinancialStatements.md) - List financial statements for a company with optional filters

### Models

- FinancialStatement
- FinancialStatementLineItem

### Invariants

- FinancialStatement requires a valid companyId referencing an ACTIVE company
- FinancialStatement requires a valid chartOfAccountsId referencing an ACTIVE CoA
- Statement type must be one of: BALANCE_SHEET, PROFIT_AND_LOSS, CASH_FLOW
- Balance Sheet generation requires a single reporting date (as-of date)
- Profit & Loss generation requires a date range (start date and end date)
- Cash Flow Statement generation requires a date range and a method (DIRECT or INDIRECT)
- The reporting date or date range must fall within a closed or active accounting period
- A Balance Sheet includes only accounts of type ASSET, LIABILITY, and EQUITY
- A Profit & Loss includes only accounts of type REVENUE and EXPENSE
- A Cash Flow Statement derives from ledger data covering all account types relevant to cash movements
- On a correctly generated Balance Sheet, total assets equal total liabilities plus total equity
- Statement line items are structured according to the account group hierarchy from coa-management
- Comparative period data, when requested, is aligned to the same account group sections as the current period
- If comparative period trial balance data is unavailable, generation fails with a descriptive error
- FinancialStatement is created in DRAFT status
- A DRAFT statement can be regenerated with updated trial balance data
- A FINALIZED statement is immutable — its line items, parameters, and output cannot be modified
- Finalizing an already FINALIZED statement fails
- All monetary amounts are denominated in the company's base currency
- Accounts not assigned to any account group are reported in an "Unclassified" section and flagged as warnings
- Statement output includes subtotals at each level of the account group hierarchy
- Generating a statement for a period with no posted journal entries fails with a validation error
- Statement generation for a company with no trial balance data for the requested period returns a validation error
- Cash Flow Statement (indirect method) starts with net income and adjusts for non-cash items and working capital changes
- Cash Flow Statement reconciles to the net change between opening and closing cash balances
- Each statement records a reference to the trial balance snapshot it was generated from
- Statement generation emits an audit event via the audit module recording the acting user, timestamp, statement type, and parameters
- Finalizing a statement emits an audit event recording the status transition from DRAFT to FINALIZED

### Relationships

- **References Company**: Each statement is scoped to a Company via companyId (organization module)
- **References ChartOfAccounts**: Each statement references a ChartOfAccounts via chartOfAccountsId (coa-management module)
- **References TrialBalance**: Each statement references the TrialBalance it was generated from via trialBalanceId
- **References TrialBalance (comparative)**: Optionally references a prior period TrialBalance via comparativePeriodTrialBalanceId
- **Has Many FinancialStatementLineItem**: A statement contains line items organized by sections
