# CreateProfitCenterHierarchyNode

## Permission Scope

accounting

## Overview

createProfitCenterHierarchyNode adds a new node to an existing profit center hierarchy. Nodes form a tree structure with parent-child relationships, supporting hierarchical roll-up profitability reporting. A root node must be created before child nodes can be added. The same structural rules as cost center hierarchy nodes apply.

## Business Rules

- Hierarchy must exist
- Parent node must exist when creating a child node (except for root node creation)
- A root node must be established before child nodes can be added
- A node cannot reference itself as its parent (no self-referencing)
- Creating a node must not introduce a circular reference in the hierarchy
- Node carries a name, sort order, and level attribute
- Emits an audit event recording the acting user, timestamp, and initial field values

## Process Flow

```mermaid
flowchart TD
    A[Receive create hierarchy node request] --> B{Hierarchy exists?}
    B -->|No| C[Return error: HIERARCHY_NOT_FOUND]
    B -->|Yes| D{Is root node creation?}
    D -->|Yes| E{Root node already exists?}
    E -->|Yes| F[Return error: DUPLICATE_ROOT_NODE]
    E -->|No| G[Create root node]
    D -->|No| H{Parent node exists?}
    H -->|No| I[Return error: PARENT_NODE_NOT_FOUND]
    H -->|Yes| J{Self-referencing?}
    J -->|Yes| K[Return error: SELF_REFERENCE]
    J -->|No| L{Circular reference?}
    L -->|Yes| M[Return error: CIRCULAR_REFERENCE]
    L -->|No| N[Create child node under parent]
    G --> O[Emit audit event]
    N --> O
    O --> P[Return created node]
```

## External Dependencies

- None

## Error Scenarios

- **HIERARCHY_NOT_FOUND**: Referenced hierarchy does not exist
- **PARENT_NODE_NOT_FOUND**: Referenced parent node does not exist within the hierarchy
- **DUPLICATE_ROOT_NODE**: A root node already exists in this hierarchy
- **SELF_REFERENCE**: Node cannot reference itself as its parent
- **CIRCULAR_REFERENCE**: Operation would introduce a circular reference in the hierarchy

## Test Cases

- creates a root node in an existing hierarchy
- creates a child node under an existing parent node
- returns error when hierarchy does not exist
- returns error when parent node does not exist
- returns error when attempting to create a second root node
- returns error when node references itself as parent
- returns error when node would create a circular reference
- emits audit event recording acting user, timestamp, and initial field values
