PSA/docs/plans/2026-06-11-qbo-phase2-slice3-onboarding/PRD.md

PRD: QBO Closed-Loop Sync — Slice 3: Onboarding & Reconciliation

• Status: Draft
• Owner: Robert Isaacs
• Created: 2026-06-11
• Design: ../2026-06-11-qbo-phase2-closed-loop/design.md
• Depends on: Slice 1 (engine, payment applier, mapping ledger); benefits from slice 2 but does not require it

1. Problem statement & user value

Nearly every tenant connecting QBO connects to an established company file: customers, invoices, and payment history already live there. Today the integration auto-provisions customers by display name on first export — which duplicates "Acme Corporation" when Alga says "Acme Corp" — and offers no way to link existing QBO invoices, so a re-export of history would double-book it. Payments recorded before connecting never replay through CDC, so linked history would read unpaid in Alga forever.

This slice makes first connect safe and deliberate: explicit customer mapping with auto-match assistance, historical invoice linking without export, a one-time payment-status backfill for matched history, and a go-live cutoff that fences which invoices auto-sync.

2. Goals

• A customer mapping surface where every Alga client can be linked to an existing QBO customer, created in QBO on demand, or left for first-export auto-provision — with exact-name matches bulk-acceptable and fuzzy matches human-confirmed.
• A re-runnable first-connect wizard: customers → historical invoice matching (mappings written, nothing exported) → go-live cutoff.
• Matched historical invoices get a one-time payment backfill through recordExternalPayment, so their paid state and AR are correct from day one.
• The go-live cutoff guarantees connecting never sprays history into QBO: only invoices finalized after the cutoff auto-enqueue.

3. Non-goals

• Importing QBO customers as new Alga clients (link-only; creation flows Alga→QBO).
• Importing unmatched QBO invoices into Alga.
• Continuous two-way customer field sync (name/address propagation beyond the cached display name from slice 1).
• Multi-realm wizard flows (single/default realm this slice; realm picker arrives in slice 4).

4. Personas & primary flows

• MSP billing admin (new connection): completes OAuth, lands in the wizard. Accepts 40 exact customer matches in one click, reviews 6 fuzzy ones, links 200 historical invoices by doc number, opts into the payment backfill, sets go-live to today. First scheduled cycle exports nothing historical; the books simply agree.
• MSP billing admin (established connection): opens the Customers mapping tab to fix one mis-linked client, or re-runs the wizard from settings after a QBO file cleanup.

5. Functional scope

5.1 Customer mapping surface

• getQboCustomers server action (realm-scoped, cached like the existing catalog actions; EE + billing_settings read gated).
• A Customers tab in the live mapping manager — a bespoke component (the generic module pattern fits dropdown mappings; this needs match suggestions and per-row actions): each Alga client row shows its mapping state and offers link to existing (searchable QBO customer picker), create in QBO now (runs the company-sync adapter immediately), or leave.
• Auto-match: normalized display-name comparison (case, punctuation, whitespace, common suffixes like Inc/LLC folded). Exact matches → bulk-accept bar ("Accept N exact matches"); near matches → suggested but individually confirmed; everything else unmatched.
• Mapping writes go to tenant_external_entity_mappings (alga_entity_type: 'client', realm-scoped), the same rows the exporter's customer resolution already consults.

5.2 Reconciliation wizard

• Launches after the first successful OAuth connect (no completed-wizard record for the realm); re-runnable from QBO settings. Steps:
  1. Customers — embeds the mapping surface (5.1) in wizard chrome.
  2. Historical invoices — fetch QBO invoices (paged), candidate-match against Alga invoices by doc number + total + (when mapped) customer. Confident matches are listed for one-click bulk link: mapping rows written with sync-token/total snapshot, nothing exported. Ambiguous candidates (number collision, total mismatch) go to a review list and are never auto-linked. Includes the payment backfill option (default on): for each linked invoice, query its QBO payments once and apply through recordExternalPayment (skipping invoices already paid), giving history real payment records and correct status.
  3. Go-live cutoff — set auto_sync_start_date (default today): the slice-1 finalize producer only enqueues invoices finalized on/after this date. Existing unexported invoices before the cutoff remain manual-batch only.
• Wizard completion recorded per tenant×realm; settings shows completed/last-run state next to the re-run entry point.

6. Data model & API notes

• Tenant settings: auto_sync_start_date, wizard completion record (per realm). No new tables — match candidates are computed live so the wizard is naturally idempotent and re-runnable.
• Slice-1 producer gains the cutoff check (one condition).
• QBO API surface: Customer query (paged), Invoice query by date window (paged), Payment query by invoice — all read-only additions to QboClientService.

7. Risks & open questions

• Name normalization quality drives the wizard's first impression; ship the folding rules with table-driven tests and keep "exact" strict (normalized equality only — similarity scoring stays suggestion-tier).
• Payment backfill volume: a tenant with years of history triggers many Payment queries — run inside the wizard as a progress-reporting batch, not in the 15-minute cycle.
• Doc-number matching assumes Alga invoice numbers were used in QBO historically; where they weren't, matching legitimately finds nothing — the wizard must make "0 matches" a normal outcome, not an error.

8. Acceptance criteria / definition of done

• Features implemented; automated tests green; slice-1 suites unaffected.
• Live sandbox smoke against a pre-seeded QBO file (existing customers + invoices + payments): wizard links exact customers in bulk, links history without exporting, backfills paid status correctly, and a post-wizard finalize+cycle exports only the new invoice; re-running the wizard is a no-op.