# MoveTaxonomyNode

## Permission Scope

taxonomy

## Overview

moveTaxonomyNode reparents a taxonomy node by changing its parent reference. The node and all its descendants move together, preserving the subtree structure and all item assignments. This supports taxonomy restructuring scenarios such as promoting a branch to root level or reorganizing classification hierarchies.

Moving to a null parent promotes the node to a root node.

## Business Rules

- Target node must exist in the system
- New parent node must exist when specified (null for root promotion)
- A node cannot be moved under itself or any of its descendants (circular reference prevention)
- All child nodes and their item assignments are preserved during the move
- The move must not cause the tree to exceed the configurable maximum depth
- Node code and item assignments are unchanged by the move

## Process Flow

```mermaid
flowchart TD
    A[Receive move request] --> B{Node exists?}
    B -->|No| C[Return error: not found]
    B -->|Yes| D{New parent specified?}
    D -->|Yes| E{New parent exists?}
    E -->|No| F[Return error: parent not found]
    E -->|Yes| G{New parent is descendant of node?}
    G -->|Yes| H[Return error: circular reference]
    G -->|No| I{Depth limit exceeded?}
    I -->|Yes| J[Return error: max depth exceeded]
    I -->|No| K[Update parent reference]
    D -->|No/null| K[Promote to root]
    K --> L[Return moved node]
```

## External Dependencies

- None

## Error Scenarios

- **NODE_NOT_FOUND**: Specified taxonomy node ID does not exist
- **PARENT_NODE_NOT_FOUND**: Specified parent node ID does not exist
- **CIRCULAR_REFERENCE**: New parent is the node itself or one of its descendants
- **MAX_DEPTH_EXCEEDED**: Operation would cause the taxonomy subtree to exceed the maximum depth limit

## Test Cases

- returns error when node does not exist
- returns error when new parent does not exist
- returns error when moving node under itself
- returns error when moving node under its descendant
- promotes node to root by setting parent to null
- moves node to different parent
- returns error when subtree depth + new parent depth exceeds maxDepth