Plaid renewal auto-seed: prior contract → v2 quote

When a renewal opp lands for Plaid Test Org, auto-seed a v2 quote from the prior CPQ contract and light up the "previous price" + "previous usage" columns — no rep button, no flag.

1. Why this exists

2. End-to-end flow

Step through the lifecycle below. Each step lights up the nodes responsible for it; the rest dim to context.

3. Three fixes, one shape

4. The gate (why Plaid prod is safe)

There are two Plaid orgs in the system. The PR introduces isPlaidV2OrgName specifically because the legacy isPlaidOrgName matches both — and matching prod would seed v2 quotes on an org that's still served by v1.

5. The dispatch — jobId, retries, race guard

The listener does only Postgres reads + a dispatch. Salesforce reads stay inside the BullMQ job, off the request path. Three details in the dispatch call matter:

await _testHooks.dispatch(
  'dealops2RenewalInit',
  { organizationId, userId: opp.userId, opportunityV2Id: opp.id, sfdcOpportunityId: opp.crmId },
  {
    jobId: `dealops2RenewalInit-${opp.id}`,   // deterministic; '-' not ':' (BullMQ reserves :)
    removeOnFail:     { age: 3600 },            // retry on next CRM sync after 1h
    removeOnComplete: { age: 3600 },            // no-op seeds (prior quote missing) also unblock after 1h
  },
);

6. The snapshot — atomic capture, read-time fallback

The snapshot has to be written in the same insert as the quote. Otherwise a follow-up write could fail and leave the listener's dedupe guard pointing at a snapshot-less quote forever. CpqImportService threads it all the way down to repository.create.

// quote.get
const info = await getAmendmentInfo(oppId);
// info.priorProductsFull === []
// for Plaid renewals (no v2
// DealGroup to walk)
return { ...info, ... };

const raw = await getAmendmentInfo(oppId);
const snap = result.priorContractSnapshot;
const info = applyPriorContractSnapshot(raw, snap);

// Inert if:
//  - snap is null / no products
//  - raw.priorProductsFull non-empty
//    (walk wins → amendments unchanged)

What's in the snapshot

7. Previous usage — billed actuals, not QLIs

Why the snapshot needs its own usage capture rather than reading SBQQ__Quantity__c off the prior quote:

The aggregation is deliberately split into pure helpers + a thin IO wrapper, so the date math and averaging are unit-testable without a SalesforceAPI stub:

// trailing 6 full months, anchored to month-ends
computeUsageWindows(now) → { startDate, endDate, threeMonthsBoundary }

// rows split on the boundary; averaged per v2 productSpecId
buildPriorUsageData({ records, codeToSpecId, now }) → {
  productUsageLast3Months: { startDate, endDate, usage, averageMonthlyMinimumTrueUp },
  productUsage3to6Months:  { startDate, endDate, usage, averageMonthlyMinimumTrueUp },
}

Tier → spec dedupe

One subtle v2 difference from v1: several SF ProductCodes can resolve to the same umbrella spec (tier children under one product). Without care, a single usage record would double-count. The fix counts a record once per resolved spec:

for (const record of records) {
  if (record.quantity__c === null) continue;
  const specIds = new Set<string>();                       // dedupe per record
  for (const code of mapMrrRecordToProductCodes(record)) {
    const specId = codeToSpecId.get(code);
    if (specId) specIds.add(specId);
  }
  for (const specId of specIds) {
    quantitiesBySpec.get(specId) ?? quantitiesBySpec.set(specId, []);
    quantitiesBySpec.get(specId)!.push(record.quantity__c);
  }
}

8. The renewal signal — snapshot ⇒ isRenewal

One read-path subtlety: when the snapshot fallback fires, quote.get also flips isRenewal = true:

// trpc/router/pricingQuote/get.ts
if (hasSnapshotFallback) {
  isRenewal = true;
}

The presence of a snapshot is an authoritative renewal signal — it's only ever written by the renewal-init import. This matters because CRM opp-types like "Auto Renewal" don't literally contain "Renewal" in every comparison v2 makes, and treating the quote as an amendment would clamp product end-dates to the prior contract's end. Renewal = new term, fresh dates.

9. FE — reading the new fields

Everything comes back from the existing trpc.pricingQuotes.get query. No new endpoint, no new request. For non-renewal / non-Plaid quotes the fields come back null / empty, so call sites can read them unconditionally.

const snap  = pricingQuote.priorContractSnapshot;   // null unless renewal-seeded
const usage = snap?.usageDataForRenewal;            // null if no usage captured

usage?.productUsageLast3Months;
//   { startDate, endDate,
//     usage: Record<productSpecId, number>,        // avg MONTHLY billed quantity
//     averageMonthlyMinimumTrueUp: number }

const priorAvgQty = usage?.productUsageLast3Months.usage[row.productSpecId];
snap?.minimumCommitment;                             // MinimumCommitmentInput | null

UsageTrendCell — the new visual

A 58×26 SVG trend glyph per product row. State resolution is small and deliberate:

10. What it doesn't change

11. Risks / rollback

12. Test coverage

13. Verify locally

1. Run migrations — the priorContractSnapshot migration is in this PR.
2. On Plaid Test Org, create (or re-sync) a renewal-type opp with a prior CPQ contract in Salesforce.
3. Confirm the quote is auto-seeded with prior products. Pricing table shows previous price (incl. tiered/ramped) and the usage trend.
4. Inspect priorContractSnapshot on the row, or in the pricingQuotes.get response: products, minimumCommitment, usageDataForRenewal, dates.
5. Edit the seeded quote — "previous price" does not move.
6. Isolation: non-Plaid orgs and non-renewal Plaid deals get no auto-seed.