# CreateProfitCenter

## Permission Scope

accounting

## Overview

createProfitCenter establishes a new profit center in DRAFT status within the management accounting module. A profit center represents a discrete business segment for which profitability can be independently evaluated. It carries a company reference, a unique code within the company scope, a name, a required valid-from date, an optional valid-to date, an optional description, and an optional responsible person reference.

## Business Rules

- Profit center is always created in DRAFT status
- 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 `validFrom` date
- `validTo` is optional; when provided, it must be on or after the `validFrom` date
- `description` is optional and can be set on creation
- `responsiblePersonId` is optional and can be set on creation
- Profit centers are scoped to a company; profit 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 profit 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_PROFIT_CENTER_CODE]
    D -->|Yes| F{Name provided?}
    F -->|No| G[Return error: INVALID_NAME]
    F -->|Yes| H{validFrom provided?}
    H -->|No| I[Return error: VALID_FROM_REQUIRED]
    H -->|Yes| J{validTo >= validFrom when both set?}
    J -->|No| K[Return error: INVALID_VALIDITY_PERIOD]
    J -->|Yes| L[Create profit center in DRAFT status]
    L --> M[Emit audit event]
    M --> N[Return created profit 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_PROFIT_CENTER_CODE**: A profit center with the same code already exists within the company
- **INVALID_NAME**: Name is empty, whitespace-only, or not provided
- **VALID_FROM_REQUIRED**: validFrom date is required but not provided
- **INVALID_VALIDITY_PERIOD**: validFrom is after validTo

## Test Cases

- creates profit center in DRAFT status with required fields
- returns error when company does not exist
- returns error when company is not ACTIVE
- returns error when code already exists within the company
- returns error when name is missing
- returns error when validFrom is not provided
- returns error when validTo is before validFrom
- creates profit center with optional description
- creates profit center without validTo
- profit centers from different companies are isolated
- emits audit event recording acting user, timestamp, and initial field values
