PSA/docs/plans/2026-06-11-qbo-phase2-closed-loop/SCRATCHPAD.md

SCRATCHPAD — QBO Phase 2: Closed-Loop Accounting Sync

Decisions (with rationale)

• 2026-06-10 — QBO is authoritative for payments; Alga pushes both ways (user-confirmed). Bookkeepers live in QBO; payments recorded there flow into Alga as real AR records, and Alga-originated (Stripe portal) payments push out so the books agree. Conflicts resolve in QBO's favor.
• 2026-06-10 — CDC polling through the IJobRunner abstraction, no Intuit webhooks this phase (user-confirmed, with correction: "pg-boss is usually not used, usually temporal is, but the abstraction should handle it properly"). On-prem appliances cannot receive Intuit webhooks, so polling must exist regardless; one code path for hosted + appliance.
• 2026-06-10 — Credit semantics reshape lands before credit sync (user-confirmed after impedance-mismatch review). applyCreditToInvoice decrements invoices.total_amount (creditActions.ts:910) — posted documents must be immutable; application moves derived balance-due. Reshape now while the credit system is barely used; backfill is recoverable (total_amount += credit_applied).
• 2026-06-10 — Real void semantics (user-confirmed). cancelled status and invoice_cancelled transaction type exist in the schema but are unused; a voidInvoice action adopts them. Hard delete blocked for exported invoices.
• 2026-06-10 — Architecture B: central sync engine (user-confirmed) over per-feature jobs (fragmented state) and over resurrecting the event-bus push model deliberately removed in Oct 2025 (migration 20251031121500_remove_qbo_workflow_automation.cjs).
• 2026-06-11 — Engine is adapter-agnostic by construction. Shared tables carry adapter_type; no qbo_ prefixes. Xero adopts the engine in a later phase ~for free.
• 2026-06-11 — Test planning follows the 80/20 rule (user-directed): automated tests target ~80% confidence; the rest is the live Intuit-sandbox smoke checklist. tests.json marks live-smoke entries with "mode": "live-smoke".

Key file paths

• Design (scope authority for architecture): ./design.md
• Phase 1 feature commit: 01ff24f662; design commit: 91fc97b5b6 (branch release/qbo-online-integration)
• Adapter: packages/billing/src/adapters/accounting/quickBooksOnlineAdapter.ts
• Client service: packages/integrations/src/lib/qbo/qboClientService.ts
• Payment landing (to refactor into shared service): ee/server/src/lib/payments/PaymentService.ts:598 (recordPaymentFromWebhook)
• Credit application mutation site: packages/billing/src/actions/creditActions.ts:910
• Job abstraction: packages/jobs/src/lib/jobs/interfaces/IJobRunner.ts; startup registration server/src/lib/jobs/initializeScheduledJobs.ts
• Workflow task inbox: shared/workflow/persistence/workflowTaskModel.ts:119; unwired qbo_mapping_error task type from migration 20250511215231_consolidate_qbo_workflow_schema.cjs:126
• Badge precedent: packages/billing/src/components/invoices/InvoiceTaxSourceBadge.tsx

Gotchas

• JobScheduler.scheduleRecurringJob (server/src/lib/jobs/jobScheduler.ts:184) coerces every interval to 24 hours. The 15-minute cycle must use the shorter-interval path (precedent: renew-google-gmail-watch every 30 min) or fix the coercion.
• CDC overlap window (5 min) makes duplicate delivery routine — every inbound applier must be a no-op for already-mapped, unchanged entities.
• invoice_payments is EE-only today; acceptable because the QBO integration is EE-gated, but the shared recordExternalPayment service lives in EE.
• Pre-existing local test failures unrelated to this work (verified via git stash on clean tree): xeroAdapter.spec.ts (needs live test DB; local .env.localtest creds fail), pageTitles.metadata.test.ts T006/T007/T024/T026, XeroIntegrationSettings.contract.test.tsx 3/6.
• Run package tests from server/: npx vitest run ../packages/... (root vitest.config.ts include-globs don't match package paths).

Commands

• Targeted suites: cd server && npx vitest run src/test/unit/api/qboOAuthRoutes.test.ts
• Typecheck a package: cd packages/<pkg> && npx tsc --noEmit -p tsconfig.json
• Pseudo-locales after en changes: node scripts/generate-pseudo-locales.cjs

Implementation notes (slice 1 built 2026-06-11)

• Scheduling deviation (F011): instead of connect/disconnect registration, accounting-sync-cycle is scheduled for EVERY tenant at startup (initializeScheduledJobs) like the platform's other per-tenant jobs, with a cheap no-op guard for CE/unconnected/auto-sync-off tenants. Cron */15 * * * * goes through getJobRunner() (PgBossJobRunner uses real boss.schedule() per-schedule queues; Temporal in EE) — NOT the legacy initializeScheduler() JobScheduler, which coerces intervals to 24h.
• The auto-sync toggle is the engine's master switch: cycles skip when off; force (Sync Now) bypasses. First-run cursor = now − 5min (never imports history; the slice-3 wizard is the deliberate path for that).
• One job tick per tenant enumerates realms and runs sequential per-realm cycles (multi-realm scheduling needs no extra registration in slice 4).
• RefundReceipt added to the CDC entity set + change-entity union (stats-only).
• Health panel = QboSyncHealthPanel in packages/billing, injected into QboIntegrationSettings via a syncHealthSlot prop threaded from server/src/components/settings/SettingsPage.tsx — avoids the billing↔integrations package cycle (nx cycles broke appliance builds before).
• recordExternalPayment transaction metadata is a superset of the old Stripe metadata (adds reference_number); PaymentService webhook path now delegates to it (validation + PAYMENT_RECORDED/APPLIED publication unchanged).
• Notifications: system-announcement internal template; recipients = active internal users with role_name 'admin'. Token thresholds remembered in tenant_settings.settings.accountingSync.tokenNotices[realm].
• Sync Now runs the cycle inline in the server action (no job round-trip).
• T032 (DB-backed integration cycle test) + T033 (migration round-trip) deferred: local test DB unavailable (pre-existing). Stripe integration tests are DB-skipped locally; T016 verified via typecheck + unchanged validation semantics. Live-smoke T034-T041 pending an Intuit sandbox session.