# CancelJournalEntry

## Permission Scope

journalEntry

## Overview

cancelJournalEntry transitions a DRAFT journal entry to CANCELLED without deleting the journal entry header or its prepared JournalLine rows. Cancelled entries have no ledger effect and cannot be posted, updated, or reversed. Posted entries must be reversed rather than cancelled because their JournalLine rows already form part of the ledger surface.

## Business Rules

- Journal entry must exist and be in DRAFT status
- Only DRAFT entries can be cancelled; POSTED entries cannot be cancelled
- Cancelling a DRAFT entry preserves its header and prepared lines for audit traceability
- Cancelled entries have no ledger effect and cannot be updated, posted, or reversed
- Posted entries must be reversed via reverseJournalEntry instead of cancelled

## Process Flow

```mermaid
flowchart TD
    A[Receive cancel 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 cancel non-draft entry]
    D -->|Yes| F[Set status to CANCELLED]
    F --> G[Return cancelled journal entry]
```

## External Dependencies

- None

## Error Scenarios

- **JOURNAL_ENTRY_NOT_FOUND**: Referenced journal entry does not exist
- **INVALID_STATUS_FOR_CANCEL**: Journal entry is not in DRAFT status; only DRAFT entries can be cancelled

## Test Cases

- returns error when journal entry does not exist
- returns error when journal entry is in POSTED status
- transitions DRAFT journal entry to CANCELLED without deleting lines