PowderCoatingLogix/docs/ACCOUNTING_LEDGER_REFACTOR.md

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.