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

PRD: QBO Closed-Loop Sync — Slice 1

• Status: Draft
• Owner: Robert Isaacs
• Created: 2026-06-11
• Design: ./design.md (architecture authority; this PRD details slice 1)
• Branch: feature branches off release/qbo-online-integration

1. Problem statement & user value

Phase 1 shipped a one-way, operator-driven invoice push to QuickBooks Online. The moment a client pays an invoice in QBO, Alga is wrong: AR status, the client portal, and collections all show unpaid until someone reconciles by hand. There is also no automation (an operator must remember to create export batches), no per-invoice answer to "is this in QuickBooks?", and a dead connection is discovered only when an export fails.

Slice 1 closes the loop for the highest-value flows: a scheduled sync engine pulls QBO payments into Alga as real AR records, pushes newly finalized invoices out automatically, detects drift on exported invoices, surfaces sync state on every invoice, and warns billing admins before the connection breaks.

2. Goals (slice 1)

• A per-tenant×realm sync cycle runs every ~15 minutes unattended, on Temporal or pg-boss via the IJobRunner abstraction, identically on hosted and appliance.
• Payments recorded in QBO (including edits and deletions) are applied to Alga invoices within one cycle: invoice_payments row, payment transaction, status flip to paid/partially_applied.
• Finalizing an invoice auto-enqueues its export; the cycle delivers it through the existing batch pipeline (auto-batches, origin: 'scheduled').
• Exported invoices changed or voided in QBO are flagged as drift with re-export / accept resolutions.
• Every invoice shows a sync badge (Not synced | Queued | Synced | Drift | Error | Voided) with a deep link into QBO; the QBO settings page shows cycle health and pending work.
• Refresh-token expiry and auth failures notify billing admins (14/7/2-day countdown; immediate on failure).
• Sync exceptions land in the existing workflow-task inbox, deduplicated to one open task per entity+type.

3. Non-goals (slice 1)

• Credit memo export, credit reshape, voids (slice 2 — outlined in §9).
• Customer mapping UI, reconciliation wizard, go-live cutoff (slice 3).
• Outward Stripe-payment push, class/department tracking, multi-realm UX, Intuit webhooks (slice 4).
• Importing QBO-originated documents; RefundReceipt handling (surface only).
• Monitoring/metrics beyond the cycle stats already in the design.

4. Personas & primary flows

• MSP billing admin: connects QBO (phase 1), leaves auto-sync on; finalized invoices appear in QBO within a cycle; when clients pay, Alga flips to paid by itself. Checks the settings health panel when something looks off; works sync exceptions from the task inbox.
• MSP bookkeeper (in QBO): records, edits, or deletes payments in QBO as the book of record; Alga follows without being told.
• Operator (existing flow): can still create manual export batches; they ride the same pipeline and satisfy any queued auto-export ops.

5. Functional scope (slice 1 detail)

5.1 Sync engine

Per design.md §Sync engine: accounting_sync_cycles (cursor + run history), accounting_sync_operations (outbound queue), new adapter capabilities supportsChangePolling/fetchChanges(since) (QBO: CDC) and supportsPaymentRecording (declared now, used in slice 4). Cycle order: token health → inbound (customers, payments, invoice drift) → outbound drain → cursor advance (inbound success only; outbound failures retry with capped backoff, then become exceptions). 5-minute cursor overlap; all appliers idempotent against the mapping ledger. Scheduling registered on connect / deregistered on disconnect / re-registered at startup; singleton-keyed per tenant×realm. "Sync now" triggers an immediate cycle.

5.2 Inbound payments

Per-allocation application from Payment.Line[].LinkedTxn via a shared recordExternalPayment service refactored out of PaymentService.recordPaymentFromWebhook (Stripe behavior unchanged). Idempotency/echo-suppression via payment mapping rows (alga_entity_type: 'invoice_payment'). Payment edits reverse-and-reapply; deletions write payment_reversal and recompute status. Unmapped invoice, currency mismatch → exceptions. Unapplied amounts → cycle stats only. Status flip uses a computeBalanceDue helper that matches current behavior (slice 2 swaps its internals for the credit reshape).

5.3 Invoice drift detection

