# PostAllocationCycle

## Permission Scope

accounting

## Overview

postAllocationCycle transitions an allocation cycle from EXECUTED to POSTED status by creating journal entries through the finance-ledger module. For ASSESSMENT type allocations, journal entries use secondary cost elements. For DISTRIBUTION type allocations, journal entries preserve the original primary cost elements. The accounting period must be in OPEN or FUTURE_ENTERABLE status.

## Business Rules

- Allocation cycle must exist
- Allocation cycle must be in EXECUTED status to be posted
- Posting creates journal entries through the finance-ledger subledger integration
- Assessment-type allocations use secondary cost elements in generated journal entries
- Distribution-type allocations preserve original primary cost elements in generated journal entries
- The accounting period must be in OPEN or FUTURE_ENTERABLE status
- Posting to a CLOSED or PERMANENTLY_CLOSED period is rejected
- Journal entries reference the allocation cycle as the source document
- Transitions status from EXECUTED to POSTED
- Emits an audit event recording the status transition and acting user

## Process Flow

```mermaid
flowchart TD
    A[Receive post allocation cycle request] --> B{Allocation cycle exists?}
    B -->|No| C[Return error: ALLOCATION_CYCLE_NOT_FOUND]
    B -->|Yes| D{Status is EXECUTED?}
    D -->|No| E[Return error: INVALID_STATE]
    D -->|Yes| F{Accounting period is OPEN or FUTURE_ENTERABLE?}
    F -->|No| G[Return error: PERIOD_NOT_OPEN]
    F -->|Yes| H{Allocation type?}
    H -->|ASSESSMENT| I[Create journal entries with secondary cost elements]
    H -->|DISTRIBUTION| J[Create journal entries with primary cost elements]
    I --> K[Post journal entries via finance-ledger]
    J --> K
    K --> L[Transition status from EXECUTED to POSTED]
    L --> M[Emit audit event]
    M --> N[Return posted allocation cycle]
```

## External Dependencies

- [finance-ledger::getAccountingPeriod](../../../finance-ledger/docs/queries/GetAccountingPeriod.md) — Validates that the accounting period is in OPEN or FUTURE_ENTERABLE status
- [finance-ledger::createJournalEntry](../../../finance-ledger/docs/commands/CreateJournalEntry.md) — Creates journal entries for the allocation postings

## 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
- **PERIOD_NOT_OPEN**: Accounting period is not in OPEN or FUTURE_ENTERABLE status

## Test Cases

- posts an EXECUTED allocation cycle transitioning it to POSTED status
- returns error when allocation cycle does not exist
- returns error when allocation cycle is not in EXECUTED status
- returns error when accounting period is CLOSED
- returns error when accounting period is PERMANENTLY_CLOSED
- emits audit event recording the status transition and acting user
