fix(billing): surface subscription-past-due and cutoff-scheduled tenants in billing health (#514)

`getAtRiskTenants()` fetched a single population — `tenants.billing_status =
'past_due'` — so two of the three groups #493 §1.2 asked for were invisible:

- a tenant whose `platform_subscriptions.status` went past due without
  `tenants.billing_status` being synced never appeared, which is exactly the
  drift the epic wanted visible;
- a tenant over its plan limits with an `access_cutoff_at` scheduled by #494
  but healthy billing never appeared either, so the cutoff column could only
  ever hold a value for a tenant that was *also* past due.

Fetch the union of the three conditions and carry the `reasons` a tenant
qualified under through the pure layer, so the cases stay distinguishable
instead of collapsing into one undifferentiated list. PostgREST cannot express
a disjunction spanning two tables, hence three reads merged by tenant id
rather than a single `.or()`.

Also rank subscription rows deterministically (past_due > active > other, tie
broken by `updated_at` desc) instead of last-wins over an unordered list. To be
precise about severity: `platform_subscriptions` carries UNIQUE (tenant_id) and
every write path upserts on it, so a tenant cannot hold two rows today — this
closes a latent trap rather than a live miscount.

The metric cards keep counting past-due tenants only, so their meaning does not
silently change now that over-limit tenants are listed; scheduled cutoffs get
their own card, and the empty state no longer claims "no schools past-due" for
a list that is no longer only about payment.

Author: DPS0340

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

@@ -1,24 +1,39 @@
 import { getAtRiskTenants } from '@/app/actions/platform/billing-health'
+import type { AtRiskReason } from '@/lib/billing/billing-health'
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
 import { Badge } from '@/components/ui/badge'
 import { format } from 'date-fns'
 import {
   IconAlertTriangle,
   IconClockPause,
   IconCreditCardOff,
+  IconLockExclamation,
 } from '@tabler/icons-react'
 
+const REASON_LABELS: Record<AtRiskReason, string> = {
+  tenant_past_due: 'Past due',
+  subscription_past_due: 'Subscription past due',
+  access_cutoff_scheduled: 'Cutoff scheduled',
+}
+
 export default async function PlatformBillingHealthPage() {
   const atRisk = await getAtRiskTenants()
 
-  const manualTransfer = atRisk.filter((t) => t.paymentMethod === 'manual_transfer')
-  const stripeDunning = atRisk.filter((t) => t.paymentMethod !== 'manual_transfer')
+  // 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)
 
   const metricCards = [
     {
       title: 'Past-Due Schools',
-      value: String(atRisk.length),
+      value: String(pastDue.length),
       sub: 'Total schools currently behind on payment',
       icon: IconAlertTriangle,
       bg: 'bg-red-50 dark:bg-red-950/40',
@@ -40,18 +55,27 @@ export default async function PlatformBillingHealthPage() {
       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),
+      sub: 'Over plan limits — access pauses on the cutoff date',
+      icon: IconLockExclamation,
+      bg: 'bg-purple-50 dark:bg-purple-950/40',
+      iconColor: 'text-purple-600 dark:text-purple-400',
+    },
   ]
 
   return (
     <main className="flex-1 px-4 py-6 sm:px-6 lg:px-8" data-testid="platform-billing-health">
       <div className="mb-8">
         <h1 className="text-2xl font-bold tracking-tight">Billing Health</h1>
         <p className="text-sm text-muted-foreground mt-1">
-          Schools currently past-due, with their grace-period countdown to automatic downgrade.
+          Schools that are past-due or over their plan limits, with their countdown to automatic
+          downgrade or access cutoff.
         </p>
       </div>
 
-      <div className="mb-8 grid gap-3 sm:grid-cols-3" data-testid="billing-health-metrics">
+      <div className="mb-8 grid gap-3 sm:grid-cols-2 lg:grid-cols-4" data-testid="billing-health-metrics">
         {metricCards.map((card) => (
           <Card key={card.title} className="relative overflow-hidden">
             <CardContent className="p-5">
@@ -80,14 +104,17 @@ export default async function PlatformBillingHealthPage() {
         </CardHeader>
         <CardContent>
           {atRisk.length === 0 ? (
-            <p className="text-muted-foreground text-sm">No schools currently past-due.</p>
+            <p className="text-muted-foreground text-sm">
+              No schools are past-due or over their plan limits.
+            </p>
           ) : (
             <div className="overflow-x-auto">
               <table className="w-full text-sm">
                 <thead>
                   <tr className="border-b text-left text-[11px] uppercase tracking-wider text-muted-foreground">
                     <th className="pb-2 font-medium">School</th>
                     <th className="pb-2 font-medium">Plan</th>
+                    <th className="pb-2 font-medium">Reason</th>
                     <th className="pb-2 font-medium">Payment method</th>
                     <th className="pb-2 font-medium">Past due since</th>
                     <th className="pb-2 font-medium">Downgrades in</th>
@@ -99,6 +126,15 @@ export default async function PlatformBillingHealthPage() {
                     <tr key={t.tenantId} className="border-b last:border-0" data-testid="at-risk-row" data-tenant-id={t.tenantId}>
                       <td className="py-2.5 font-medium">{t.tenantName}</td>
                       <td className="py-2.5 capitalize text-muted-foreground">{t.plan || '—'}</td>
+                      <td className="py-2.5" data-testid="at-risk-reasons" data-reasons={t.reasons.join(' ')}>
+                        <div className="flex flex-wrap gap-1">
+                          {t.reasons.map((reason) => (
+                            <Badge key={reason} variant="secondary" className="text-[10px] font-normal">
+                              {REASON_LABELS[reason]}
+                            </Badge>
+                          ))}
+                        </div>
+                      </td>
                       <td className="py-2.5 text-muted-foreground">
                         {t.paymentMethod === 'manual_transfer' ? 'Manual transfer' : t.paymentMethod === 'stripe' ? 'Stripe' : '—'}
                       </td>

app/actions/platform/billing-health.ts

@@ -3,7 +3,11 @@
 import { createAdminClient } from '@/lib/supabase/admin'
 import { isSuperAdmin } from '@/lib/supabase/get-user-role'
 import { getCurrentUserId } from '@/lib/supabase/tenant'
-import { computeBillingHealth, type AtRiskTenant } from '@/lib/billing/billing-health'
+import {
+  computeBillingHealth,
+  type AtRiskReason,
+  type AtRiskTenant,
+} from '@/lib/billing/billing-health'
 
 async function verifySuperAdmin() {
   const userId = await getCurrentUserId()
@@ -12,36 +16,101 @@ async function verifySuperAdmin() {
   return userId
 }
 
+/**
+ * #514: "at risk" is a union across two tables, which PostgREST cannot express
+ * as a single `.or()`. Three reads, merged by tenant id:
+ *
+ *  1. `tenants.billing_status = 'past_due'`
+ *  2. tenants owning a `platform_subscriptions` row with `status = 'past_due'`
+ *     (drifts from #1 when only one side is synced)
+ *  3. `tenants.access_cutoff_at IS NOT NULL` (#494 scheduled a cutoff — the
+ *     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.
+ */
 export async function getAtRiskTenants(): Promise<AtRiskTenant[]> {
   await verifySuperAdmin()
   const admin = createAdminClient()
 
-  const { data: tenants } = await admin
-    .from('tenants')
-    .select('id, name, plan, access_cutoff_at')
-    .eq('billing_status', 'past_due')
+  const [
+    { data: pastDueTenants },
+    { 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),
+  ])
 
-  const tenantIds = (tenants || []).map((t) => t.id)
+  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')
+  }
+
+  // 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 { data: subscriptions } = tenantIds.length
     ? await admin
         .from('platform_subscriptions')
-        .select('tenant_id, payment_method, current_period_end, grace_period_end')
+        .select('tenant_id, status, payment_method, current_period_end, grace_period_end, updated_at')
         .in('tenant_id', tenantIds)
     : { data: [] }
 
   return computeBillingHealth(
-    (tenants || []).map((t) => ({
+    [...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,
     })),
     new Date(),
   )

lib/billing/billing-health.ts

@@ -1,7 +1,17 @@
 /**
  * Computes the "billing health" view for super admins: which tenants are
- * currently `past_due` and how much runway they have before an automatic
- * downgrade to free.
+ * at risk and how much runway they have before an automatic downgrade to
+ * free.
+ *
+ * #514: "at risk" is a union of three populations, not just one. A tenant
+ * qualifies when `tenants.billing_status = 'past_due'`, **or** it has a
+ * `platform_subscriptions` row with `status = 'past_due'` (the two can drift
+ * apart, and the sub-only case used to be invisible here), **or** it has an
+ * `access_cutoff_at` scheduled by #494 — an over-limit tenant that is paying
+ * on time never showed up at all, so the cutoff column could only ever hold
+ * a value for a tenant that was *also* past due. Each row carries the
+ * `reasons` it qualified under; a tenant can qualify under several, and
+ * collapsing that would hide exactly the drift this view exists to surface.
  *
  * Two past-due paths write `tenants.billing_status = 'past_due'`, and they
  * carry different amounts of information:
@@ -20,18 +30,33 @@
 
 const DAY_MS = 24 * 60 * 60 * 1000
 
+/** Why a tenant appears in the at-risk list. A tenant may qualify under several. */
+export type AtRiskReason =
+  | 'tenant_past_due'
+  | 'subscription_past_due'
+  | 'access_cutoff_scheduled'
+
+const REASON_ORDER: AtRiskReason[] = [
+  'tenant_past_due',
+  'subscription_past_due',
+  'access_cutoff_scheduled',
+]
+
 export interface AtRiskTenantInput {
   tenantId: string
   tenantName: string
   plan: string | null
   accessCutoffAt: string | null
+  reasons: AtRiskReason[]
 }
 
 export interface PastDueSubscriptionInput {
   tenantId: string
+  status: string | null
   paymentMethod: string | null
   currentPeriodEnd: string | null
   gracePeriodEnd: string | null
+  updatedAt: string | null
 }
 
 export interface AtRiskTenant {
@@ -46,6 +71,44 @@ export interface AtRiskTenant {
   /** True when there is no fixed downgrade date to report (Stripe-managed dunning). */
   isEstimate: boolean
   accessCutoffAt: string | null
+  /** Which of the three at-risk conditions this tenant met, in a stable order. */
+  reasons: AtRiskReason[]
+}
+
+/**
+ * Ranks two subscription rows for the same tenant; higher wins.
+ *
+ * `platform_subscriptions` carries `UNIQUE (tenant_id)` today and every write
+ * path upserts on it, so a tenant cannot actually hold two rows — but the old
+ * plain `.set()` over an unordered list meant that if the constraint were ever
+ * relaxed (per-plan history, say), a stale `canceled` row could donate its
+ * `payment_method` and `grace_period_end`, and therefore its countdown, to the
+ * dashboard. Ranking explicitly costs nothing and removes the trap.
+ */
+function subscriptionRank(sub: PastDueSubscriptionInput): number {
+  if (sub.status === 'past_due') return 2
+  if (sub.status === 'active') return 1
+  return 0
+}
+
+function isMoreRelevantSubscription(
+  candidate: PastDueSubscriptionInput,
+  incumbent: PastDueSubscriptionInput,
+): boolean {
+  const candidateRank = subscriptionRank(candidate)
+  const incumbentRank = subscriptionRank(incumbent)
+  if (candidateRank !== incumbentRank) return candidateRank > incumbentRank
+
+  const candidateUpdated = candidate.updatedAt ? new Date(candidate.updatedAt).getTime() : null
+  const incumbentUpdated = incumbent.updatedAt ? new Date(incumbent.updatedAt).getTime() : null
+  if (candidateUpdated === null && incumbentUpdated === null) return false
+  if (incumbentUpdated === null) return true
+  if (candidateUpdated === null) return false
+  return candidateUpdated > incumbentUpdated
+}
+
+function normalizeReasons(reasons: AtRiskReason[]): AtRiskReason[] {
+  return REASON_ORDER.filter((reason) => reasons.includes(reason))
 }
 
 export function computeBillingHealth(
@@ -55,7 +118,10 @@ export function computeBillingHealth(
 ): AtRiskTenant[] {
   const subByTenant = new Map<string, PastDueSubscriptionInput>()
   for (const sub of subscriptions) {
-    subByTenant.set(sub.tenantId, sub)
+    const incumbent = subByTenant.get(sub.tenantId)
+    if (!incumbent || isMoreRelevantSubscription(sub, incumbent)) {
+      subByTenant.set(sub.tenantId, sub)
+    }
   }
 
   const results = tenants.map((tenant) => {
@@ -79,6 +145,7 @@ export function computeBillingHealth(
       daysUntilDowngrade,
       isEstimate: !isManualTransfer,
       accessCutoffAt: tenant.accessCutoffAt,
+      reasons: normalizeReasons(tenant.reasons),
     }
   })