PSA/docs/plans/2026-06-11-qbo-phase2-slice4-polish/SCRATCHPAD.md

SCRATCHPAD — QBO Slice 4: Payments Out, Class Tracking, Multi-Realm

Decisions

• 2026-06-11 — Intuit webhooks excluded (user-confirmed). 15-minute CDC polling is competitive; webhooks get their own plan only if hosted latency becomes a real complaint. Keeps hosted/appliance behavior identical.
• Deposit account defaults to Undeposited Funds, resolved at delivery time (not stored) so renamed/recreated accounts don't strand a stale ref.
• Class granularity v1 = per item mapping metadata + tenant default; no per-client/per-invoice overrides.
• default_realm becomes an explicit tenant setting; phase-1's first-stored-key ordering remains the fallback when unset.

Key file paths

• Payment producer site: recordExternalPayment (slice-1 extraction from ee/server/src/lib/payments/PaymentService.ts)
• Echo-suppression mechanism: payment mapping rows in tenant_external_entity_mappings (slice-1 design)
• Catalog action pattern: packages/integrations/src/actions/qboActions.ts
• Realm defaulting to swap to setting-backed: getDefaultQboRealmId in packages/integrations/src/lib/qbo/qboClientService.ts
• Settings connection card to become a list: packages/integrations/src/components/settings/integrations/QboIntegrationSettings.tsx
• Batch dialog for the realm picker: packages/billing/src/components/billing-dashboard/accounting/AccountingExportsTab.tsx

Gotchas

• QBO Payment currency must match the customer's currency; mismatches ride the slice-1 currency exception path — multi-currency tenants will hit it.
• DepositToAccountRef must reference an account of an allowed type (Other Current Asset/Bank); filter in getQboAccounts, not just in the UI.
• The double-entry scenario (bookkeeper manually re-keys a pushed Stripe payment) is detected at application time as an over-allocation on a settled invoice — exception, never auto-reversal.
• Disconnecting one realm of several must not deregister the other realm's cycle (singleton keys are per tenant×realm).

Implementation notes (built 2026-06-11)

• Payment push producer lives INSIDE recordExternalPayment's success path with a provider !== 'quickbooks' echo guard, so any future provider pushes automatically; reverseExternalPayment pushes nothing (refunds out of scope).
• DepositToAccountRef omitted when unconfigured — QBO defaults to Undeposited Funds natively (no account lookup needed). PaymentRefNum truncated to QBO's 21-char limit.
• Echo suppression verified end-to-end: push stores String(response.SyncToken) in the payment mapping; the CDC change for the same payment carries the same token → inbound applier no-ops.
• Double-entry guard: NEW external payments against fully-settled invoices file an accounting_sync_unmapped_payment exception with reason 'over_application' and apply nothing; partial invoices accept normally.
• Realm UX landed in QboSyncHealthPanel (realm list + make-default via AccountingSyncHealth.realms + setDefaultQboRealm) instead of the integrations connection card — package-direction constraint. Batch dialog realm picker appears only with >1 realm. Wizard intentionally runs against the default realm (resolveDefaultRealm inside the onboarding actions).
• resolveDefaultRealm (settings.defaultRealm validated against the credential map, else first-stored-key) adopted by ALL billing call sites including the four syncProducers producers (follow-up TODO closed same day).
• Settings-dir contract suites (Microsoft/Xero/MspSso) have 13 pre-existing, shuffle-sensitive failures — identical on a clean tree (stash-verified).