# MoveCostCenterHierarchyNode

## Permission Scope

accounting

## Overview

moveCostCenterHierarchyNode relocates an existing node to a different parent within the same cost center hierarchy. The move must not introduce a circular reference in the hierarchy tree structure. This enables reorganization of the cost center grouping structure without recreating nodes.

## Business Rules

- Node must exist
- New parent node must exist within the same hierarchy
- Node cannot be moved to itself as parent (no self-referencing)
- Move must not create a circular reference (the new parent cannot be a descendant of the node being moved)
- All child nodes and assigned cost centers move with the node
- Emits an audit event recording the move and acting user

## Process Flow

```mermaid
flowchart TD
    A[Receive move hierarchy node request] --> B{Node exists?}
    B -->|No| C[Return error: NODE_NOT_FOUND]
    B -->|Yes| D{New parent node exists?}
    D -->|No| E[Return error: PARENT_NODE_NOT_FOUND]
    D -->|Yes| F{Self-referencing?}
    F -->|Yes| G[Return error: SELF_REFERENCE]
    F -->|No| H{Circular reference?}
    H -->|Yes| I[Return error: CIRCULAR_REFERENCE]
    H -->|No| J[Move node to new parent]
    J --> K[Emit audit event]
    K --> L[Return moved node]
```

## External Dependencies

- None

## Error Scenarios

- **NODE_NOT_FOUND**: Hierarchy node with the specified ID does not exist
- **PARENT_NODE_NOT_FOUND**: Referenced parent node does not exist within the hierarchy
- **SELF_REFERENCE**: Node cannot reference itself as its parent
- **CIRCULAR_REFERENCE**: Operation would introduce a circular reference in the hierarchy

## Test Cases

- returns error for self-reference
- returns error when node does not exist
- returns error when new parent is not in same hierarchy
- returns error for circular reference (moving parent under its child)
- moves node to new parent successfully
- updates level based on new parent level
