# InvalidateAllocationCycle

## Permission Scope

accounting

## Overview

invalidateAllocationCycle transitions an allocation cycle from VALIDATED status back to DRAFT status, allowing further editing of allocation rules. This enables corrections before execution.

## Business Rules

- Allocation cycle must exist
- Allocation cycle must be in VALIDATED status to be invalidated
- Invalidating a cycle in any other status is rejected as an invalid state transition
- Upon invalidation, rules can be added, modified, or removed again
- Emits an audit event recording the status transition and acting user

## Process Flow

```mermaid
flowchart TD
    A[Receive invalidate 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[Transition status from VALIDATED to DRAFT]
    F --> G[Emit audit event]
    G --> H[Return invalidated allocation cycle]
```

## 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

- invalidates a VALIDATED allocation cycle transitioning it to DRAFT status
- returns error when allocation cycle does not exist
- returns error when allocation cycle is in DRAFT status
- returns error when allocation cycle is in EXECUTED status
- returns error when allocation cycle is in POSTED status
- returns error when allocation cycle is in REVERSED status
- emits audit event recording the status transition and acting user
