0010 — Payments as a primitive module; billing depends on payments

• Status: accepted
• Date: 2026-05-13
• Deciders: Ramón Martínez (DentalPin Core)
• Tags: modules, finance, dental-operations

Context

The original billing module owned the Payment model with a NOT-NULL invoice_id. That coupling blocks three operational realities of a dental clinic, validated with the user when scoping issue #53:

1. Patients commonly pay before an invoice exists — anticipos and partial cobros against an accepted budget.
2. Some clinics legitimately leave certain treatments off the invoice. The software cannot assume executed ⇒ invoiced nor expose KPIs that document the diff between paid/earned and invoiced — those metrics surface an operative clinics keep off-record, and visibility would be a stopper for adoption.
3. The clinic needs real-time financial visibility (patient credit, clinic receivable, refunds, breakdowns) that has nothing to do with invoice state.

A standalone payments module with patient-centric Payment and an allocations layer (budget | on_account) cleanly supports anticipos. A Refund entity replaces the legacy is_voided flag. The invoice ↔ payment link is owned by billing in its own invoice_payments table.

Decision

payments is a primitive module. billing depends on payments; the reverse direction is forbidden. Concretely:

• payments.manifest.depends = ["patients", "budget"].
• billing.manifest.depends = ["patients", "catalog", "budget", "payments"].
• payments never imports app.modules.billing.*.
• The link between an Invoice and a Payment lives in billing.invoice_payments — billing tracks the imputation in its own schema, payments stays invoice-agnostic.
• Invoice.total_paid and Invoice.balance_due are no longer stored columns; they are computed in BillingService.compute_paid_summary from invoice_payments minus proportional refunds.
• Reports of payment KPIs (collected, refunded, net, patient credit, receivable, aging, refunds, trends) live in /api/v1/payments/reports/*, inside the payments module.
• No KPI must compare the paid axis with the invoiced axis (e.g. "cobrado no facturado"). The fiscal axis stays in /api/v1/reports/billing/* (invoice-side aging, overdue) and is legitimate; the payment-side reports compare paid ↔ earned ↔ refunded only.
• The earned signal for the patient ledger comes from event payloads (odontogram.treatment.performed, treatment_plan.treatment_completed) and is materialized in patient_earned_entries. Payments never imports odontogram or treatment_plan.

Consequences

Good

• Anticipos against budgets become first-class without faking an invoice. Payment is patient-centric.
• Off-books reality is supported without code paths labelled as such: treatments can be performed without an invoice, payments can be recorded without an invoice, and no metric surfaces the diff.
• Single source of truth for invoice paid amount (the invoice_payments rows + refunds), no cached column drift.
• Refund is the only payment-adjustment mechanism. Cleaner audit surface than the legacy is_voided flag.
• Module isolation holds: payments has zero imports from billing / odontogram / treatment_plan; billing imports payments freely (declared in depends).

Bad / accepted trade-offs

• Invoice.total_paid and Invoice.balance_due now require an aggregation over invoice_payments + refunds. List endpoints pay for one extra query (batched). Acceptable at clinic-scale data sets.
• One asymmetric dependency direction means a future "billing without payments" deployment is not supported; payments is mandatory once billing is installed. Both are removable=False so this is intentional.
• The orchestrator POST /api/v1/billing/invoices/{id}/payments internally uses a payments-module Payment with an on_account allocation plus an InvoicePayment row. The invariant Σ allocation.amount == payment.amount is preserved without leaking invoice references into payments.

Alternatives considered

• Keep Payment inside billing with optional FK to invoice / budget. Rejected — does not solve the off-books metric concern, keeps the is_voided flag, and conflates fiscal and operational axes in one schema.
• Payments depending on billing. Rejected — would mean the payment table needs to know about invoices to compute its allocations, which reintroduces the very coupling the extraction is meant to break.
• Eventual consistency via events for Invoice status. Rejected for money: refunds proportionally affect already-imputed payments and require a transactional recalc that fits the synchronous recalc_invoice_status path triggered by the payment.refunded handler.

How to verify the rule still holds

• backend/tests/test_module_isolation.py confirms payments does not import billing, odontogram, or treatment_plan.
• backend/app/core/plugins/manifest_validator.py enforces that every cross-module FK resolves to a module listed in manifest.depends.
• Search guard: no /api/v1/payments/reports/* endpoint may return a field whose name suggests cross-axis comparison (paid_vs_invoiced, unbilled_paid, etc.). Reviewers flag in PR.
• backend/scripts/generate_catalogs.py --check keeps the event + module catalogs in sync; reviewers see new payment events at PR time.

References

• Issue #53
• backend/app/modules/payments/ (module root)
• backend/app/modules/payments/CLAUDE.md
• backend/app/modules/billing/models.py (InvoicePayment)
• backend/app/modules/billing/migrations/versions/bil_0004_invoice_payments.py
• ADR 0001 (modular plugin architecture)
• ADR 0003 (event bus over direct imports)