# README

## Overview

The Cash Management module imports bank statements and reconciles statement lines with posted AP and AR payment documents. Business settlement remains owned by Account Payable and Account Receivable: an IncomingPayment or OutgoingPayment allocates to due schedules in its source module, while Cash Management records which collection of bank statement lines and payments represents the same movement of funds.

Bank reconciliation follows a group-and-item model. `BankReconciliation` is an immutable confirmed group and `BankReconciliationItem` stores every participating source through `sourceType + sourceId`. The initial source set is deliberately limited to `BANK_STATEMENT_LINE`, `INCOMING_PAYMENT`, and `OUTGOING_PAYMENT`.

## Key Features

- Bank account master with actual-bank and optional incoming/outgoing clearing GL accounts
- Balanced bank statement import with positive line amounts and explicit CREDIT/DEBIT direction
- **[Bank Reconciliation](docs/feature/bank-reconciliation.md)** — Manual 1:1, 1:N, N:1, and N:M reconciliation through one group header and common item table
- Materialized statement-line `reconciliationStatus` and `currentBankReconciliationId` for current-state reads
- Whole-line reconciliation with immutable reconciliation and reversal history
- Typed runtime validation of polymorphic AP/AR payment references through source-module queries
- Direct accounting with no reconciliation journal and indirect accounting with bank-to-clearing transfer
- Immutable reversal groups that restore source unreconciled amounts and reverse indirect accounting

## Module Scope

### In Scope

- BankAccount, BankStatement, and BankStatementLine
- IncomingPayment and OutgoingPayment reconciliation
- Manual confirmed reconciliation and reversal
- Same-company, same-currency, same-bank-account validation
- Direct and clearing-account payment recognition

### Out of Scope

- Automatic matching and posting rules
- Generic GL open-item clearing
- Cash transactions unrelated to AP/AR
- Payment-provider payout modeling
- Payroll, bank transfer, journal-line, and external-transaction reconciliation sources
- Bank connectivity and statement-file parsing

### Scope Decision Rationale

The first version stops at AP/AR payments because these are the business documents already capable of explaining customer and supplier cash movements. Generic cash transactions, GL journal matching, and provider-specific settlement add different business meanings and should be introduced only with their owning modules. Keeping `sourceType + sourceId` in the reconciliation item preserves that extension path without adding speculative tables now.

## Module Dependencies

- `organization` — Company validation and scope
- `primitives` — Currency validation
- `coa-management` — Bank and clearing GL account validation
- `account-receivable` — IncomingPayment lookup
- `account-payable` — OutgoingPayment lookup
- `financial-accounting` — Indirect reconciliation journal creation and posting