# ValidateAllocationCycle

## Permission Scope

accounting

## Overview

validateAllocationCycle transitions an allocation cycle from DRAFT status to VALIDATED status. Validation verifies that the cycle has at least one allocation rule and that receiver percentages sum to exactly 100% for each sender. Only DRAFT cycles can be validated.

## Business Rules

- Allocation cycle must exist
- Allocation cycle must be in DRAFT status to be validated
- Cycle must have at least one allocation rule
- Allocation rule percentages for each sender must sum to exactly 100%
- Percentage values must be positive (greater than zero)
- Upon validation, the cycle becomes eligible for execution
- Emits an audit event recording the status transition and acting user

## Process Flow

```mermaid
flowchart TD
    A[Receive validate allocation cycle request] --> B{Allocation cycle exists?}
    B -->|No| C[Return error: ALLOCATION_CYCLE_NOT_FOUND]
    B -->|Yes| D{Status is DRAFT?}
    D -->|No| E[Return error: INVALID_STATE]
    D -->|Yes| F{Has at least one allocation rule?}
    F -->|No| G[Return error: NO_ALLOCATION_RULES]
    F -->|Yes| P{All percentages positive?}
    P -->|No| Q[Return error: INVALID_PERCENTAGE]
    P -->|Yes| H{Percentages sum to 100% per sender?}
    H -->|No| I[Return error: INVALID_PERCENTAGE_SUM]
    H -->|Yes| J[Transition status from DRAFT to VALIDATED]
    J --> K[Emit audit event]
    K --> L[Return validated 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
- **NO_ALLOCATION_RULES**: Cycle has no allocation rules defined
- **INVALID_PERCENTAGE**: One or more percentage values are zero or negative
- **INVALID_PERCENTAGE_SUM**: Allocation rule percentages for one or more senders do not sum to exactly 100%

## Test Cases

- validates a DRAFT allocation cycle with valid rules transitioning it to VALIDATED status
- returns error when allocation cycle does not exist
- returns error when allocation cycle is not in DRAFT status
- returns error when cycle has no allocation rules
- returns error when any percentage is zero or negative
- returns error when percentages do not sum to 100% for a sender
- validates with multiple senders each summing to 100%
- emits audit event recording the status transition and acting user
