Table of Contents

#136 — Contacts' entire money side (Purchase/Sale ledger, You-Owe/They-Owe-You balances) is completely disconnected from the Finance mo (Resolved)

← Back to Manara Bugs · View issue #136 in MantisBT


Reported by: Khaled Tarabay on 2026-07-28T14:42:20+01:00
Assigned to: Claude
Resolved by: Claude on 2026-07-29T07:15:14+01:00
Severity: major
Priority: high
Reproducibility: always
Category: General

Description: Recording a Purchase or Sale on a contact, and fully settling it through the ledger's own “Pay” action, has zero effect anywhere else in Finance — it never creates an Expense, never creates a Payment, and never moves the Business Overview dashboard's TOTAL EXPENSES or NET LIQUIDITY figures, even though real money is being recorded as changing hands. Captured Business Overview's totals before touching anything (TOTAL EXPENSES $52,795.00, NET LIQUIDITY -$48,696.10), then created a fresh Supplier-role contact and recorded a real $250.00 Purchase against it — a purchase, per the app's own on-page copy, is “money you now owe” a supplier, which is by definition a company expense. Fully settling that $250.00 through the ledger's real “Pay” button (proven elsewhere in this audit to correctly zero the row's balance and flip it to Settled) produced no change whatsoever: TOTAL EXPENSES and NET LIQUIDITY read back exactly $52,795.00 and -$48,696.10, unchanged to the cent. The Expenses module's own list has no row for it, and the Payments module — despite the settle action being visually and functionally a “payment” — has no row for it either. This is the same underlying pattern as two already-documented bugs elsewhere in this engagement, BUG-P02 (“Prepaid” payment method never touches Customer Wallets) and BUG-R04 (a standalone Credit never touches Customer Wallets): a financial action that is internally self-consistent (the contact's own You-Owe/They-Owe-You figures were independently verified correct to the cent throughout this audit) but writes to nowhere else, making it invisible to the actual books the business runs on. The one thing that does work correctly is the Activity Log, which does record both the creation (Create Contact transaction #41 kind=purchase, amount=250.00) and the settlement (Update Contact transaction #29 payment=250.00) with full field-level detail — so there is a technical audit trail, it's just that none of the financial reporting surfaces read from it. The fix should route Contact ledger settlements through the same underlying mechanism Expenses and Payments already use — a settled Purchase should generate a real Expense entry (the same way Payroll's “Pay” already correctly posts to Expenses, per this engagement's HR audit), and a settled Sale should generate a real Payment entry — so that Business Overview, the Expenses list, and the Payments list all reflect money that the app itself says has moved.

Steps to Reproduce: Note Business Overview's TOTAL EXPENSES and NET LIQUIDITY figures (/dashboard). Create a Supplier-role contact, record a Purchase for a clean, easily-recognizable amount (e.g. $250.00). On that contact's Ledger, fill the SETTLE box with the full amount and click Pay — confirm the row now shows Settled. Reload Business Overview — TOTAL EXPENSES and NET LIQUIDITY are unchanged. Check /expenses and /payments — neither has a new row for this $250.00. This is the bug; expected is that settling a Contact ledger transaction produces a real Expense (for a Purchase) or Payment (for a Sale) that shows up everywhere the rest of the app's money already does.

Resolution: FIXED. What: settling a Contact ledger row (a Purchase you owe a supplier/provider, or a Sale a client owes you) moved real money but posted NOTHING to Finance — no Expense, no income — so Business Overview's Total Expenses and Net Liquidity, the Expenses list, etc. never reflected it. Same class as Payroll's payout (which DOES post an Expense) — the contact ledger just never got wired.

Where + how: - app/classes/Crm/ContactTransaction.php — recordPayment() is now transactional and posts a matching finance-ledger (transactions) row for the amount actually settled: a Purchase settlement → a DEBIT (money out / expense), a Sale collection → a CREDIT (money in). It locks the ledger row, clamps the payment to the remaining balance (so a raw over-pay posts only what actually applied, never the raw figure), and posts inside the SAME db transaction so a failed finance post rolls the settlement back. Mirrors how PayrollEntry::record() posts its expense. - WHY NOT the payments table (as the ticket suggested for a Sale): payments.invoice_id is NOT NULL and invoices.customer_id is NOT NULL — a Contact is neither an invoice nor a customer, so a “payment” with no invoice is structurally impossible and would be a lie in the invoice-collection ledger. The transactions ledger (debit=out, credit=in) is the app's real general-ledger primitive (it's exactly what the Expenses module is), so both directions post there. A settled Purchase and a collected Sale now both appear in the /expenses finance list. - Migration 067 (app/../database/migrations/067_contact_settlement_types.sql, folded into schema.sql, embedded in run-migrations.php now 004-007 + 011-067): two system transaction types, contact_purchase (debit, “Supplier Purchase”) and contact_sale (credit, “Client Sale”), so these settlements are their own categories in the finance breakdown (same pattern as the payroll/commission types). If the type is missing (pre-migration DB) the settlement throws and rolls back rather than silently losing the finance side again. - app/controllers/DashboardController.php — Net Liquidity is now money IN - money OUT = (invoice payments + credit-direction finance entries) - (debit expenses). Before, credits were counted nowhere, so a collected Sale (and, correctly, any Deposit/Adjustment credit) never moved the figure. The Financial Trends chart's net line was updated the same way (new Transaction::creditSeries()) so it stays consistent with the headline; the “Total Paid” line/card stays invoice-payments-only. - app/controllers/ContactController.php — passes Auth::id() as the recorder of the posted finance row.

