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

# PRD: QBO Closed-Loop Sync — Slice 4: Payments Out, Class Tracking, Multi-Realm

- **Status:** Draft
- **Owner:** Robert Isaacs
- **Created:** 2026-06-11
- **Design:** `../2026-06-11-qbo-phase2-closed-loop/design.md`
- **Depends on:** Slice 1 (engine, ops queue, payment mapping/echo suppression); slice 2's `record_payment`-adjacent adapter work is independent

## 1. Problem statement & user value

Three remaining asymmetries after slices 1–3. Client-portal Stripe payments
land in Alga but not in QBO, so the bookkeeper re-keys them (or the books
disagree) — the one direction of payment flow still manual. MSPs that segment
their P&L by class or location in QBO get invoices with no `ClassRef`/
`DepartmentRef`, making the integration useless for their reporting. And
tenants with more than one QBO company can connect both but can only operate
the default from the UI.

## 2. Goals

- Stripe/portal payments recorded in Alga appear in QBO as `Payment` objects
  against the right customer and invoice, deposited to a tenant-configured
  account, within one cycle.
- Exported invoice lines carry `ClassRef` (per item mapping, falling back to
  a tenant default) and invoices carry `DepartmentRef` (tenant default).
- Multi-realm tenants can see all connections, switch the default, and pick
  a realm in the batch dialog and wizard.

## 3. Non-goals

- Intuit webhooks (excluded by decision 2026-06-11; plan separately if
  polling latency ever becomes a real complaint).
- Manual payment entry in Alga (no such action exists; when one is added it
  should ride the same `record_payment` op).
- Per-client or per-invoice class/department overrides beyond the item
  mapping metadata (tenant default + per-item is the v1 granularity).
- Prepayment → QBO unapplied-payment mapping (still unscheduled).
- Per-realm divergent mappings UI beyond what slice 1 already scopes by realm.

## 4. Personas & primary flows

- **Client (portal):** pays an invoice by card; minutes later the bookkeeper
  sees a QBO Payment with the Stripe reference in Undeposited Funds (or the
  configured account) — no re-keying, no unexplained paid invoice.
- **MSP billing admin (class tracking):** sets a default class "Managed
  Services" and overrides per item where needed; QBO P&L by class works.
- **MSP billing admin (two companies):** connects both realms, makes the
  right one default, and routes the occasional batch to the second company
  from the batch dialog.

## 5. Functional scope

### 5.1 Alga-originated payments to QBO

- Producer: the Stripe success path in `recordExternalPayment` (provider
  `stripe`) enqueues `record_payment` when the tenant has a connected realm
  and the invoice is mapped; unmapped invoice → op is skipped with a stat
  (not an exception — the invoice may predate go-live).
- Cycle execution: create a QBO `Payment` (CustomerRef from the client
  mapping, `Line` linking the mapped invoice with the paid amount,
  `PaymentRefNum` = Stripe reference, `DepositToAccountRef` from settings).
  The payment mapping row is written at push time — slice 1's echo
  suppression makes the next CDC poll a no-op.
- `getQboAccounts` server action (account list filtered to valid deposit
  targets) feeding a deposit-account picker in QBO settings; unset →
  *Undeposited Funds* resolved at delivery time.
- Failures (deleted invoice in QBO, account invalid) file
  `accounting_sync_export_error` exceptions through the slice-1 framework.

### 5.2 Class & department tracking

- `getQboClasses` / `getQboDepartments` server actions (catalog pattern).
- Tenant defaults (class, department) configured in QBO settings via pickers;
  stored as tenant settings.
- Item mapping metadata accepts `classId`; the mapping dialog's JSON editor
  documents it and the items tab shows a class column when set.
- Invoice transform: per-line `SalesItemLineDetail.ClassRef` from item
  mapping metadata, else tenant default class, else omitted; header
  `DepartmentRef` from tenant default, else omitted. CreditMemos (slice 2)
  get the same treatment.

### 5.3 Multi-realm UX

- Explicit `default_realm` tenant setting consumed by `getDefaultQboRealmId`
  (replacing first-stored-key ordering); *make default* action on the
  settings connection list, which now renders one row per realm
  (company name, status, last cycle).
- Batch creation dialog and the slice-3 wizard show a realm picker only when
  more than one realm is connected.
- Cycle scheduling registers per realm (slice 1 keyed it per tenant×realm
  already; registration now enumerates realms on connect/disconnect).
- Realm-scoped surfaces (badges, health panel counts, mapping tabs) read the
  selected/default realm consistently; with one realm nothing changes.

## 6. Data model & API notes

- Tenant settings: `default_realm`, `deposit_account_ref`, `default_class_ref`,
  `default_department_ref`. No new tables.
- QBO API surface: Payment create, Account/Class/Department queries (all via
  `QboClientService`).

## 7. Risks & open questions

- Double-entry guard: if a tenant's bookkeeper ALSO records the same Stripe
  payout manually in QBO, CDC will deliver it as a new payment against an
  invoice that Alga already shows paid — the applier's idempotency makes the
  second application a no-op only if amounts align; overlapping different
  payments surface as an exception (already-paid invoice receiving new
  allocation). Verify this path in tests.
- QBO requires Payment currency to match the customer's; multi-currency
  tenants exercise the slice-1 currency-mismatch exception path.
- Realm enumeration on disconnect must deregister only that realm's cycle.

## 8. Acceptance criteria / definition of done

- Features implemented; automated tests green; slices 1–3 suites unaffected.
- Live sandbox smoke: portal Stripe payment appears as a QBO Payment with
  the Stripe reference in the configured account and does not echo back;
  class/department visible on a delivered QBO invoice; second sandbox
  company connected — default switch, realm-routed batch, and per-realm
  health all work.