# CreateCostCenter

## Permission Scope

accounting

## Overview

createCostCenter establishes a new cost center within a company. A cost center is a responsibility area that accumulates overhead costs for management accounting reporting. It requires a unique code within the company, a name, a category, a reference to a hierarchy node within the same company, and a valid-from date. Cost centers serve as the primary receiver for overhead costs and are foundational cost objects for allocation, budgeting, and variance analysis.

## Business Rules

- Requires a valid `companyId` referencing an ACTIVE company from the organization module
- Requires a `code` that is unique within the company scope
- Requires a `name`
- Requires a `category` from a defined set: overhead, production, administration, sales, or research
- Requires a `hierarchyNodeId` referencing an existing node within the same company's cost center hierarchy
- A cost center hierarchy must exist before cost centers can be created
- Requires a `validFrom` date
- `validTo` is optional; when provided, it must be on or after the `validFrom` date
- `responsiblePersonId` is optional
- `departmentId` is optional (informational mapping to the organization module)
- Cost centers are scoped to a company; cost centers from different companies are fully isolated
- Emits an audit event recording the acting user, timestamp, and initial field values

## Process Flow

```mermaid
flowchart TD
    A[Receive create cost center request] --> B{Company exists and is ACTIVE?}
    B -->|No| C[Return error: COMPANY_NOT_FOUND]
    B -->|Yes| D{Code unique within company?}
    D -->|No| E[Return error: DUPLICATE_COST_CENTER_CODE]
    D -->|Yes| F{Valid category?}
    F -->|No| G[Return error: INVALID_CATEGORY]
    F -->|Yes| H{Hierarchy node exists in same company?}
    H -->|No| I[Return error: HIERARCHY_NODE_NOT_FOUND]
    H -->|Yes| J{validTo >= validFrom when both set?}
    J -->|No| K[Return error: INVALID_VALIDITY_PERIOD]
    J -->|Yes| L[Create cost center]
    L --> M[Emit audit event]
    M --> N[Return created cost center]
```

## 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
- **DUPLICATE_COST_CENTER_CODE**: A cost center with the same code already exists within the company
- **INVALID_CATEGORY**: Category is not one of the recognized values (overhead, production, administration, sales, research)
- **HIERARCHY_NODE_NOT_FOUND**: Referenced hierarchy node does not exist or does not belong to the same company
- **INVALID_VALIDITY_PERIOD**: validFrom is after validTo

## 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 code already exists within company
- returns error when category is invalid
- returns error when hierarchy node does not exist
- returns error when hierarchy node belongs to different company
- returns error when validTo is before validFrom
- creates cost center with valid inputs
- creates cost center without optional fields
