# CreateAllocationRule

## Permission Scope

accounting

## Overview

createAllocationRule adds an allocation rule to a DRAFT allocation cycle. Each rule defines a sender cost center, one or more receiver cost objects (cost center, profit center, or internal order), and the allocation percentage for each receiver. The sender cannot also appear as a receiver within the same rule. Percentage values must be positive.

## Business Rules

- Allocation cycle must exist and be in DRAFT status
- Rules cannot be added to cycles in VALIDATED, EXECUTED, POSTED, or REVERSED status
- Requires a valid sender cost center reference
- Requires one or more valid receiver cost objects (cost center, profit center, or internal order)
- Sender cost center cannot also be a receiver within the same rule set
- Percentage values for each receiver must be positive (greater than zero)
- Emits an audit event recording the rule creation and acting user

## Process Flow

```mermaid
flowchart TD
    A[Receive create allocation rule 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{Sender cost center valid?}
    F -->|No| G[Return error: SENDER_NOT_FOUND]
    F -->|Yes| H{All receivers valid?}
    H -->|No| I[Return error: RECEIVER_NOT_FOUND]
    H -->|Yes| J{Sender appears as receiver?}
    J -->|Yes| K[Return error: SENDER_IS_RECEIVER]
    J -->|No| L{All percentages positive?}
    L -->|No| M[Return error: INVALID_PERCENTAGE]
    L -->|Yes| N[Create allocation rule]
    N --> O[Emit audit event]
    O --> P[Return created allocation rule]
```

## 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
- **SENDER_NOT_FOUND**: Referenced sender cost center does not exist
- **RECEIVER_NOT_FOUND**: One or more referenced receiver cost objects do not exist
- **SENDER_IS_RECEIVER**: Sender cost center appears as a receiver in the same rule
- **INVALID_PERCENTAGE**: One or more percentage values are zero or negative

## Test Cases

- adds an allocation rule to a DRAFT allocation cycle
- returns error when allocation cycle does not exist
- returns error when allocation cycle is not in DRAFT status
- returns error when sender cost center does not exist
- returns error when a receiver cost object does not exist
- returns error when sender appears as a receiver
- returns error when percentage value is zero or negative
- emits audit event recording the rule creation and acting user
