fix(billing): gate past-due fields on past-due reasons, flatten at-risk fetch (#514)

Builds on @DPS0340's union fetch (#523) with the review follow-ups.

Widening the at-risk population to `access_cutoff_at IS NOT NULL` admits
tenants whose billing is healthy, but `computeBillingHealth` still derived
`pastDueSince`, `graceEndsAt`, `daysUntilDowngrade` and `isEstimate` from
`payment_method` alone. `downgradeTenantToFree()` sets status='canceled'
without clearing `grace_period_end` and then schedules the very cutoff that
lists the tenant, so an already-downgraded school rendered "Past due since
<old date>" with a large negative countdown — and sorted above the schools
that still had a downgrade to avert. Those fields are now gated on the
tenant actually being past due, and the no-countdown tail is ordered by
soonest cutoff instead of arbitrarily.

Also:
- `mergeAtRiskTenants()` extracted as a pure, exported function so the union
  itself is unit-testable without a database.
- Fetch flattened from four sequential round-trips to two: the past-due
  subscription read now takes the full column set, which makes the follow-up
  tenant fetch independent of the subscription fetch. Safe to feed both
  subscription lists to `computeBillingHealth` because it ranks duplicates
  rather than taking the last one. The super-admin check stays ahead of the
  reads on purpose.
- Row mapping goes through typed helpers instead of `as TenantRow[]`, so a
  drifting select list fails typecheck.
- `accessCutoffActive` distinguishes a cutoff already in force ("Access
  paused") from a scheduled one, and the metric cards count in one pass.

Co-Authored-By: Jiho Lee <optional.int@kakao.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJDnXnWmdBDTX33bvTx62K

Author: 3 people

app/[locale]/platform/billing-health/page.tsx

@@ -16,48 +16,67 @@ const REASON_LABELS: Record<AtRiskReason, string> = {
   access_cutoff_scheduled: 'Cutoff scheduled',
 }
 
+function reasonLabel(reason: AtRiskReason, cutoffActive: boolean): string {
+  // A cutoff date in the past means access is already paused, not pending.
+  if (reason === 'access_cutoff_scheduled' && cutoffActive) return 'Access paused'
+  return REASON_LABELS[reason]
+}
+
 export default async function PlatformBillingHealthPage() {
   const atRisk = await getAtRiskTenants()
 
   // The metric cards deliberately keep counting past-due tenants only, so the
   // numbers do not silently change meaning now that #514 also lists tenants
   // that are merely over their plan limits. Cutoffs get their own card.
-  const pastDue = atRisk.filter(
-    (t) => t.reasons.includes('tenant_past_due') || t.reasons.includes('subscription_past_due'),
-  )
-  const manualTransfer = pastDue.filter((t) => t.paymentMethod === 'manual_transfer')
-  const stripeDunning = pastDue.filter((t) => t.paymentMethod !== 'manual_transfer')
-  const cutoffScheduled = atRisk.filter((t) => t.reasons.includes('access_cutoff_scheduled'))
-  const urgent = manualTransfer.filter((t) => t.daysUntilDowngrade !== null && t.daysUntilDowngrade <= 3)
+  // Counted in one pass — five chained .filter() calls over the same list was
+  // five allocations for four numbers.
+  const counts = { pastDue: 0, manualTransfer: 0, stripeDunning: 0, cutoffScheduled: 0, urgent: 0 }
+  for (const t of atRisk) {
+    const isPastDue =
+      t.reasons.includes('tenant_past_due') || t.reasons.includes('subscription_past_due')
+    if (isPastDue) {
+      counts.pastDue++
+      if (t.paymentMethod === 'manual_transfer') {
+        counts.manualTransfer++
+        if (t.daysUntilDowngrade !== null && t.daysUntilDowngrade <= 3) counts.urgent++
+      } else {
+        counts.stripeDunning++
+      }
+    }
+    if (t.reasons.includes('access_cutoff_scheduled')) counts.cutoffScheduled++
+  }
 
   const metricCards = [
     {
       title: 'Past-Due Schools',
-      value: String(pastDue.length),
+      value: String(counts.pastDue),
       sub: 'Total schools currently behind on payment',
       icon: IconAlertTriangle,
       bg: 'bg-red-50 dark:bg-red-950/40',
       iconColor: 'text-red-600 dark:text-red-400',
     },
     {
       title: 'Manual-Transfer Grace Running',
-      value: String(manualTransfer.length),
-      sub: urgent.length > 0 ? `${urgent.length} downgrading within 3 days` : 'None expiring imminently',
+      value: String(counts.manualTransfer),
+      sub:
+        counts.urgent > 0
+          ? `${counts.urgent} downgrading within 3 days`
+          : 'None expiring imminently',
       icon: IconClockPause,
       bg: 'bg-amber-50 dark:bg-amber-950/40',
       iconColor: 'text-amber-600 dark:text-amber-400',
     },
     {
       title: 'Stripe Dunning In Progress',
-      value: String(stripeDunning.length),
+      value: String(counts.stripeDunning),
       sub: 'Downgrade timing controlled by Stripe, not this app',
       icon: IconCreditCardOff,
       bg: 'bg-blue-50 dark:bg-blue-950/40',
       iconColor: 'text-blue-600 dark:text-blue-400',
     },
     {
       title: 'Access Cutoff Scheduled',
-      value: String(cutoffScheduled.length),
+      value: String(counts.cutoffScheduled),
       sub: 'Over plan limits — access pauses on the cutoff date',
       icon: IconLockExclamation,
       bg: 'bg-purple-50 dark:bg-purple-950/40',
@@ -130,7 +149,7 @@ export default async function PlatformBillingHealthPage() {
                         <div className="flex flex-wrap gap-1">
                           {t.reasons.map((reason) => (
                             <Badge key={reason} variant="secondary" className="text-[10px] font-normal">
-                              {REASON_LABELS[reason]}
+                              {reasonLabel(reason, t.accessCutoffActive)}
                             </Badge>
                           ))}
                         </div>

app/actions/platform/billing-health.ts

@@ -5,8 +5,10 @@ import { isSuperAdmin } from '@/lib/supabase/get-user-role'
 import { getCurrentUserId } from '@/lib/supabase/tenant'
 import {
   computeBillingHealth,
-  type AtRiskReason,
+  mergeAtRiskTenants,
   type AtRiskTenant,
+  type AtRiskTenantRow,
+  type PastDueSubscriptionInput,
 } from '@/lib/billing/billing-health'
 
 async function verifySuperAdmin() {
@@ -16,6 +18,46 @@ async function verifySuperAdmin() {
   return userId
 }
 
+const TENANT_SELECT = 'id, name, plan, access_cutoff_at'
+const SUBSCRIPTION_SELECT =
+  'tenant_id, status, payment_method, current_period_end, grace_period_end, updated_at'
+
+/**
+ * Mapped through helpers rather than an `as` cast so a drifting select list
+ * fails `tsc` here instead of rendering blanks in production.
+ */
+function toTenantRow(row: {
+  id: string
+  name: string
+  plan: string | null
+  access_cutoff_at: string | null
+}): AtRiskTenantRow {
+  return {
+    tenantId: row.id,
+    tenantName: row.name,
+    plan: row.plan,
+    accessCutoffAt: row.access_cutoff_at,
+  }
+}
+
+function toSubscriptionInput(row: {
+  tenant_id: string
+  status: string | null
+  payment_method: string | null
+  current_period_end: string | null
+  grace_period_end: string | null
+  updated_at: string | null
+}): PastDueSubscriptionInput {
+  return {
+    tenantId: row.tenant_id,
+    status: row.status,
+    paymentMethod: row.payment_method,
+    currentPeriodEnd: row.current_period_end,
+    gracePeriodEnd: row.grace_period_end,
+    updatedAt: row.updated_at,
+  }
+}
+
 /**
  * #514: "at risk" is a union across two tables, which PostgREST cannot express
  * as a single `.or()`. Three reads, merged by tenant id:
@@ -27,6 +69,17 @@ async function verifySuperAdmin() {
  *     tenant may be paying perfectly well and simply be over its plan limits)
  *
  * Each contributes a reason, so the UI can keep the three cases apart.
+ *
+ * Two round-trips, not four. The past-due subscription read takes the full
+ * column set, so the rows belonging to subscription-only tenants are already
+ * in hand; that makes the follow-up `tenants` fetch for those ids independent
+ * of the subscription fetch for the tenants we already know about, and the two
+ * go out together. Feeding both subscription lists to `computeBillingHealth`
+ * is safe because it ranks duplicate rows rather than taking the last one.
+ *
+ * The auth check deliberately stays *before* the reads and is never folded
+ * into the `Promise.all` — a non-super-admin caller must not cause tenant
+ * billing data to be read at all.
  */
 export async function getAtRiskTenants(): Promise<AtRiskTenant[]> {
   await verifySuperAdmin()
@@ -37,81 +90,45 @@ export async function getAtRiskTenants(): Promise<AtRiskTenant[]> {
     { data: pastDueSubscriptions },
     { data: cutoffTenants },
   ] = await Promise.all([
-    admin
-      .from('tenants')
-      .select('id, name, plan, access_cutoff_at')
-      .eq('billing_status', 'past_due'),
-    admin
-      .from('platform_subscriptions')
-      .select('tenant_id')
-      .eq('status', 'past_due'),
-    admin
-      .from('tenants')
-      .select('id, name, plan, access_cutoff_at')
-      .not('access_cutoff_at', 'is', null),
+    admin.from('tenants').select(TENANT_SELECT).eq('billing_status', 'past_due'),
+    admin.from('platform_subscriptions').select(SUBSCRIPTION_SELECT).eq('status', 'past_due'),
+    admin.from('tenants').select(TENANT_SELECT).not('access_cutoff_at', 'is', null),
   ])
 
-  const reasonsByTenant = new Map<string, Set<AtRiskReason>>()
-  const addReason = (tenantId: string, reason: AtRiskReason) => {
-    const existing = reasonsByTenant.get(tenantId)
-    if (existing) existing.add(reason)
-    else reasonsByTenant.set(tenantId, new Set([reason]))
-  }
-
-  type TenantRow = { id: string; name: string; plan: string | null; access_cutoff_at: string | null }
-  const tenantById = new Map<string, TenantRow>()
-
-  for (const tenant of (pastDueTenants || []) as TenantRow[]) {
-    tenantById.set(tenant.id, tenant)
-    addReason(tenant.id, 'tenant_past_due')
-  }
-  for (const tenant of (cutoffTenants || []) as TenantRow[]) {
-    tenantById.set(tenant.id, tenant)
-    addReason(tenant.id, 'access_cutoff_scheduled')
-  }
+  const pastDueTenantRows = (pastDueTenants ?? []).map(toTenantRow)
+  const cutoffTenantRows = (cutoffTenants ?? []).map(toTenantRow)
+  const pastDueSubscriptionRows = (pastDueSubscriptions ?? []).map(toSubscriptionInput)
 
-  // Subscription-only past-due tenants have no row yet from either read above.
-  const subscriptionPastDueIds = [...new Set((pastDueSubscriptions || []).map((s) => s.tenant_id))]
-  for (const tenantId of subscriptionPastDueIds) {
-    addReason(tenantId, 'subscription_past_due')
-  }
-  const missingTenantIds = subscriptionPastDueIds.filter((id) => !tenantById.has(id))
-
-  if (missingTenantIds.length) {
-    const { data: extraTenants } = await admin
-      .from('tenants')
-      .select('id, name, plan, access_cutoff_at')
-      .in('id', missingTenantIds)
-    for (const tenant of (extraTenants || []) as TenantRow[]) {
-      tenantById.set(tenant.id, tenant)
-    }
-  }
-
-  const tenantIds = [...tenantById.keys()]
+  const knownTenantIds = new Set([
+    ...pastDueTenantRows.map((t) => t.tenantId),
+    ...cutoffTenantRows.map((t) => t.tenantId),
+  ])
+  const subscriptionPastDueTenantIds = [
+    ...new Set(pastDueSubscriptionRows.map((s) => s.tenantId)),
+  ]
+  // Subscription-only past-due tenants appear in neither read above.
+  const missingTenantIds = subscriptionPastDueTenantIds.filter((id) => !knownTenantIds.has(id))
 
-  const { data: subscriptions } = tenantIds.length
-    ? await admin
-        .from('platform_subscriptions')
-        .select('tenant_id, status, payment_method, current_period_end, grace_period_end, updated_at')
-        .in('tenant_id', tenantIds)
-    : { data: [] }
+  const [{ data: extraTenants }, { data: knownSubscriptions }] = await Promise.all([
+    missingTenantIds.length
+      ? admin.from('tenants').select(TENANT_SELECT).in('id', missingTenantIds)
+      : Promise.resolve({ data: [] as never[] }),
+    knownTenantIds.size
+      ? admin
+          .from('platform_subscriptions')
+          .select(SUBSCRIPTION_SELECT)
+          .in('tenant_id', [...knownTenantIds])
+      : Promise.resolve({ data: [] as never[] }),
+  ])
 
   return computeBillingHealth(
-    [...tenantById.values()].map((t) => ({
-      tenantId: t.id,
-      tenantName: t.name,
-      plan: t.plan,
-      accessCutoffAt: t.access_cutoff_at,
-      reasons: [...(reasonsByTenant.get(t.id) ?? [])],
-    })),
-    (subscriptions || []).map((s) => ({
-      tenantId: s.tenant_id,
-      status: s.status,
-      paymentMethod: s.payment_method,
-      currentPeriodEnd: s.current_period_end,
-      gracePeriodEnd: s.grace_period_end,
-      updatedAt: s.updated_at,
-    })),
+    mergeAtRiskTenants({
+      pastDueTenants: pastDueTenantRows,
+      cutoffTenants: cutoffTenantRows,
+      subscriptionPastDueTenantIds,
+      extraTenants: (extraTenants ?? []).map(toTenantRow),
+    }),
+    [...pastDueSubscriptionRows, ...(knownSubscriptions ?? []).map(toSubscriptionInput)],
     new Date(),
   )
 }