# CreateProfitCenterHierarchy

## Permission Scope

accounting

## Overview

createProfitCenterHierarchy establishes a new profit center hierarchy within a company. The hierarchy provides the tree structure required for organizing profit centers into grouping nodes for hierarchical roll-up profitability reporting. A hierarchy carries a name and company reference. Hierarchies are scoped to a company.

## Business Rules

- Requires a valid `companyId` referencing an ACTIVE company from the organization module
- Requires a `name` for the hierarchy
- Hierarchy is scoped to a company; hierarchies from different companies are fully isolated
- A company can have multiple profit center hierarchies
- Emits an audit event recording the acting user, timestamp, and initial field values

## Process Flow

```mermaid
flowchart TD
    A[Receive create profit center hierarchy request] --> B{Company exists and is ACTIVE?}
    B -->|No| C[Return error: COMPANY_NOT_FOUND]
    B -->|Yes| D{Name provided?}
    D -->|No| E[Return error: INVALID_NAME]
    D -->|Yes| F[Create profit center hierarchy]
    F --> G[Emit audit event]
    G --> H[Return created hierarchy]
```

## External Dependencies

- [organization::getCompany](../../../organization/docs/queries/GetCompany.md) — Validates that the referenced company exists and is ACTIVE

## Error Scenarios

- **COMPANY_NOT_FOUND**: Referenced company does not exist or is not in ACTIVE status
- **INVALID_NAME**: Name is empty, whitespace-only, or not provided

## Test Cases

- creates a profit center hierarchy with name and company reference
- returns error when company does not exist
- returns error when company is not ACTIVE
- returns error when name is missing
- hierarchies from different companies are isolated
- a company can have multiple profit center hierarchies
- emits audit event recording acting user, timestamp, and initial field values
