# UpdateChartOfAccounts

## Permission Scope

chartOfAccounts

## Overview

updateChartOfAccounts modifies the mutable fields (name, description) of an existing Chart of Accounts. Updates are permitted while the CoA is in DRAFT or ACTIVE status. ARCHIVED CoA records cannot be updated.

## Business Rules

- Target CoA must exist
- Target CoA must be in DRAFT or ACTIVE status; updating an ARCHIVED CoA is rejected
- Name, when provided, must be non-empty
- Description is optional and can be cleared

## Process Flow

```mermaid
flowchart TD
    A[Receive update request] --> B{CoA exists?}
    B -->|No| C[Return error: not found]
    B -->|Yes| D{Status is DRAFT or ACTIVE?}
    D -->|No| E[Return error: CoA is archived]
    D -->|Yes| F{Name valid if provided?}
    F -->|No| G[Return error: name required]
    F -->|Yes| H[Update CoA fields]
    H --> I[Return updated CoA]
```

## External Dependencies

- None

## Error Scenarios

- **CHART_OF_ACCOUNTS_NOT_FOUND**: Referenced CoA does not exist
- **CHART_OF_ACCOUNTS_ARCHIVED**: Parent CoA is in ARCHIVED status and cannot be modified
- **NAME_REQUIRED**: Name is empty, whitespace-only, or not provided

## Test Cases

- returns error when CoA does not exist
- returns error when CoA is ARCHIVED
- returns error when name is empty
- updates name of a DRAFT CoA
- updates description of an ACTIVE CoA
- clears description by setting to null
- passes custom fields through to update
