# RegenerateFinancialStatement

## Permission Scope

financialStatement

## Overview

regenerateFinancialStatement replaces the content of an existing DRAFT financial statement with fresh data from the current trial balance. This allows controllers to re-run statement generation after posting correcting journal entries or adjusting entries without creating a new statement entity. Only DRAFT statements can be regenerated — FINALIZED statements are immutable.

## Business Rules

- Financial statement must exist and be identified by `id`
- Financial statement must be in DRAFT status; FINALIZED statements cannot be regenerated
- The referenced trial balance must still exist and be valid
- The system re-fetches the trial balance data and re-maps accounts to statement sections
- All existing line items are replaced with the regenerated output
- The generation timestamp is updated to reflect the regeneration time
- If comparative period data was included, it is also refreshed from the comparative trial balance
- Regeneration follows the same validation rules as initial generation (balanced trial balance, valid account mappings)
- Emits an audit event via the audit module recording the acting user, timestamp, and regeneration parameters

## Process Flow

```mermaid
flowchart TD
    A[Receive regenerate request] --> B{Financial statement exists?}
    B -->|No| C[Return error: statement not found]
    B -->|Yes| D{Statement in DRAFT status?}
    D -->|No| E[Return error: statement is finalized]
    D -->|Yes| F[Fetch current trial balance data]
    F --> G[Load account group hierarchy from coa-management]
    G --> H[Re-map accounts to statement sections by account type]
    H --> I[Aggregate balances per account group]
    I --> J{Comparative period included?}
    J -->|Yes| K[Refresh comparative period data]
    K --> L[Replace all line items with regenerated output]
    J -->|No| L
    L --> M[Update generation timestamp]
    M --> N[Emit audit event]
    N --> O[Return regenerated statement]
```

## External Dependencies

- [coa-management::listAccountGroups](../../../coa-management/docs/queries/ListAccountGroups.md) - Retrieves account group hierarchy for structuring statement sections

## Error Scenarios

- **FINANCIAL_STATEMENT_NOT_FOUND**: Referenced financial statement does not exist
- **STATEMENT_ALREADY_FINALIZED**: Financial statement is in FINALIZED status and cannot be regenerated
- **TRIAL_BALANCE_NOT_FOUND**: Referenced trial balance does not exist or is invalid
- **TRIAL_BALANCE_IMBALANCED**: Total debits do not equal total credits
- **COMPARATIVE_TRIAL_BALANCE_NOT_FOUND**: Comparative period trial balance is unavailable when requested

## Test Cases

- returns error when financial statement does not exist
- returns error when financial statement is already FINALIZED
- returns error when trial balance is not found
- returns error when trial balance is imbalanced
- returns error when comparative trial balance is not found
- regenerates statement with fresh data and updates generatedAt
- emits audit event recording statement regeneration
