# README

<!-- This section should contain the following subsections in order: -->
<!-- 1. ## Overview (required) -->
<!-- 2. ## Key Features (required) -->
<!-- 3. ## Module Scope (required) -->
<!-- 4. ## Module Dependencies (required) -->

## Overview

The account-payable module owns payable-side operational accounting documents.
It captures vendor invoices and credit memos as AP documents before they are
posted to financial accounting, records outgoing payments, and owns the
AccountPayableSettlement allocations that consume or restore posted AP due
schedules. The module keeps payable document lifecycle, commercial AP lines,
AP-owned posting distributions, and operational AP settlement together. Posted
AP documents and outgoing payments are immutable; corrections are represented
by separate linked correction or reversal documents.

When an AP document or outgoing payment is posted, account-payable creates and
posts a balanced journal entry directly in `financial-accounting` in the same
transaction. The journal entry keeps source document references back to its AP
source.

## Key Features

- Account payable document lifecycle from draft through registration, posting, and cancellation
- Commercial AP document lines with weak source document references
- Line-level price, quantity, and amount corrections through separate correction documents
- AP distribution lines that become journal lines at posting
- Posting workflow that records source-referenced journal entries directly in financial accounting
- Outgoing payment lifecycle from editable draft through posting or pre-post cancellation
- Common AP settlement allocations against posted invoice and credit memo due schedules, with signed net payment calculation and OutgoingPayment as the initial source
- Posted outgoing payment reversal through a new immutable linked payment and opposite journal entry

## Module Scope

### In Scope

- Vendor and payable-side document headers for invoices and credit memos
- AP document line capture and AP-owned posting distributions
- AP correction documents for posted AP documents, with optional line and distribution correction links
- Registration and posting readiness validation
- Direct posting into financial accounting through source document references
- Full invoice offsets through posted credit memo correction documents
- Operational outgoing payment documents and AP-owned settlement allocation against posted invoice and credit memo due schedules
- Pre-post payment cancellation and post-payment reversal through a linked payment

### Out of Scope

- General ledger ownership, accounting period ownership, and journal lifecycle
- Chart of accounts and account governance, owned by `coa-management`
- Purchase order processing, goods receipt matching, and procurement workflows
- Payment approval, execution rails, bank connectivity, bank reconciliation, and cash management
- External accounting system delivery such as QBO Bill synchronization

### Scope Decision Rationale

AP documents are payable operational documents, not GL master records. Keeping
them in a separate module avoids overloading financial-accounting with vendor
bill lifecycle while still allowing AP posting to create immutable GL facts in
financial-accounting.

AccountPayableSettlement is likewise an operational AP allocation, not a
financial-accounting open-item clearing fact or a bank reconciliation record.
Future cash-management capabilities may reference AP source documents but must
not own or mutate AP settlements.

The boundary also leaves room for accounting output integrations. A future QBO
integration can translate AP document intent into a QBO Bill without forcing the
AP document itself to become a generic journal-entry interface.

## Module Dependencies

- `business-partner` - Payable counterparty references
- `coa-management` - Posting account references on AP distributions and outgoing payments
- `financial-accounting` - Accounting period lookup and direct journal entry posting
- `inventory` - Acquisition cost adjustment posting for purchase-order sourced lines at AP posting time
- `organization` - Company scope for AP documents and outgoing payments
- `primitives` - Currency references for AP documents and outgoing payments