# ConsumeCommitment

## Permission Scope

accounting

## Overview

consumeCommitment reduces an existing commitment and increases the actual amount when goods are received or an invoice is matched against a purchase order. This reclassifies committed funds as actual expenditure, keeping budget availability unchanged for the consumed portion.

## Business Rules

- Commitment must exist for the specified cost element, cost object, and period
- Requires a positive consumption amount
- Consumption amount must not exceed the remaining commitment amount
- Reduces the commitment amount by the consumption amount
- Increases the actual amount by the consumption amount
- Budget availability remains unchanged for the consumed portion (commitment decreases, actual increases by the same amount)
- Emits an audit event recording the consumption and acting user

## Process Flow

```mermaid
flowchart TD
    A[Receive consume commitment request] --> B{Commitment exists?}
    B -->|No| C[Return error: COMMITMENT_NOT_FOUND]
    B -->|Yes| D{Consumption amount positive?}
    D -->|No| E[Return error: INVALID_CONSUMPTION_AMOUNT]
    D -->|Yes| F{Consumption amount <= remaining commitment?}
    F -->|No| G[Return error: CONSUMPTION_EXCEEDS_COMMITMENT]
    F -->|Yes| H[Reduce commitment by consumption amount]
    H --> I[Increase actual by consumption amount]
    I --> J[Emit audit event]
    J --> K[Return updated commitment]
```

## External Dependencies

- None

## Error Scenarios

- **COMMITMENT_NOT_FOUND**: No commitment exists for the specified cost element, cost object, and period
- **INVALID_CONSUMPTION_AMOUNT**: Consumption amount is not positive
- **CONSUMPTION_EXCEEDS_COMMITMENT**: Consumption amount exceeds the remaining commitment amount

## Test Cases

- consumes a portion of an existing commitment
- reduces commitment amount by the consumption amount
- increases actual amount by the consumption amount
- budget availability remains unchanged for the consumed portion
- returns error when commitment does not exist
- returns error when consumption amount is zero or negative
- returns error when consumption amount exceeds remaining commitment
- fully consumes a commitment when consumption equals remaining amount
- emits audit event recording the consumption and acting user
