# UpdateAccountGroup

## Permission Scope

accountManagement

## Overview

updateAccountGroup modifies the mutable fields (name, sort order, number range) of an existing account group. The target group can be looked up by `id` or by `chartOfAccountsId` + `code`. Group code is fixed by the existing record and is used only as a lookup key when paired with `chartOfAccountsId`. Number range changes must not conflict with existing account assignments or overlap with other groups' ranges.

## Business Rules

- Target group must exist (looked up by `id` or `chartOfAccountsId` + `code`)
- Parent CoA must be in DRAFT or ACTIVE status; updating a group under an ARCHIVED CoA is rejected
- Name, when provided, must be non-empty
- Group code is not part of the update input
- Number range changes, when provided, require both start and end to be provided together, must remain a valid non-overlapping interval within the CoA
- Changing a number range must not invalidate existing accounts already assigned to the group (their codes must still fall within the new range)

## Process Flow

```mermaid
flowchart TD
    A[Receive update request] --> B{Group exists?}
    B -->|No| C[Return error: not found]
    B -->|Yes| B2{Parent CoA is DRAFT or ACTIVE?}
    B2 -->|No| B3[Return error: CoA is ARCHIVED]
    B2 -->|Yes| D{Name valid if provided?}
    D -->|No| E[Return error: name required]
    D -->|Yes| F{Number range valid if changed?}
    F -->|No| G[Return error: invalid or overlapping range]
    F -->|Yes| H{Existing accounts within new range?}
    H -->|No| I[Return error: accounts out of range]
    H -->|Yes| J[Update group fields]
    J --> K[Return updated group]
```

## External Dependencies

- None

## Error Scenarios

- **ACCOUNT_GROUP_NOT_FOUND**: Referenced account group does not exist or belongs to a different CoA
- **CHART_OF_ACCOUNTS_ARCHIVED**: Parent CoA is in ARCHIVED status and cannot be modified
- **NAME_REQUIRED**: Name is empty, whitespace-only, or not provided
- **INVALID_NUMBER_RANGE**: Number range is invalid or overlaps with another group's range
- **ACCOUNTS_OUT_OF_RANGE**: Existing assigned accounts have codes outside the new number range

## Test Cases

- returns error when group does not exist
- looks up group by chartOfAccountsId and code and updates name
- returns error when parent CoA is ARCHIVED
- returns error when name is empty
- returns error when new number range is invalid
- returns error when updating to one-sided number range (start only)
- returns error when updating to one-sided number range (end only)
- returns error when new number range overlaps with another group
- returns error when existing accounts fall outside new number range
- updates group name
- updates sort order
- updates number range
- passes custom fields through to update
