# RecordCommitment

## Permission Scope

accounting

## Overview

recordCommitment records a purchase order commitment against a specific cost element, cost object, and accounting period. Commitments reduce budget availability by reserving funds for outstanding purchase orders that have not yet been invoiced. This is triggered when a purchase order confirmation event is received.

## Business Rules

- Requires a valid cost element reference
- Requires a valid cost object reference (cost center, profit center, or internal order)
- Requires a valid accounting period reference
- Requires a positive commitment amount
- Commitment reduces budget availability using the formula: Available = Budget - (Actual + Commitments + Encumbrances)
- Commitment is associated with a purchase order reference for traceability
- An ACTIVE budget must exist for the cost object to record commitments against
- Emits an audit event recording the commitment and acting user

## Process Flow

```mermaid
flowchart TD
    A[Receive record commitment request] --> B{Cost element exists?}
    B -->|No| C[Return error: COST_ELEMENT_NOT_FOUND]
    B -->|Yes| D{Cost object exists?}
    D -->|No| E[Return error: COST_OBJECT_NOT_FOUND]
    D -->|Yes| F{Accounting period exists?}
    F -->|No| G[Return error: ACCOUNTING_PERIOD_NOT_FOUND]
    F -->|Yes| H{Commitment amount positive?}
    H -->|No| I[Return error: INVALID_COMMITMENT_AMOUNT]
    H -->|Yes| J{Active budget exists for cost object?}
    J -->|No| K[Return error: NO_ACTIVE_BUDGET]
    J -->|Yes| L[Record commitment amount]
    L --> M[Reduce budget availability]
    M --> N[Emit audit event]
    N --> O[Return recorded commitment]
```

## External Dependencies

- [finance-ledger::getAccountingPeriod](../../../finance-ledger/docs/queries/GetAccountingPeriod.md) — Validates that the referenced accounting period exists

## Error Scenarios

- **COST_ELEMENT_NOT_FOUND**: Referenced cost element does not exist
- **COST_OBJECT_NOT_FOUND**: Referenced cost object (cost center, profit center, or internal order) does not exist
- **ACCOUNTING_PERIOD_NOT_FOUND**: Referenced accounting period does not exist
- **INVALID_COMMITMENT_AMOUNT**: Commitment amount is not positive
- **NO_ACTIVE_BUDGET**: No active budget exists for the specified cost object

## Test Cases

- records a commitment against a cost element, cost object, and period
- reduces budget availability by the commitment amount
- returns error when cost element does not exist
- returns error when cost object does not exist
- returns error when accounting period does not exist
- returns error when commitment amount is zero or negative
- returns error when no active budget exists for the cost object
- associates commitment with purchase order reference
- emits audit event recording the commitment and acting user
