PSA/docs/plans/2026-06-11-qbo-phase2-slice2-credits-voids/SCRATCHPAD.md

SCRATCHPAD — QBO Slice 2: Credits & Voids

Decisions (inherited from design, 2026-06-10/11)

• Immutable invoice totals: the reshape lands before any credit sync; backfill is lossless (total_amount += credit_applied).
• Prepayments are NOT CreditMemos (unearned revenue ≠ revenue reversal); excluded from export, future mapping to QBO unapplied payments unscheduled.
• Credit application in QBO = zero-dollar Payment linking CreditMemo↔Invoice.
• Voids use the existing-but-unused cancelled status + invoice_cancelled transaction type; void blocked while payments exist; hard delete blocked for exported documents.
• Unapply of a synced allocation is exception-only (no auto-reversal in QBO).

Key file paths

• Mutation site to fix: packages/billing/src/actions/creditActions.ts:910 (applyCreditToInvoice .decrement('total_amount', ...))
• Negative-invoice finalize behavior: packages/billing/src/actions/invoiceModification.ts (finalizeInvoiceWithKnex, credit_issuance_from_negative_invoice)
• Stripe payment link amount: @alga-psa/billing/actions/paymentActions (getOrCreateInvoicePaymentLinkUrl)
• Hard delete (payment reversal precedent): invoiceModification.ts:984
• Adapter to extend with CreditMemo/void: packages/billing/src/adapters/accounting/quickBooksOnlineAdapter.ts
• Export selector already flags credits: accountingExportInvoiceSelector.ts (credit_memo: line.isCredit metadata)

Read-site audit (fill in during implementation — REQUIRED before backfill merges)

• MSP invoice list / detail
• Client portal invoice list / detail / pay page
• Stripe payment link amount
• Overdue detection job
• Invoice PDF templates / email templates
• Accounting export selectors (settledness reasoning)
• (append every additional site the grep finds)

Gotchas

• invoices.credit_applied exists since 20241126030648; the pair (total_amount, credit_applied) is what makes the backfill lossless.
• QBO void is an explicit operation (operation=void) requiring Id+SyncToken; stale sync tokens surface as QBO_STALE_OBJECT — re-read then void.
• CreditMemo tax: sign-flip must keep TxnTaxDetail consistent in internal-tax mode; in delegated mode QBO computes — mirror the invoice transform paths.

Implementation notes (built 2026-06-11)

• Read-site audit executed via subagent sweep; every MUST-CHANGE applied (Stripe link amount now charges balance due with a zero-balance guard; refund thresholds, portal amounts, emails, AR sums all net of credits). KEEP list honored — purchaseOrderService / aging / outstanding_amount formulas became correct automatically once totals turned immutable.
• Backfill is total_amount += credit_applied (single UPDATE, recoverable pair); invoice_type backfilled from is_prepayment + negative totals.
• Credit notes renumber to the CM- sequence AT FINALIZE (issuance moment); drafts keep their provisional invoice number until then.
• F025 (unapply exception): NO unapply action exists in the codebase, so there is nothing to hook — recorded as satisfied-by-absence.
• F026 (i18n): billing-dashboard components follow the package's existing non-localized convention; no integrations-namespace strings were added.
• apply_credit ops are enqueued per (allocation, credit-note) pair via the credit_tracking→transactions join, so multi-pool applications reconcile per memo; ops wait (no attempt burn) until both documents are mapped.
• Voids: QBO Invoice uses operation=void; CreditMemo has no void in QBO → operation=delete; drift detector ignores changes on 'voided'/'external_voided' mappings so our own void doesn't file drift.
• Deferred to a DB-enabled env: T001 (apply leaves total untouched — code audited), T003/T006 (migration round-trips), T004/T005 (Stripe/portal contract — Stripe integration suite is DB-skipped locally), T007 (CM sequence uses the generate_next_number PG function), T010 (validation exclusion), T017 (hardDelete block), T020 (full-cycle integration).