alldigital/PSA
2
0
Fork 0
Code Issues Pull Requests Actions 14 Packages Projects Releases Wiki Activity
PSA/docs/plans/2026-06-11-qbo-phase2-slice3-onboarding/SCRATCHPAD.md
Hermes 284313f908
Some checks are pending
Bidi Control Character Guard / bidi-control-guard (push) Waiting to run
Details
Circular Dependency Check / Check for new circular dependencies (push) Waiting to run
Details
Citus Migration Smoke / Combined migrations on single-node Citus (push) Waiting to run
Details
E2E Fresh Install Tests / fresh-install-e2e (push) Waiting to run
Details
ext-v2 guardrails / Run ext-v2 guard and ESLint (push) Waiting to run
Details
Integration Tests / Check for relevant changes (push) Waiting to run
Details
Integration Tests / ${{ (github.event_name == 'schedule' || github.event.inputs.suite == 'full') && 'Full integration suite' || 'Tier-1 integration subset' }} (push) Blocked by required conditions
Details
Mobile checks / Mobile lint + typecheck (push) Waiting to run
Details
Mobile checks / Mobile unit tests (push) Waiting to run
Details
Mobile checks / Mobile dependency audit (report) (push) Waiting to run
Details
Mobile checks / Mobile reproducibility checks (push) Waiting to run
Details
Secrets guard (env backups) / Ensure no tracked env backup files (push) Waiting to run
Details
Temporal Readiness / fast-readiness (push) Waiting to run
Details
Temporal Readiness / docker-parity (push) Waiting to run
Details
TypeScript Type Check / Nx affected typecheck (push) Waiting to run
Details
Unit Tests / Skipped-test budget (push) Waiting to run
Details
Unit Tests / Nx affected unit tests (push) Waiting to run
Details
Unit Tests / Server unit coverage (informational) (push) Waiting to run
Details
Validate Tenant Management Schema / Check for relevant changes (push) Waiting to run
Details
Validate Tenant Management Schema / Validate Tenant Management Schema (push) Blocked by required conditions
Details
EE Workflows Build Guard / ee-workflows-build-guard (push) Waiting to run
Details
Initial import of AlgaPSA codebase from PSA server 
Excluded: .git, node_modules, secrets/, compose.env, assemblyscript tgz

Source: /opt/alga-psa on psa.joliet.tech
2026-06-22 16:12:17 -05:00

3.2 KiB
Raw Permalink Blame History

SCRATCHPAD — QBO Slice 3: Onboarding & Reconciliation

Decisions

  • 2026-06-11 — One-time payment backfill for wizard-matched invoices (user-confirmed). The sync cursor starts at connect, so pre-connect payments never replay via CDC; without backfill, linked history reads unpaid forever. Backfill runs in the wizard as a progress batch (not in the 15-min cycle), applies through recordExternalPayment, skips already-paid invoices.
  • Link-only customer import: QBO customers are never turned into new Alga clients; creation flows Alga→QBO only.
  • "Exact match" = strict normalized equality; similarity scoring is suggestion-tier only and always human-confirmed.
  • Match candidates computed live, no wizard-session tables → wizard is idempotent and re-runnable by construction.

Key file paths

  • Live mapping manager to host the Customers tab: packages/integrations/src/components/qbo/QboLiveMappingManager.tsx
  • Catalog action pattern to mirror for getQboCustomers: packages/integrations/src/actions/qboActions.ts (getQboItems et al.)
  • Company auto-provision path the mapping must take precedence over: packages/billing/src/services/companySync/adapters/quickBooksCompanyAdapter.ts
    • AccountingMappingResolver.ensureCompanyMapping
  • Finalize producer to gain the cutoff check: slice-1 hook in packages/billing/src/actions/invoiceModification.ts
  • Payment landing service (from slice 1): recordExternalPayment

Gotchas

  • QBO query pagination: 1000-row max per query; customer and invoice fetches must page (STARTPOSITION/MAXRESULTS).
  • Wizard payment backfill can be hundreds of Payment queries on big files — batch with progress UI, rate-limit politely (QBO throttles ~500 req/min).
  • Historical invoices may carry doc numbers QBO de-duplicated or altered; total+customer agreement is what makes a match "confident".
  • excludeSyncedInvoices in the export selector keys off mapping presence — verify linked-without-export rows are treated as synced.

Implementation notes (built 2026-06-11)

  • All onboarding UI lives in packages/billing/src/components/accounting (QboCustomerMappingPanel, QboOnboardingWizard + Entry) and reaches QboIntegrationSettings via a second slot (onboardingSlot) threaded from SettingsPage — same cycle-avoidance as the health panel. The customer mapping surface is therefore NOT a 4th live-mapping tab; it renders inside the wizard and the connection-card slot (deviation from PRD §5.1 framing, same capability).
  • Payment backfill reuses applyExternalPaymentChange with synthetic change objects, so backfilled history gets identical mappings/idempotency/status flips as the live pull; payments are fetched once per distinct customer.
  • Wizard completion state per realm under tenant_settings.settings.accountingSync.onboarding.
  • F015 (go-live cutoff in the producer) was already shipped in slice 1.
  • Deferred to DB env / live smoke: T007 (link-without-export exclusion uses excludeSyncedInvoices mapping presence — code-audited), T011 (DB-backed wizard integration), T012-T015 (sandbox smoke).
  • Pre-existing billing-suite failures (14, DB-dependent) verified unchanged via git-stash baseline by the server agent.