Deliver snapshots exported total alongside the existing sync token in mapping metadata. Inbound invoice changes with a moved sync token compare totals / void state / doc number; material drift sets sync_status: 'drift' and files an exception with both versions and two actions: re-export (sparse update QBO to Alga's truth) or accept (refresh snapshot). Balance-only movement is not drift. Unmapped QBO invoices are counted, not imported.

5.4 Auto-export on finalize

finalizeInvoice enqueues export_invoice when a realm is connected and the tenant's auto-sync setting is on (default off until slice 1 is validated live, then on). The cycle groups pending ops into one scheduled batch through the existing validate→transform→deliver pipeline; validation failures become inbox exceptions. Manual batches mark matching ops done.

5.5 Exceptions & notifications

New system task definitions (folding in the unwired qbo_mapping_error): accounting_sync_drift, accounting_sync_unmapped_payment, accounting_sync_export_error, accounting_connection_expired. One open task per entity+type; cycles update rather than duplicate. Notifications (internal + email, to users with billing_settings update): connection expired/auth failure immediately; token expiry at 14/7/2 days; per-cycle summary only when new exceptions appeared.

5.6 UI

• Invoice sync badge (list + detail; InvoiceTaxSourceBadge pattern) fed by mapping ledger + ops queue; tooltip with QBO doc number, last-synced time, environment-aware deep link; detail actions Sync now / View in QuickBooks.
• Settings health panel in QboIntegrationSettings: last cycle result, next run, pending/exception/drift counts (deep-linked to inbox), token expiry countdown, Sync Now, auto-sync toggle.

6. Data model & API notes

• New tables accounting_sync_cycles, accounting_sync_operations (columns in design.md); Citus-distributed on tenant like the accounting_export_* tables.
• tenant_external_entity_mappings gains payment mappings (no schema change; new alga_entity_type value) and the exported-total metadata snapshot.
• accounting_export_batches gains an origin discriminator (manual | scheduled).
• Tenant settings: auto-sync flag (+ slice-4 placeholders deferred).
• QBO API surface: ChangeDataCapture endpoint added to QboClientService; no other new external calls in slice 1.

7. Risks & open questions

• scheduleRecurringJob coerces intervals to 24h — use the short-interval path or fix the coercion (see SCRATCHPAD gotchas).
• Payment reverse-and-reapply must be transactional per payment; partial application crashes mid-cycle must not double-apply (idempotency tests cover this).
• Refactoring recordPaymentFromWebhook touches the live Stripe path — regression risk is mitigated by keeping its tests green and behavior byte-identical.
• Open: exact deep-link URL format for QBO sandbox vs production (resolve during implementation; environment is already known per connection).

8. Acceptance criteria / definition of done

• All slice-1 features in features.json implemented; automated tests in tests.json (mode automated) green; existing Stripe payment and Xero suites unaffected.
• Live Intuit-sandbox smoke (mode live-smoke in tests.json) executed and passing: connect → finalize → auto-export within a cycle → pay in QBO → Alga flips paid → edit payment → amounts follow → delete payment → reversal → drift (edit invoice total in QBO) → exception with working re-export → token alert fires when expiry forced.
• Auto-sync default flipped on only after the smoke passes.

9. Later slices (planned separately)

Each later slice has its own full plan: ../2026-06-11-qbo-phase2-slice2-credits-voids/, ../2026-06-11-qbo-phase2-slice3-onboarding/, ../2026-06-11-qbo-phase2-slice4-polish/.

• Slice 2 — Credits & voids: credit reshape (immutable totals + backfill, invoice_type, CM- numbering, balance-due read-site audit incl. Stripe payment-link amount), CreditMemo export, apply_credit zero-dollar Payment linkage, voidInvoice action + QBO void propagation, delete-blocking.
• Slice 3 — Onboarding: customer mapping tab (getQboCustomers), first-connect reconciliation wizard (customers → historical invoice matching without export → go-live cutoff).
• Slice 4 — Polish: Stripe payments pushed to QBO (deposit account picker via getQboAccounts), class/department tracking via mapping metadata + tenant defaults, multi-realm UX, optional Intuit webhooks for hosted latency.