# AddJournalLine

## Permission Scope

journalEntry

## Overview

addJournalLine adds a new line item to a DRAFT journal entry. Each journal line references a GL account (from coa-management) and specifies either a debit amount or a credit amount. For multi-currency transactions, the line can include a currency code and exchange rate; otherwise it defaults to the company's functional currency with an exchange rate of 1.0. An optional line-level description can be provided for additional detail.

## Business Rules

- Journal entry must exist and be in DRAFT status
- Lines cannot be added to POSTED or REVERSED entries
- Each line must reference a valid GL account ID from coa-management
- Each line must specify either a debit amount or a credit amount (not both, and not zero for both)
- Debit and credit amounts must be positive values
- For multi-currency lines, a currency code and exchange rate must be specified
- Lines without an explicit currency default to the company's functional currency with exchange rate 1.0
- The functional currency amount is computed as the foreign amount multiplied by the exchange rate
- Line-level description is optional
- Emits an audit event recording the line addition, acting user, and timestamp

## Process Flow

```mermaid
flowchart TD
    A[Receive add journal line request] --> B{Journal entry exists?}
    B -->|No| C[Return error: journal entry not found]
    B -->|Yes| D{Entry status is DRAFT?}
    D -->|No| E[Return error: cannot add lines to non-draft entry]
    D -->|Yes| F{Valid GL account reference?}
    F -->|No| G[Return error: invalid account]
    F -->|Yes| H{Debit or credit specified correctly?}
    H -->|No| I[Return error: invalid debit/credit]
    H -->|Yes| J{Multi-currency?}
    J -->|Yes| K[Validate currency and exchange rate]
    K --> L{Currency valid?}
    L -->|No| M[Return error: invalid currency]
    L -->|Yes| N[Compute functional currency amount]
    J -->|No| N[Use functional currency defaults]
    N --> O[Create journal line]
    O --> P[Emit audit event]
    P --> Q[Return created journal line]
```

## External Dependencies

- [coa-management::getAccount](../../../coa-management/docs/queries/GetAccount.md) - Validates that the referenced GL account exists
- [primitives::getCurrency](../../../primitives/docs/queries/GetCurrency.md) - Validates that the referenced currency exists and is active (for multi-currency lines)

## Error Scenarios

- **JOURNAL_ENTRY_NOT_FOUND**: Referenced journal entry does not exist
- **INVALID_STATUS_FOR_LINE_ADD**: Journal entry is not in DRAFT status
- **ACCOUNT_NOT_FOUND**: Referenced GL account does not exist
- **INVALID_DEBIT_CREDIT**: Debit/credit values violate constraints (both specified, both zero, or negative)
- **CURRENCY_NOT_FOUND**: Referenced currency does not exist or is not active

## Test Cases

- returns error when journal entry does not exist
- returns error when journal entry is in POSTED status
- returns error when journal entry is in REVERSED status
- returns error when GL account does not exist
- returns error when GL account is not active
- returns error when both debit and credit amounts are specified
- returns error when both debit and credit amounts are zero
- returns error when debit amount is negative
- returns error when credit amount is negative
- returns error when currency does not exist for multi-currency line
- adds journal line with debit amount to DRAFT entry
- adds journal line with credit amount to DRAFT entry
- adds multi-currency journal line with currency and exchange rate
- defaults to functional currency with exchange rate 1.0 when currency not specified
- computes functional currency amount as foreign amount multiplied by exchange rate
- adds journal line with optional description
- emits audit event recording line addition and acting user
