# UpdateJournalEntry

## Permission Scope

journalEntry

## Overview

updateJournalEntry replaces the editable draft journal document. Updatable header fields include description, structured source document reference, entry date, and reference number, and the command requires the full replacement set of prepared journal lines under the same parent draft document. Posted and reversed entries are immutable and cannot be updated.

## Business Rules

- Journal entry must exist and be in DRAFT status
- Only DRAFT entries can be updated; POSTED and REVERSED entries are immutable
- Entry date can be updated while in DRAFT status
- Description, source document type, and source document ID can be updated while in DRAFT status
- At least two prepared journal lines are required on every update
- Prepared journal lines are replaced as a full set through this parent entry update
- Each journal line must reference an existing GL account
- Each journal line must specify either a debit amount or a credit amount, not both
- Journal line amounts are recorded in the company's base currency; multi-currency conversion is outside the current scope

## Process Flow

```mermaid
flowchart TD
    A[Receive update journal entry 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 modify non-draft entry]
    D -->|Yes| F{Reference number changing?}
    F -->|Yes| G{Reference number unique?}
    G -->|No| H[Return error: duplicate reference number]
    G -->|Yes| I[Apply header patch]
    F -->|No| I
    I --> J{Replacement lines valid?}
    J -->|No| K[Return line validation error]
    J -->|Yes| L[Replace prepared lines]
    L --> M[Return updated journal entry]
```

## External Dependencies

- None

## Error Scenarios

- **JOURNAL_ENTRY_NOT_FOUND**: Referenced journal entry does not exist
- **INVALID_STATUS_FOR_UPDATE**: Journal entry is not in DRAFT status; POSTED and REVERSED entries cannot be modified
- **DUPLICATE_REFERENCE_NUMBER**: A journal entry with the same reference number already exists within the company
- **MINIMUM_LINES_NOT_MET**: Journal entry has fewer than two journal lines
- **ACCOUNT_NOT_FOUND**: Referenced GL account does not exist
- **INVALID_DEBIT_CREDIT**: Debit/credit values violate constraints

## 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
- updates description on a DRAFT journal entry and replaces lines
- updates source document on a DRAFT journal entry
- updates entry date on a DRAFT journal entry
- updates reference number on a DRAFT journal entry with uniqueness check
- returns error when updated reference number already exists
- returns error when replacement lines are missing
- returns error when a replacement line account does not exist
- returns error when a replacement line has invalid debit and credit values
