# ConvertAmount

## Overview

ConvertAmount transforms a monetary amount from one currency to another using the applicable exchange rate for a given date. The function looks up the most recent exchange rate on or before the specified date and applies it to calculate the converted amount. The result is rounded according to the target currency's decimal precision.

This function supports multi-currency operations including transaction recording, financial reporting, and consolidation.

## Business Rules

- Source and target currencies must both be active
- Exchange rate lookup uses the most recent rate with effectiveDate <= conversionDate
- Calculation: `result = amount x exchangeRate`
- Result is rounded to the target currency's `decimalPlaces`
- Same currency conversion (e.g., USD to USD) returns the original amount with rate of 1.0
- If no direct rate exists, inverse rate may be calculated: `1 / reverseRate`
- Amount must be non-negative (zero is allowed)
- Forward rates are supported: if conversion date is in the future and a forward rate exists, it will be used

## Process Flow

```mermaid
flowchart TD
    A[Receive conversion request] --> B{Same currency?}
    B -->|Yes| C[Return original amount]
    B -->|No| D{Both currencies active?}
    D -->|No| E[Return error: inactive currency]
    D -->|Yes| F[Find rate for date]
    F --> G{Direct rate found?}
    G -->|Yes| H[Use direct rate]
    G -->|No| I{Inverse rate found?}
    I -->|Yes| J[Calculate inverse: 1/rate]
    I -->|No| K[Return error: no rate available]
    J --> H
    H --> L[Calculate: amount x rate]
    L --> M[Round to target decimal places]
    M --> N[Return converted amount]
```

## External Dependencies

- None

## Error Scenarios

- **INACTIVE_CURRENCY**: Referenced source or target currency is inactive
- **EXCHANGE_RATE_NOT_FOUND**: No rate found for the currency pair on or before the specified date
- **CURRENCY_NOT_FOUND**: Referenced currency does not exist

## Test Cases

- returns error when source currency doesn't exist
- returns error when target currency doesn't exist
- returns error when source currency is inactive
- returns error when target currency is inactive
- returns error when no exchange rate exists for the currency pair
- returns same amount when source and target are the same currency
- converts USD to EUR using direct rate
- uses inverse rate when no direct rate exists
- uses most recent rate on or before the conversion date
- rounds to target currency decimal places (JPY has 0)
- handles zero amount correctly