Verified live end-to-end (real HTTP, signed-in session, all test data cleaned up): created a supplier+client contact, recorded a $250 Purchase + a $175 Sale, then settled both. Settling the Purchase posted a real DEBIT contact_purchase of $250 and raised the tenant's month Total Expenses (debit sum) by exactly $250; collecting the Sale posted a real CREDIT contact_sale of $175 and raised income (credit sum) by exactly $175; net Net-Liquidity movement over the flow was income - expenses = -$75.00, and both ledger rows read Settled. Separately confirmed a raw over-pay (POST $500 against a $100 balance) clamps amount_paid to $100 AND posts only $100 to Finance, never $500. PHPUnit 29/29 (859 assertions).

NOTE: this is the same root pattern the ticket names as BUG-P02 (“Prepaid” method never touches Customer Wallets) and BUG-R04 (a standalone Credit never touches Customer Wallets) — those two are separate items, not filed as their own MANARA tickets, and were NOT touched here; only the Contact ledger → Finance disconnect (this ticket) was fixed. PROD: run /run-migrations.php for migration 067.

Activity / Notes

Where + how: - app/classes/Crm/ContactTransaction.php — recordPayment() is now transactional and posts a matching finance-ledger (transactions) row for the amount actually settled: a Purchase settlement → a DEBIT (money out / expense), a Sale collection → a CREDIT (money in). It locks the ledger row, clamps the payment to the remaining balance (so a raw over-pay posts only what actually applied, never the raw figure), and posts inside the SAME db transaction so a failed finance post rolls the settlement back. Mirrors how PayrollEntry::record() posts its expense. - WHY NOT the payments table (as the ticket suggested for a Sale): payments.invoice_id is NOT NULL and invoices.customer_id is NOT NULL — a Contact is neither an invoice nor a customer, so a “payment” with no invoice is structurally impossible and would be a lie in the invoice-collection ledger. The transactions ledger (debit=out, credit=in) is the app's real general-ledger primitive (it's exactly what the Expenses module is), so both directions post there. A settled Purchase and a collected Sale now both appear in the /expenses finance list. - Migration 067 (app/../database/migrations/067_contact_settlement_types.sql, folded into schema.sql, embedded in run-migrations.php now 004-007 + 011-067): two system transaction types, contact_purchase (debit, “Supplier Purchase”) and contact_sale (credit, “Client Sale”), so these settlements are their own categories in the finance breakdown (same pattern as the payroll/commission types). If the type is missing (pre-migration DB) the settlement throws and rolls back rather than silently losing the finance side again. - app/controllers/DashboardController.php — Net Liquidity is now money IN - money OUT = (invoice payments + credit-direction finance entries) - (debit expenses). Before, credits were counted nowhere, so a collected Sale (and, correctly, any Deposit/Adjustment credit) never moved the figure. The Financial Trends chart's net line was updated the same way (new Transaction::creditSeries()) so it stays consistent with the headline; the “Total Paid” line/card stays invoice-payments-only. - app/controllers/ContactController.php — passes Auth::id() as the recorder of the posted finance row.

Verified live end-to-end (real HTTP, signed-in session, all test data cleaned up): created a supplier+client contact, recorded a $250 Purchase + a $175 Sale, then settled both. Settling the Purchase posted a real DEBIT contact_purchase of $250 and raised the tenant's month Total Expenses (debit sum) by exactly $250; collecting the Sale posted a real CREDIT contact_sale of $175 and raised income (credit sum) by exactly $175; net Net-Liquidity movement over the flow was income - expenses = -$75.00, and both ledger rows read Settled. Separately confirmed a raw over-pay (POST $500 against a $100 balance) clamps amount_paid to $100 AND posts only $100 to Finance, never $500. PHPUnit 29/29 (859 assertions).

NOTE: this is the same root pattern the ticket names as BUG-P02 (“Prepaid” method never touches Customer Wallets) and BUG-R04 (a standalone Credit never touches Customer Wallets) — those two are separate items, not filed as their own MANARA tickets, and were NOT touched here; only the Contact ledger → Finance disconnect (this ticket) was fixed. PROD: run /run-migrations.php for migration 067.

Full History

Date User Field Change
2026-07-28T14:42:20+01:00 Khaled Tarabay issue-new New Issue
2026-07-29T07:15:07+01:00 Claude Assigned To ⇒ Claudine
2026-07-29T07:15:09+01:00 Claude tag-added Tag Attached: done-by-claude
2026-07-29T07:15:11+01:00 Claude note-added Note Added: 0000095
2026-07-29T07:15:14+01:00 Claude Status new ⇒ resolved

Synced automatically from MantisBT issue #136.