# MoveAccountGroup

## Permission Scope

accountManagement

## Overview

moveAccountGroup reparents an account group by changing its parent reference within the same CoA. The group and all its descendants move together, preserving the subtree structure and all account assignments. Moving to a null parent promotes the group to a root group.

## Business Rules

- Target group must exist
- Parent CoA must be in DRAFT or ACTIVE status; moving a group under an ARCHIVED CoA is rejected
- New parent group must exist within the same CoA when specified (null for root promotion)
- A group cannot be moved under itself or any of its descendants (circular reference prevention)
- All child groups and their account assignments are preserved during the move
- Group code and account assignments are unchanged by the move

## Process Flow

```mermaid
flowchart TD
    A[Receive move 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{New parent specified?}
    D -->|Yes| E{New parent exists in same CoA?}
    E -->|No| F[Return error: parent not found]
    E -->|Yes| G{New parent is descendant of group?}
    G -->|Yes| H[Return error: circular reference]
    G -->|No| I[Update parent reference]
    D -->|No/null| I[Promote to root]
    I --> J[Return moved 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
- **PARENT_GROUP_NOT_FOUND**: Specified parent group does not exist or belongs to a different CoA
- **CIRCULAR_REFERENCE**: New parent is the group itself or one of its descendants

## Test Cases

- returns error when group does not exist
- returns error when parent CoA is ARCHIVED
- returns error when new parent does not exist
- returns error when new parent belongs to different CoA
- returns error when moving group under itself
- returns error when moving group under its descendant
- moves group to different parent
- promotes group to root by setting parent to null
