# ExecuteAllocationCycle

## Permission Scope

accounting

## Overview

executeAllocationCycle runs the allocation calculations for a VALIDATED cycle. In ACTUAL mode, it transitions the cycle from VALIDATED to EXECUTED and creates immutable AllocationResult records for each sender-receiver-amount combination. In TEST_RUN mode, it generates preview results without changing the cycle status, allowing controllers to review projected allocations before committing.

## Business Rules

- Allocation cycle must exist
- Allocation cycle must be in VALIDATED status to be executed
- Supports two execution modes: ACTUAL and TEST_RUN
- ACTUAL mode transitions status from VALIDATED to EXECUTED
- ACTUAL mode creates immutable AllocationResult records for each sender-receiver-amount combination
- AllocationResult records cannot be modified or deleted after creation
- Each AllocationResult references the allocation cycle, sender, receiver, allocated amount, and cost element
- TEST_RUN mode generates preview results without changing cycle status
- Emits an audit event recording the execution and acting user (ACTUAL mode only)

## Process Flow

```mermaid
flowchart TD
    A[Receive execute allocation cycle request] --> B{Allocation cycle exists?}
    B -->|No| C[Return error: ALLOCATION_CYCLE_NOT_FOUND]
    B -->|Yes| D{Status is VALIDATED?}
    D -->|No| E[Return error: INVALID_STATE]
    D -->|Yes| F{Execution mode?}
    F -->|TEST_RUN| G[Calculate allocation amounts]
    G --> H[Return preview results without status change]
    F -->|ACTUAL| I[Calculate allocation amounts]
    I --> J[Create immutable AllocationResult records]
    J --> K[Transition status from VALIDATED to EXECUTED]
    K --> L[Emit audit event]
    L --> M[Return execution results]
```

## External Dependencies

- None

## Error Scenarios

- **ALLOCATION_CYCLE_NOT_FOUND**: Allocation cycle with the specified ID does not exist
- **INVALID_STATE**: Target entity is not in a valid status for this operation

## Test Cases

- executes a VALIDATED allocation cycle in ACTUAL mode transitioning it to EXECUTED status
- creates AllocationResult records in ACTUAL mode
- executes in TEST_RUN mode returning preview results without status change
- returns error when allocation cycle does not exist
- returns error when allocation cycle is not in VALIDATED status
- each AllocationResult references cycle, sender, receiver, amount, and cost element
- emits audit event recording the execution and acting user
