# UpdateJournalEntry

## Permission Scope

journalEntry

## Overview

updateJournalEntry modifies the header fields of an existing journal entry that is in DRAFT status. Updatable fields include description, source document reference, entry date, and reference number. Posted and reversed entries are immutable and cannot be updated. This command does not affect journal lines, which are managed via addJournalLine, updateJournalLine, and removeJournalLine.

## 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 and source document reference can be updated while in DRAFT status
- Emits an audit event recording previous and new field values, acting user, and timestamp

## 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[Update header fields]
    F --> G[Emit audit event]
    G --> H[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

## 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
- updates source document reference 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
- emits audit event recording previous and new field values and acting user
