# CreateCostCenterHierarchy

## Permission Scope

accounting

## Overview

createCostCenterHierarchy establishes a new cost center hierarchy within a company. The hierarchy provides the tree structure required for organizing cost centers into grouping nodes for hierarchical roll-up reporting. A hierarchy carries a name, version identifier, and company reference. Hierarchies are scoped to a company and must be established before cost centers can be created.

## Business Rules

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

## Process Flow

```mermaid
flowchart TD
    A[Receive create cost 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 cost 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

- returns error when company does not exist
- returns error when company is not ACTIVE
- returns error when name is empty
- returns error when name is whitespace only
- creates hierarchy with valid inputs
- emits audit event by calling insert
