# CreateProductCategory

## Permission Scope

productCatalog

## Overview

createProductCategory creates a new category node in the hierarchical product category tree. Categories can be root nodes (no parent) or child nodes referencing an existing parent. The category tree is used to classify products for commercial and marketing purposes.

## Business Rules

- Category code is required, must be globally unique, and is immutable after creation
- Category name is required and must be non-empty
- Parent ID is optional — omitting it creates a root category
- If parent ID is provided, the parent category must exist
- Creating a child category must not exceed the configurable maximum tree depth
- Categories are created without any product assignments

## Process Flow

```mermaid
flowchart TD
    A[Receive create request] --> B{Code provided and unique?}
    B -->|No| C[Return error: DUPLICATE_CODE or MISSING_REQUIRED_FIELD]
    B -->|Yes| D{Name provided?}
    D -->|No| E[Return error: MISSING_REQUIRED_FIELD]
    D -->|Yes| F{Parent ID provided?}
    F -->|No| G[Create as root category]
    F -->|Yes| H{Parent exists?}
    H -->|No| I[Return error: PARENT_NOT_FOUND]
    H -->|Yes| J{Depth within limit?}
    J -->|No| K[Return error: MAX_DEPTH_EXCEEDED]
    J -->|Yes| L[Create as child category]
    G --> M[Return created category]
    L --> M
```

## External Dependencies

- None

## Error Scenarios

- **DUPLICATE_CODE**: An entity with the same code already exists within the scope
- **MISSING_REQUIRED_FIELD**: One or more required fields are missing or empty
- **PARENT_NOT_FOUND**: Specified parent category ID does not exist
- **MAX_DEPTH_EXCEEDED**: Operation would cause the category subtree to exceed the maximum depth limit

## Test Cases

- should return MissingRequiredFieldError when code is empty
- should return MissingRequiredFieldError when name is empty
- should return DuplicateCodeError when code already exists
- should return ParentNotFoundError when parent does not exist
- should return MaxDepthExceededError when depth exceeds maxDepth
- should create a root category when no parentId is provided
- should create a child category when parentId is provided
