From 012f4d9a3e8daf90d903e3cdafeb1eba5ef4221e Mon Sep 17 00:00:00 2001 From: Scott Pouliot Date: Fri, 19 Jun 2026 21:34:12 -0400 Subject: [PATCH] Document the JournalEntry single-source ledger refactor plan MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Captures the phased plan to make JournalEntry lines the single source of truth for all GL balances/reports, retiring the parallel re-derivation in LedgerService and FinancialReportService. Resolves the O2/O6/O7/O8 bug class structurally and folds in O9 (inventory capitalization) at Phase 5. Proposed only — not started. Co-Authored-By: Claude Opus 4.8 --- docs/ACCOUNTING_LEDGER_REFACTOR.md | 115 +++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 docs/ACCOUNTING_LEDGER_REFACTOR.md diff --git a/docs/ACCOUNTING_LEDGER_REFACTOR.md b/docs/ACCOUNTING_LEDGER_REFACTOR.md new file mode 100644 index 0000000..44a9e21 --- /dev/null +++ b/docs/ACCOUNTING_LEDGER_REFACTOR.md @@ -0,0 +1,115 @@ +# Accounting Ledger Refactor — Single Source of Truth + +> Status: **PROPOSED / not started.** This is a captured plan, not in-progress work. +> Companion to `docs/ACCOUNTING_AUDIT.md`. Resolves the O2/O6/O7/O8 bug *class* and the open +> finding **O9** (inventory capitalization). Do this when there's runway + a staging environment — +> it is not an emergency; after audit fixes O1–O8 the current books are correct. + +--- + +## Why + +Today every financial event's GL effect is encoded in **three** places: + +1. **`Account.CurrentBalance`** — updated live at each posting site via + `AccountBalanceService.DebitAsync/CreditAsync`. +2. **`LedgerService`** — re-derives each account's balance by reading *source documents* (Payments, + Invoices, Bills, InventoryTransactions, GiftCertificates, CreditMemos, …). Drives + `RecalculateAllAsync` and the Balance Reconciliation report. +3. **`FinancialReportService`** — *independently* re-derives P&L, Balance Sheet, and Trial Balance from + the same documents, with its own per-report logic (largely duplicated across the three reports). + +Adding a transaction type means hand-mirroring its debit and credit into all three engines, in the right +direction, in every report method. Missing one spot produced every finding in the audit: + +| Finding | Missed mirror | +|---|---| +| O2 | 4950 Sales Discounts absent from `LedgerService` → recalc wiped it | +| O6 | inventory-consumption COGS absent from both recompute engines | +| O7 | GC redemption's AR credit absent → **Trial Balance did not balance** | +| O8 | written-off payments filtered inconsistently between the two engines | + +These are one design flaw with four faces: **reports re-interpret documents instead of reading a ledger.** + +## Target + +The journal becomes the only representation of GL effect. The tables already exist +(`JournalEntry` + `JournalEntryLine`, with a `Posted` status). + +- **Every** financial event posts a balanced `JournalEntry` (DR == CR enforced once, centrally). +- `Account.CurrentBalance`, Trial Balance, Balance Sheet, P&L, and the recompute all derive from + **`JournalEntryLine` only** (plus each account's opening balance). +- Invoices/Payments/Bills remain *operational* records; they stop carrying implicit GL meaning that every + report must re-decode. + +Result: `LedgerService.GetAccountLedgerAsync` (~800 lines of per-document sections) collapses to +"sum the JE lines for this account in range." Trial Balance / Balance Sheet become straight per-account JE +aggregations. The special cases — `gcRedeemed`, `cmApplied`, refund splits, consumption COGS, discount +contra-revenue — all disappear because they are simply journal lines. + +## What changes in the code + +1. **One posting service:** `PostAsync(date, description, lines[])` — validates balanced, assigns the + `JE-YYMM-####` number, marks `Posted`, updates `CurrentBalance` from the lines. `AccountBalanceService` + becomes a thin wrapper over it. +2. **Convert every posting site** to build JE lines instead of ad-hoc Debit/Credit pairs: invoice create, + payment, deposit record/apply, refund, credit memo issue/apply/void, GC issue/redeem/void, bill, bill + payment, vendor credit, inventory consumption, write-off, sales-tax remittance, year-end close, + depreciation, Stripe. Many already call `DebitAsync`; mechanical but touches **every accounting + controller**. `InvoicesController.WriteOff` already posts a JE — copy that model everywhere. +3. **Edits/voids become reversing entries** (post an opposite JE), never mutate in place. +4. **Gut the re-derivation:** `LedgerService` → JE-only; `FinancialReportService` TB/BS/P&L → JE-only. + AR/AP **aging** and customer/vendor statements stay document-driven (they answer "which documents are + open," not "what is the GL balance"). The AR control account then auto-reconciles to the subledger + because both come from the same postings. + +## Migration of historical data + +- **(a) Replay** — re-run every historical document through the new posting logic to emit JEs. Most + faithful; must handle edits/voids in chronological order. Complex, higher risk. +- **(b) Conversion balances (recommended)** — snapshot each account's current `CurrentBalance` as a single + dated "opening balance" JE at a cutover date; only new events post JEs after that. This is how real + systems migrate. With ~7 companies it is the pragmatic, low-risk path: pre-cutover per-transaction GL + granularity is lost, but every balance is preserved exactly. + +## Phased plan (verifiable, not big-bang) + +- **Phase 0** — build `PostAsync` + balanced-entry invariant + unit tests. +- **Phase 1** — route all posting sites through it, creating JEs *alongside* existing behavior (no report + changes yet). The **Balance Reconciliation report is the regression harness** — it should show near-zero + drift everywhere once every event posts a JE. +- **Phase 2** — switch `LedgerService` to JE-only; confirm `RecalculateAllAsync` reproduces balances. +- **Phase 3** — switch `FinancialReportService` (TB/BS/P&L) to JE-only; reconcile each report per company + against the old numbers using the snapshot harness below. +- **Phase 4** — post conversion-balance JEs at the cutover date; delete the dead re-derivation code + (~1,000+ lines). +- **Phase 5** — decide **O9** (perpetual vs periodic inventory) and implement it as JE postings. Perpetual + falls out naturally: purchases DR Inventory, consumption DR COGS / CR Inventory (O6 already posts the + consumption half). This makes the Balance Sheet inventory line consistent with the Trial Balance / P&L. + +## Prerequisites before starting + +- A **report-snapshot/diff harness** to compare each company's P&L / Balance Sheet / Trial Balance before + vs after each phase (the safety net for "numbers shifting"). +- A **staging copy** of production data to run the cutover against first. +- A **decision on O9** (the inventory policy) — see `docs/ACCOUNTING_AUDIT.md`. + +## Honest assessment + +- **Effort:** the single biggest change in the accounting area — weeks, not hours, with careful per-company + verification. +- **Risk:** broad blast radius (every accounting controller); report numbers *will* shift slightly as they + become consistent (the point), so it needs per-company sign-off. +- **Optional:** after O1–O8 the current system is correct. The refactor buys *prevention* of this bug class, + a real audit trail, and ~1,500 fewer lines of parallel logic. Higher ROI the more accounting features you + keep adding. +- **Safe stopping point:** Phases 0–1 alone (post JEs everywhere, watch the reconciliation report) are + low-risk and immediately valuable. You can stop there and continue later. + +## What it fixes + +- Eliminates the O2/O6/O7/O8 bug class (one place to get each event right). +- Trial Balance balances by construction. +- Every balance is traceable to a journal entry (audit trail). +- Resolves **O9** as part of Phase 5. +- Turns the Balance Reconciliation report into a true integrity check rather than a drift detector.