# ExecuteYearEndClose

## Overview

executeYearEndClose runs the fiscal year-end close process on the final period of a fiscal year. It generates a closing journal entry that zeroes out all temporary accounts (REVENUE and EXPENSE types) and transfers the net income or net loss to the retained earnings account. It then generates opening balance entries for the first period of the new fiscal year, carrying forward all permanent account balances (ASSET, LIABILITY, EQUITY). This command can only be executed after the final period's standard close checklist has been completed.

## Business Rules

- Can only be initiated for the final period of a fiscal year
- Initiating year-end close for a non-final period is rejected
- Requires the final period's standard close checklist to be completed through the soft-lock or permanent close stage
- Identifies all temporary accounts (REVENUE and EXPENSE types) with posted journal lines during the fiscal year
- Calculates net income or net loss: total revenue minus total expenses
- Looks up the retained earnings account from the CoA configuration (account with RETAINED_EARNINGS operational classification)
- Fails if no account with RETAINED_EARNINGS operational classification exists in the active CoA
- Generates a closing journal entry that debits all revenue accounts to zero and credits all expense accounts to zero
- Posts the net difference (net income/loss) to the retained earnings account
- The closing journal entry must be balanced (total debits equal total credits)
- The closing journal entry is flagged with a distinct journal type (CLOSING)
- The closing entry is posted to the final period of the fiscal year
- Only accounts with posted journal lines during the fiscal year are included in the closing entry (zero-balance temporary accounts are excluded)
- Generates opening balance entries for all permanent accounts (ASSET, LIABILITY, EQUITY types)
- Opening balance entries carry the correct closing balance from each permanent account, including updated retained earnings
- Opening balance entries are posted to the first period of the new fiscal year
- Opening balance entries are flagged with a distinct journal type (OPENING)
- The sum of all opening balance debits equals the sum of all opening balance credits
- Opening balances are only generated if the new fiscal year's periods exist
- Fails gracefully if the new fiscal year has not been defined
- Year-end close cannot be run twice for the same fiscal year; duplicate attempts are rejected
- After year-end close, the final period of the old fiscal year is permanently closed
- Year-end close is scoped to a single company
- Emits audit events recording each step: closing entry generation, retained earnings posting, opening balance generation

## Process Flow

```mermaid
flowchart TD
    A[Receive execute year-end close request] --> B{Period is the final period of a fiscal year?}
    B -->|No| C[Return error: not final period]
    B -->|Yes| D{Standard close checklist completed?}
    D -->|No| E[Return error: standard close not complete]
    D -->|Yes| F{Already run for this fiscal year?}
    F -->|Yes| G[Return error: duplicate year-end close]
    F -->|No| H[Identify all REVENUE and EXPENSE accounts with activity]
    H --> I[Calculate net income/loss]
    I --> J{Retained earnings account configured in CoA?}
    J -->|No| K[Return error: retained earnings account required]
    J -->|Yes| L[Generate closing journal entry]
    L --> M[Debit revenue accounts to zero, credit expense accounts to zero]
    M --> N[Post net difference to retained earnings]
    N --> O{New fiscal year periods exist?}
    O -->|No| P[Return error: new fiscal year not defined]
    O -->|Yes| Q[Generate opening balance entries for permanent accounts]
    Q --> R[Post opening balances to first period of new fiscal year]
    R --> S[Permanently close final period]
    S --> T[Emit audit events]
    T --> U[Return year-end close result]
```

## External Dependencies

- [coa-management::getChartOfAccounts](../../../coa-management/docs/queries/GetChartOfAccounts.md) - Retrieves the active CoA, account types, and retained earnings account configuration
- [coa-management::getAccount](../../../coa-management/docs/queries/GetAccount.md) - Retrieves individual GL accounts for closing and opening entries

## Error Scenarios

- **NOT_FINAL_PERIOD**: The specified period is not the final period of its fiscal year
- **STANDARD_CLOSE_NOT_COMPLETE**: The final period's standard close checklist has not been completed through soft-lock or permanent close
- **DUPLICATE_YEAR_END_CLOSE**: Year-end close has already been executed for this fiscal year
- **RETAINED_EARNINGS_ACCOUNT_NOT_FOUND**: No account with RETAINED_EARNINGS operational classification exists in the active CoA
- **NEW_FISCAL_YEAR_NOT_DEFINED**: The new fiscal year has not been defined; opening balance entries cannot be generated

## Test Cases

- returns error when accounting period does not exist
- returns error when period is not the final period of its fiscal year
- returns error when standard close checklist is not complete
- returns error when year-end close has already been executed
- returns error when no retained earnings account exists
- returns error when no new fiscal year is defined
- successfully executes year-end close
