# FinalizeFinancialStatement

## Permission Scope

financialStatement

## Overview

finalizeFinancialStatement transitions a financial statement from DRAFT to FINALIZED status, making it immutable. Once finalized, the statement's line items, parameters, and output cannot be modified or regenerated. This ensures that published financial statements maintain their integrity for audit and regulatory purposes.

## Business Rules

- Financial statement must exist and be identified by `id`
- Financial statement must be in DRAFT status
- FINALIZED statements cannot be finalized again (no-op / invalid status transition)
- Once finalized, the statement is immutable — line items, parameters, and output cannot be modified
- A FINALIZED statement cannot be regenerated
- Emits an audit event via the audit module recording the status transition from DRAFT to FINALIZED, acting user, and timestamp

## Process Flow

```mermaid
flowchart TD
    A[Receive finalize statement 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: invalid status transition]
    D -->|Yes| F[Transition statement to FINALIZED]
    F --> G[Emit audit event]
    G --> H[Return finalized statement]
```

## External Dependencies

- None (same-module read for financial statement lookup)

## Error Scenarios

- **FINANCIAL_STATEMENT_NOT_FOUND**: Referenced financial statement does not exist
- **INVALID_STATUS_TRANSITION**: Requested status transition is not allowed from the current status

## Test Cases

- returns error when financial statement does not exist
- returns error when financial statement is already FINALIZED
- transitions DRAFT statement to FINALIZED with finalizedAt set
- emits audit event recording status transition from DRAFT to FINALIZED
