# CreateInternalOrder

## Permission Scope

accounting

## Overview

createInternalOrder establishes a new internal order in CREATED status. An internal order is a temporary cost collector for tracking expenses associated with specific short-to-medium-term activities such as projects, marketing campaigns, and R&D initiatives. It requires a unique order number within the company, an order type, a description, a responsible person, a responsible cost center within the same company, and a company reference. Optional fields include validity dates and a budget reference.

## Business Rules

- Internal order is always created in CREATED status
- Requires a valid `companyId` referencing an ACTIVE company from the organization module
- Requires an `orderNumber` that is unique within the company scope
- Requires an `orderType` of OVERHEAD, INVESTMENT, or ACCRUAL
- Requires a `description`
- Requires a `responsiblePersonId`
- Requires a `costCenterId` referencing a valid cost center within the same company
- `validFrom` and `validTo` are optional; when both are provided, validFrom must precede validTo
- Budget assignment is optional; when assigned, the budget must exist and belong to the same company
- Internal orders are scoped to a company; orders 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 internal order request] --> B{Company exists and is ACTIVE?}
    B -->|No| C[Return error: COMPANY_NOT_FOUND]
    B -->|Yes| D{Order number unique within company?}
    D -->|No| E[Return error: DUPLICATE_ORDER_NUMBER]
    D -->|Yes| F{Valid order type?}
    F -->|No| G[Return error: INVALID_ORDER_TYPE]
    F -->|Yes| H{Description provided?}
    H -->|No| I[Return error: DESCRIPTION_REQUIRED]
    H -->|Yes| J{Responsible person provided?}
    J -->|No| K[Return error: RESPONSIBLE_PERSON_REQUIRED]
    J -->|Yes| L{Cost center exists in same company?}
    L -->|No| M[Return error: COST_CENTER_NOT_FOUND]
    L -->|Yes| N{validFrom <= validTo when both set?}
    N -->|No| O[Return error: INVALID_VALIDITY_PERIOD]
    N -->|Yes| P[Create internal order in CREATED status]
    P --> Q[Emit audit event]
    Q --> R[Return created internal order]
```

## 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_ORDER_NUMBER**: An internal order with the same order number already exists within the company
- **INVALID_ORDER_TYPE**: Order type is not one of the recognized values (OVERHEAD, INVESTMENT, ACCRUAL)
- **DESCRIPTION_REQUIRED**: Description is missing or empty
- **RESPONSIBLE_PERSON_REQUIRED**: Responsible person reference is missing
- **COST_CENTER_NOT_FOUND**: Referenced cost center does not exist or does not belong to the same company
- **INVALID_VALIDITY_PERIOD**: validFrom is after validTo

## Test Cases

- creates internal order in CREATED status with required fields
- returns error when company does not exist
- returns error when company is not ACTIVE
- returns error when order number already exists within the company
- returns error when order type is invalid
- returns error when description is missing
- returns error when responsible person is missing
- returns error when cost center does not exist
- returns error when cost center belongs to a different company
- returns error when validFrom is after validTo
- creates internal order with optional validity dates
- internal orders from different companies are isolated
- emits audit event recording acting user, timestamp, and initial field values
