This is an old revision of the document!
Table of Contents
contacts invoices and payments (Resolved)
Reported by: Khaled Tarabay on 2026-07-29T08:54:19+01:00
Assigned to: Claude
Resolved by: Claude on 2026-07-29T10:10:51+01:00
Priority: normal
Severity: minor
Reproducibility: always
Category: General
Description: You're working in the source code of BOS (“Manara” white-label), a multi-tenant ISP Business Operations System SaaS. This handoff describes a feature request from the LEGO tenant's product owner, following a black-box QA pass against the live app (https://bos.matrixdn.net/). The tester had no access to your codebase, so everything below is described from the outside — URLs, field names, form behavior — rather than in terms of your actual files or framework. Your first job is to locate the real code behind each of these before changing anything.
The Contacts submodule (CRM → Contacts) manages Suppliers, Clients, and Internet Providers, and a contact can hold any combination of those three roles. Each contact has its own lightweight ledger: a “purchase” transaction (kind=purchase) records money the company owes that contact, created via POST /contacts/{id}/transactions with fields kind, amount, occurred_at, description; a “sale” transaction (kind=sale) records money that contact owes the company, same endpoint. Each transaction row has its own partial-settlement box, POST /contacts/{id}/transactions/{txnId}/pay with an amount field, which reduces that row's outstanding balance and flips it to “Settled” once fully paid, with direction-aware buttons — “Pay” for a purchase row, “Collect” for a sale row. This math was verified extensively and is correct: cumulative partial payments track to the cent, negative amounts are rejected both client- and server-side, and the “Has balance” list filter and the list-level YOU OWE (ALL SUPPLIERS) / OWED TO YOU (ALL CLIENTS) aggregates all sum correctly off these rows. This ledger is now correctly wired into Finance reporting (previously filed as BUG-CRM04, since fixed and re-verified live): settling a purchase posts a “Supplier Purchase | Debit” row into the general Expenses/Transactions ledger (/expenses), and settling a sale posts a “Client Sale | Credit” row there too, and both correctly move Business Overview's (/dashboard) TOTAL EXPENSES and NET LIQUIDITY figures — confirmed with fresh test data, a $180.00 purchase and $95.00 sale each showed up as their own dated row in /expenses and moved the dashboard totals by exactly that amount. Nothing further is needed on that front, don't re-touch it.
This is a completely separate system from the main Billing module — Customer-facing invoices at /billing, statuses Draft/Issued/Paid/Partially Paid/Refunded/Void, real invoice numbers like LG-INV-93, Print/PDF, and a Payments module that records money against Billing invoices specifically, tied to invoice_id. Billing's actual operational framework matters here and isn't optional context — the new Contact-Sale invoicing has to reproduce this exact sequencing, verified live against the current module, not just reuse the invoice template visually. Invoice existence and payment are two separate, sequential actions, and payment never creates or auto-issues an invoice: a freshly created invoice defaults to Draft, and attempting to record a payment against a Draft invoice is hard-rejected server-side with “Issue this invoice before recording a payment against it” — the invoice must be explicitly moved to Issued first, as its own distinct step, before any payment can touch it. Recording a payment against an Issued invoice automatically updates that invoice's own fields — PAID, BALANCE DUE, and Status all update in the same action as a direct side effect, not a separate reconciliation step; paying an $80.00 invoice in full produces PAID $80.00, BALANCE DUE $0.00, status Paid/Settled, immediately, no further action needed. A partial payment produces a distinct status, not the same as a full payment — paying $40.00 of a $100.00 invoice correctly reads Partially Paid, not Paid. Translate this directly to the Contact-Sale flow: recording a sale transaction must create the underlying Invoice as Draft (or, if the product decision is that a Contact Sale should be usable immediately without a separate Issue step, confirm that with the product owner rather than assuming either way, since it's a real behavior change from how Billing works today), and the “Collect” action on that transaction must go through the same payment-recording code path Billing already uses, not a separate ad hoc balance update, so that Partially Paid vs Paid status, the PAID/BALANCE DUE fields, and the hard block on paying an un-Issued invoice all behave identically for a Contact invoice as they already correctly do for a Customer invoice. Don't reimplement this state machine from scratch for Contacts, call into the existing one.
With the Finance-integration gap closed, what's left is a genuine feature build, not a bug fix. First: add real invoicing to the Sale side only. For kind=sale transactions — money a Client owes the company — the product owner wants a proper, client-facing invoice document, the same kind of thing Billing already generates for Customers, a numbered invoice, Print/PDF, a real status lifecycle. Do not build a second, parallel invoice engine — extend Billing's existing Invoice model/numbering/PDF/print flow so an invoice can be raised against a Contact in addition to a Customer (Billing invoices are presumably tied to a customer_id today, so you'll need to either make that polymorphic or add an equivalent contact_id path through the same rendering/numbering code). Once this exists, a settled Contact Sale and a settled Billing Invoice should look and behave the same way to a Client on the receiving end. Whatever code now posts the “Client Sale | Credit” Expenses-ledger row on settlement is a good starting point to trace backwards from — that's the current point of contact between a Contact Sale and the rest of Finance, and the new Invoice object should plug in alongside it, not replace it, since that Expenses-ledger entry is what feeds Business Overview and should keep doing so.
Second: do not build a generated-invoice format for the Purchase side. A purchase is a bill the company receives from a supplier, not one it generates — a PDF invoice-generator doesn't make sense there. Instead, add a file attachment field on a purchase transaction so staff can upload the supplier's actual invoice/receipt, plus a free-text reference/bill-number field. This is a small, self-contained change, independent of the Sale-side work, and a good one to do first since it carries no shared-code risk, before moving on to the larger, more architecturally sensitive Billing-engine extension — which will touch shared invoice-numbering and PDF-rendering code, so budget time for regression-testing existing Customer invoices afterward, and make sure it doesn't disturb the now-working Expenses-ledger posting on settlement.
Done looks like this: a Sale against a Contact can be raised as a real, numbered, printable/PDF invoice through the same engine Customer invoices already use; the Contact invoice follows the identical Draft → Issued → Partially Paid/Paid state machine as a Customer invoice, so attempting to collect against an un-Issued Contact invoice is rejected the same way, a partial Collect correctly produces Partially Paid, and a full Collect correctly produces Paid with BALANCE DUE $0.00; settling that Contact invoice still produces the existing “Client Sale | Credit” Expenses-ledger row and still moves Business Overview's totals correctly, since the new invoicing layer sits on top of the existing working money-tracking rather than replacing it; existing Customer-facing Billing invoices are unaffected, verified with a full regression pass on invoice creation, numbering, and PDF rendering for Customers after touching the shared invoice code; and a purchase transaction supports a file attachment and a reference field, both visible on the transaction's detail view.
Resolution: FIXED — both parts, built in the ticket's recommended order (attachment first, then the Billing-engine extension), with a full regression pass on customer invoices.
PART A — Purchase attachment + reference/bill number (migration 071). A purchase contact-transaction can now carry the supplier's ACTUAL bill (an uploaded PDF/image — a received document, no generated invoice) plus a free-text bill/reference number, both shown on the contact's ledger. - contact_transactions.attachment_path added; reference already existed and is now wired. New FileUploader::storeDocument() (PDF + PNG/JPEG/WEBP, 8MB, anti-polyglot re-check on images). Stored outside the web root, served only via a new permission-checked route GET /uploads/contact-bills/{txnId}/{filename} (UploadController::contactBill — requires contacts.manage AND the txn belongs to this tenant AND the filename matches the stored one, so no cross-tenant read and no enumeration). The add-transaction form gained the Reference + Attach-bill fields (multipart); the ledger shows “Ref: …” + a “View bill” link. A failed upload doesn't undo the ledger row — it's saved and the user is warned.
PART B — Client SALE raised as a real Billing invoice, same engine (migration 072). Product decision confirmed with the owner: MIRROR BILLING EXACTLY (Draft → Issue → Collect). - invoices is now polymorphic: customer_id nullable + new contact_id, with a DB CHECK enforcing exactly one (customer XOR contact). contact_transactions.invoice_id links a sale row to its invoice. - Recording a Client Sale now also creates a linked DRAFT invoice through the same engine/numbering (new ContactInvoicer::draftSaleInvoice, mirroring JobInvoicer) — a real number, one line item (sp_recalc_invoice sets the total), Print/PDF. Same lifecycle as a customer invoice. - The sale row's actions on the contact page: Issue (Draft→Issued) then Collect. “Collect” goes through the REAL Billing payment path (a payments row → sp_recalc_invoice drives amount_paid/balance/status), NOT an ad-hoc balance update — so collecting on an un-Issued invoice is rejected (“Issue this invoice first”), a partial Collect → Partially Paid, a full Collect → Paid ($0 balance), and overpayment is rejected, identically to a customer invoice. The ledger row's amount_paid is synced to the invoice. - The existing “Client Sale | Credit” Expenses-ledger posting on settlement is UNCHANGED and still fires (it feeds Business Overview) — the invoice layer sits on top of it, doesn't replace it. - Print/PDF and the invoice show page reuse the existing Billing views (bill-to coalesces to the contact); the customer-only actions (Record Payment/Refund/Void) and line-item editing are hidden for a contact invoice and blocked server-side too. Contact invoices are kept OUT of the /billing customer list and the customer payment pickers (they're managed from the contact page).
VERIFIED LIVE against the local DB — Part A 13/13 (upload round-trip, stream auth/enumeration/unauth guards, bad-file rejection) and Part B 31/31, INCLUDING a full customer-invoice regression (7/7): create → add item → issue → pay → Paid, list/show/print/picker all still correct after the shared-invoice changes. Full lifecycle proven end-to-end: sale → draft invoice, collect-on-draft rejected, issue, partial→Partially Paid, full→Paid, collect-on-paid + overpay rejected, Client-Sale credit posted, and the customer-only actions blocked on a contact invoice. PHPUnit 29/29.
Prod: run /run-migrations.php for migrations 071 and 072.
Activity / Notes
- 2026-07-29T10:10:48+01:00 - Claude: FIXED — both parts, built in the ticket's recommended order (attachment first, then the Billing-engine extension), with a full regression pass on customer invoices.
PART A — Purchase attachment + reference/bill number (migration 071). A purchase contact-transaction can now carry the supplier's ACTUAL bill (an uploaded PDF/image — a received document, no generated invoice) plus a free-text bill/reference number, both shown on the contact's ledger. - contact_transactions.attachment_path added; reference already existed and is now wired. New FileUploader::storeDocument() (PDF + PNG/JPEG/WEBP, 8MB, anti-polyglot re-check on images). Stored outside the web root, served only via a new permission-checked route GET /uploads/contact-bills/{txnId}/{filename} (UploadController::contactBill — requires contacts.manage AND the txn belongs to this tenant AND the filename matches the stored one, so no cross-tenant read and no enumeration). The add-transaction form gained the Reference + Attach-bill fields (multipart); the ledger shows “Ref: …” + a “View bill” link. A failed upload doesn't undo the ledger row — it's saved and the user is warned.
PART B — Client SALE raised as a real Billing invoice, same engine (migration 072). Product decision confirmed with the owner: MIRROR BILLING EXACTLY (Draft → Issue → Collect). - invoices is now polymorphic: customer_id nullable + new contact_id, with a DB CHECK enforcing exactly one (customer XOR contact). contact_transactions.invoice_id links a sale row to its invoice. - Recording a Client Sale now also creates a linked DRAFT invoice through the same engine/numbering (new ContactInvoicer::draftSaleInvoice, mirroring JobInvoicer) — a real number, one line item (sp_recalc_invoice sets the total), Print/PDF. Same lifecycle as a customer invoice. - The sale row's actions on the contact page: Issue (Draft→Issued) then Collect. “Collect” goes through the REAL Billing payment path (a payments row → sp_recalc_invoice drives amount_paid/balance/status), NOT an ad-hoc balance update — so collecting on an un-Issued invoice is rejected (“Issue this invoice first”), a partial Collect → Partially Paid, a full Collect → Paid ($0 balance), and overpayment is rejected, identically to a customer invoice. The ledger row's amount_paid is synced to the invoice. - The existing “Client Sale | Credit” Expenses-ledger posting on settlement is UNCHANGED and still fires (it feeds Business Overview) — the invoice layer sits on top of it, doesn't replace it. - Print/PDF and the invoice show page reuse the existing Billing views (bill-to coalesces to the contact); the customer-only actions (Record Payment/Refund/Void) and line-item editing are hidden for a contact invoice and blocked server-side too. Contact invoices are kept OUT of the /billing customer list and the customer payment pickers (they're managed from the contact page).
VERIFIED LIVE against the local DB — Part A 13/13 (upload round-trip, stream auth/enumeration/unauth guards, bad-file rejection) and Part B 31/31, INCLUDING a full customer-invoice regression (7/7): create → add item → issue → pay → Paid, list/show/print/picker all still correct after the shared-invoice changes. Full lifecycle proven end-to-end: sale → draft invoice, collect-on-draft rejected, issue, partial→Partially Paid, full→Paid, collect-on-paid + overpay rejected, Client-Sale credit posted, and the customer-only actions blocked on a contact invoice. PHPUnit 29/29.
Prod: run /run-migrations.php for migrations 071 and 072.
Full History
| Date Modified | Username | Field | Change |
|---|---|---|---|
| 2026-07-29T08:54:19+01:00 | Khaled Tarabay | issue-new | New Issue |
| 2026-07-29T10:10:43+01:00 | Claude | Assigned To | ⇒ Claudine |
| 2026-07-29T10:10:46+01:00 | Claude | tag-added | Tag Attached: done-by-claude |
| 2026-07-29T10:10:48+01:00 | Claude | note-added | Note Added: 0000099 |
| 2026-07-29T10:10:51+01:00 | Claude | Status | new ⇒ resolved |
Synced automatically from MantisBT issue #140.
