# CorrectAccountPayableDocument

## Permission Scope

accountPayableDocument

## Overview

correctAccountPayableDocument creates a DRAFT AP correction document for a POSTED AP document. It does not mutate the corrected AP document or its lines. The correction document records a header-level `correctionOfId`, each correction line records `correctionOfLineId` and `correctionType`, and each correction distribution can record `correctionOfDistributionLineId` when the correction targets a specific accounting or cost allocation. This supports Oracle-style price, quantity, and amount corrections while keeping the correction document as a normal AccountPayableDocument that is later registered and posted.

## Business Rules

- Only POSTED AP documents can be corrected
- A correction document is created in DRAFT status
- The correction document inherits company, supplier, and currency from the corrected AP document
- The correction document stores `correctionOfId` on its AccountPayableDocument header
- Each correction line must reference a line on the corrected AP document through `correctionOfLineId`
- Each correction line must declare `correctionType` as PRICE, QUANTITY, or AMOUNT
- PRICE and QUANTITY corrections can only target purchase-order sourced AP lines
- AMOUNT corrections can target purchase-order sourced or amount-only AP lines
- Purchase-order sourced correction lines keep the same purchase order line context as the corrected AP line; supplied source fields must match the corrected line
- A correction distribution may reference a distribution on the corrected line through `correctionOfDistributionLineId`
- Distribution correction references must belong to the corrected line referenced by the correction line
- Amounts remain positive; documentType determines whether the correction increases or decreases AP exposure
- CREDIT_MEMO correction documents reduce AP exposure
- INVOICE correction documents increase AP exposure when `correctionOfId` marks them as correction documents rather than normal invoices
- A full offset of a posted AP invoice is represented as a CREDIT_MEMO correction document for the full invoice amount; it does not change the corrected document's lifecycle status
- Tax, expense, and other posting distributions are supplied by the correction document itself; correction links provide provenance and validation, not posting accounts

## Process Flow

```mermaid
flowchart TD
    A[Receive correct AP document request] --> B{Corrected document exists?}
    B -->|No| C[Return error: AP document not found]
    B -->|Yes| D{Corrected document is POSTED?}
    D -->|No| E[Return error: invalid AP document status]
    D -->|Yes| F{Corrected lines belong to document?}
    F -->|No| G[Return error: AP document line not found]
    F -->|Yes| H{Correction types valid for source lines?}
    H -->|No| I[Return error: line source inconsistent]
    H -->|Yes| J{Distribution correction refs valid?}
    J -->|No| K[Return error: AP distribution line not found]
    J -->|Yes| L[Create DRAFT AP correction document]
    L --> M[Return correction document]
```

## External Dependencies

- [listAccounts](../../../coa-management/docs/query/ListAccounts.md) - Validates payable control and distribution accounts

## Error Scenarios

- **AP_DOCUMENT_NOT_FOUND**: Corrected AP document does not exist
- **AP_INVALID_DOCUMENT_STATUS**: Corrected AP document is not POSTED
- **AP_DOCUMENT_LINE_NOT_FOUND**: A correction line does not reference a line on the corrected AP document
- **AP_DISTRIBUTION_LINE_NOT_FOUND**: A correction distribution does not reference a distribution on the corrected line
- **AP_LINE_SOURCE_INCONSISTENT**: PRICE or QUANTITY correction targets an amount-only line, or line source fields are inconsistent
- **AP_MINIMUM_LINES_NOT_MET**: Correction document must have at least one line and one distribution
- **AP_INVALID_AMOUNT**: Correction document, line, quantity, unit price, or distribution amount is not positive
- **AP_LINE_TOTAL_MISMATCH**: Line gross total or distribution total does not match the correction document total
- **ACCOUNT_NOT_FOUND**: Referenced payable control or distribution GL account does not exist
- **ACCOUNT_INACTIVE**: Referenced payable control or distribution GL account is not ACTIVE

## Test Cases

- creates a DRAFT correction document with line and distribution correction links
- creates an INVOICE correction for an AP-increasing correction
- returns error when the corrected document is not POSTED
- returns error when a correction line references a line outside the corrected document
- returns error when a correction distribution references another line
- returns error when a price correction targets a non-PO source line
- returns error when a correction line changes the original purchase order source
- returns missing account errors through the shared AP document validation
- returns inactive account errors through the shared AP document validation
