# DeactivateAccount

## Permission Scope

accountManagement

## Overview

deactivateAccount transitions a GL account from ACTIVE to INACTIVE status, preventing new journal postings while preserving the account and its history for regulatory reporting and audit purposes. An optional successor account can be designated during deactivation; posting redirection is owned by the general-ledger module. A pre-deactivation hook is exposed for the GL module to block deactivation when open or unreconciled balances exist.

## Business Rules

- Target account must exist
- Parent CoA must be in ACTIVE status; deactivating an account under an ARCHIVED CoA is rejected. Note: the DRAFT CoA case is unreachable because account activation requires an ACTIVE CoA, so an ACTIVE account cannot exist under a DRAFT CoA
- Target account must be in ACTIVE status
- Deactivating a DRAFT account fails with an invalid state transition error
- A successor account, when provided, must be ACTIVE at the time of mapping
- Deactivation exposes a pre-deactivation hook for the GL module to block the transition when open balances exist
- Without a GL module integrated, deactivation proceeds without balance checks
- Successor account mapping is optional

## Process Flow

```mermaid
flowchart TD
    A[Receive deactivate request] --> B{Account exists?}
    B -->|No| C[Return error: not found]
    B -->|Yes| B2{Parent CoA is ACTIVE?}
    B2 -->|No| B3[Return error: CoA is not ACTIVE]
    B2 -->|Yes| D{Status is ACTIVE?}
    D -->|No| E[Return error: invalid state transition]
    D -->|Yes| F{Pre-deactivation hook registered?}
    F -->|Yes| G{Balance check passes?}
    G -->|No| H[Return error: open balances]
    G -->|Yes| I{Successor provided?}
    F -->|No| I
    I -->|Yes| J{Successor is ACTIVE?}
    J -->|No| K[Return error: successor not active]
    J -->|Yes| L[Map successor and set INACTIVE]
    I -->|No| L[Set status to INACTIVE]
    L --> M[Return deactivated account]
```

## External Dependencies

- None (GL module balance check is an optional integration hook)

## Error Scenarios

- **ACCOUNT_NOT_FOUND**: Specified account ID does not exist
- **CHART_OF_ACCOUNTS_ARCHIVED**: Parent CoA is in ARCHIVED status and cannot be modified
- **INVALID_STATE_TRANSITION**: Requested state transition is not allowed from the current status
- **OPEN_BALANCES_EXIST**: Pre-deactivation hook reports open or unreconciled balances (GL module integration)
- **SUCCESSOR_NOT_ACTIVE**: Specified successor account is not in ACTIVE status

## Test Cases

- returns error when account does not exist
- returns error when parent CoA is ARCHIVED
- returns error when account is not ACTIVE
- returns error when account is DRAFT
- returns error when successor account is not ACTIVE
- deactivates an ACTIVE account without successor
- deactivates an ACTIVE account with successor mapping
- deactivates without balance check when GL hook is not registered
- returns error when GL hook reports open balances
