fix(billing): platform billing cleanup (#468) (#480)

* fix(billing): platform billing cleanup (#468)

Address the platform-billing correctness/consistency items from issue #468
(Phase 4 cleanup of epic #458):

- instructions_sent / payment_received were rendered in the UI but never
  written. Add a super-admin `sendPaymentInstructions` action (pending →
  instructions_sent + in-app notification to tenant admins) and advance a
  request to payment_received when the school uploads transfer proof, so the
  intermediate manual-flow states are actually reachable.
- forceTenantPlanChange updated tenants.plan + revenue_splits but left
  platform_subscriptions pointing at the old plan. It now syncs the
  subscription row atomically (updates plan_id on the existing row, cancels it
  when forcing to free, or creates a manual override row when none exists).
- Stripe checkout/portal success/cancel/return URLs hardcoded /en/. Thread the
  requester's locale (from the POST body, with a referer fallback) via a shared
  resolveRequestLocale helper, validated against the supported locale set.
- Surface the plan's current price next to the snapshotted request amount on
  the super-admin confirm view so price drift is visible at confirm time.

The hardcoded 10/90 split on cancellation (item 3) was already resolved on
master by lib/billing/downgrade-tenant.ts (reads the free plan's
transaction_fee_percent); verified, no change needed. The price snapshot itself
(item 5) already exists as platform_payment_requests.amount; only confirm-time
visibility was missing.

Pre-existing no-explicit-any lint errors in the touched files are not
introduced by this change (repo lint baseline is non-blocking; npm run build
passes clean).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PTd2ffE5QnJphufL8YD7KV

* fix(billing): make forced plan overrides indefinite so the expiry cron can't undo them

forceTenantPlanChange created its manual override row with a +1 month
current_period_end, which put it squarely in the path of the
expire-platform-subscriptions cron (#471): the school would get renewal
reminders for a payment it never requested, then be silently downgraded
back to free a month later. The reactivation branch had the same bug via
a stale period end on a previously-canceled row.

Every cron phase filters on `.not('current_period_end', 'is', null)`, so
a NULL period end is the natural "indefinite override" marker: the row is
never reminded, never lapses, never auto-downgrades. Keep a real period
only when reactivating a sub already on a live paid cycle; a school that
later pays via confirmManualPayment upserts a dated cycle over the row.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HveVmDShzscMQVQdd9LuDZ

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: guillermoscript

app/[locale]/dashboard/admin/billing/billing-dashboard-client.tsx

@@ -18,7 +18,7 @@ import {
   AlertDialogTitle,
 } from '@/components/ui/alert-dialog'
 import { IconExternalLink, IconRefresh, IconCreditCard, IconPhoto, IconClock, IconLoader2 } from '@tabler/icons-react'
-import { useTranslations } from 'next-intl'
+import { useTranslations, useLocale } from 'next-intl'
 import { uploadPaymentProof, requestManualRenewal, cancelSubscription } from '@/app/actions/admin/billing'
 
 interface BillingDashboardClientProps {
@@ -66,6 +66,7 @@ interface BillingDashboardClientProps {
 export function BillingDashboardClient({ status, paymentRequests }: BillingDashboardClientProps) {
   const router = useRouter()
   const t = useTranslations('dashboard.admin.billing.overview')
+  const locale = useLocale()
   const [portalLoading, setPortalLoading] = useState(false)
   const [renewalLoading, setRenewalLoading] = useState(false)
   const [switchLoading, setSwitchLoading] = useState(false)
@@ -76,7 +77,11 @@ export function BillingDashboardClient({ status, paymentRequests }: BillingDashb
   const handleManageBilling = async () => {
     setPortalLoading(true)
     try {
-      const response = await fetch('/api/stripe/billing-portal', { method: 'POST' })
+      const response = await fetch('/api/stripe/billing-portal', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ locale }),
+      })
       const data = await response.json()
       if (data.url) {
         window.location.href = data.url

app/[locale]/dashboard/admin/billing/upgrade/upgrade-page-client.tsx

@@ -66,7 +66,7 @@ export function UpgradePageClient({ plans, currentPlan, preselectedPlan, presele
       const response = await fetch('/api/stripe/checkout-session', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ planId, interval }),
+        body: JSON.stringify({ planId, interval, locale }),
       })
       const data = await response.json()
       if (data.url) {

app/[locale]/platform/billing/billing-actions.tsx

@@ -13,18 +13,33 @@ import {
 } from "@/components/ui/dialog"
 import { Textarea } from "@/components/ui/textarea"
 import { confirmManualPayment } from "@/app/actions/admin/billing"
-import { rejectManualPayment } from "@/app/actions/platform/plans"
+import { rejectManualPayment, sendPaymentInstructions } from "@/app/actions/platform/plans"
 
 interface Props {
   requestId: string
+  status: string
 }
 
-export function BillingActions({ requestId }: Props) {
+export function BillingActions({ requestId, status }: Props) {
   const router = useRouter()
   const [loadingConfirm, setLoadingConfirm] = useState(false)
   const [showRejectModal, setShowRejectModal] = useState(false)
   const [reason, setReason] = useState('')
   const [loadingReject, setLoadingReject] = useState(false)
+  const [loadingInstructions, setLoadingInstructions] = useState(false)
+
+  async function handleSendInstructions() {
+    setLoadingInstructions(true)
+    try {
+      await sendPaymentInstructions(requestId)
+      toast.success('Instructions marked as sent — school notified')
+      router.refresh()
+    } catch (e: any) {
+      toast.error(e.message)
+    } finally {
+      setLoadingInstructions(false)
+    }
+  }
 
   async function handleConfirm() {
     setLoadingConfirm(true)
@@ -60,6 +75,17 @@ export function BillingActions({ requestId }: Props) {
   return (
     <>
       <div className="flex items-center justify-end gap-2">
+        {status === 'pending' && (
+          <Button
+            size="sm"
+            variant="outline"
+            onClick={handleSendInstructions}
+            disabled={loadingInstructions}
+            data-testid="send-instructions-btn"
+          >
+            {loadingInstructions ? 'Sending…' : 'Send instructions'}
+          </Button>
+        )}
         <Button
           size="sm"
           onClick={handleConfirm}

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

@@ -25,7 +25,7 @@ export default async function PlatformBillingPage({
 
   let query = adminClient
     .from('platform_payment_requests')
-    .select('*, platform_plans(name, slug), tenants(name, slug)')
+    .select('*, platform_plans(name, slug, price_monthly, price_yearly), tenants(name, slug)')
     .order('created_at', { ascending: false })
     .limit(100)
 
@@ -89,7 +89,18 @@ export default async function PlatformBillingPage({
                 </tr>
               </thead>
               <tbody>
-                {(requests || []).map((req: any) => (
+                {(requests || []).map((req: any) => {
+                  // Item 5: `amount` is the price snapshotted at request time.
+                  // Surface the plan's *current* price so a super admin can see
+                  // if it drifted (e.g. the plan was re-priced before confirm).
+                  const currentPlanPrice =
+                    req.interval === 'yearly'
+                      ? req.platform_plans?.price_yearly
+                      : req.platform_plans?.price_monthly
+                  const priceDrifted =
+                    typeof currentPlanPrice === 'number' &&
+                    Number(currentPlanPrice) !== Number(req.amount)
+                  return (
                   <tr key={req.request_id} className="border-b last:border-0 transition-colors hover:bg-muted/40" data-testid="billing-request-row" data-request-id={req.request_id} data-status={req.status}>
                     <td className="px-4 py-3 font-medium">
                       {req.tenants?.name || req.tenant_id}
@@ -99,6 +110,15 @@ export default async function PlatformBillingPage({
                     </td>
                     <td className="px-4 py-3 text-right font-semibold tabular-nums">
                       {new Intl.NumberFormat('en-US', { style: 'currency', currency: req.currency || 'USD' }).format(req.amount)}
+                      {priceDrifted && (
+                        <span
+                          className="mt-0.5 block text-[10px] font-normal text-amber-600 dark:text-amber-500"
+                          data-testid="price-drift-note"
+                          title="The plan price changed after this request was created."
+                        >
+                          plan now {new Intl.NumberFormat('en-US', { style: 'currency', currency: req.currency || 'USD' }).format(currentPlanPrice)}
+                        </span>
+                      )}
                     </td>
                     <td className="px-4 py-3 capitalize text-muted-foreground">{req.interval}</td>
                     <td className="px-4 py-3">
@@ -125,11 +145,12 @@ export default async function PlatformBillingPage({
                     </td>
                     <td className="px-4 py-3 text-right">
                       {['pending', 'instructions_sent', 'payment_received'].includes(req.status) && (
-                        <BillingActions requestId={req.request_id} />
+                        <BillingActions requestId={req.request_id} status={req.status} />
                       )}
                     </td>
                   </tr>
-                ))}
+                  )
+                })}
                 {(!requests || requests.length === 0) && (
                   <tr>
                     <td colSpan={8} className="px-4 py-12 text-center text-sm text-muted-foreground">

app/actions/admin/billing.ts

@@ -628,9 +628,19 @@ export async function uploadPaymentProof(requestId: string, formData: FormData)
 
   const proofUrl = signedUrlData?.signedUrl || urlData.publicUrl
 
+  // Uploading proof advances the request to `payment_received` so a super
+  // admin can see the school has paid — unless it's already been
+  // confirmed/rejected, in which case the status is left untouched.
+  const advanceStatus =
+    request.status === 'pending' || request.status === 'instructions_sent'
+
   await adminClient
     .from('platform_payment_requests')
-    .update({ proof_url: proofUrl, updated_at: new Date().toISOString() })
+    .update({
+      proof_url: proofUrl,
+      ...(advanceStatus ? { status: 'payment_received' } : {}),
+      updated_at: new Date().toISOString(),
+    })
     .eq('request_id', requestId)
 
   revalidatePath('/dashboard/admin/billing')

app/actions/platform/plans.ts

@@ -121,6 +121,75 @@ export async function rejectManualPayment(requestId: string, reason: string) {
   return { success: true }
 }
 
+/**
+ * Super admin: mark bank-transfer instructions as sent for a manual payment
+ * request. Moves it `pending → instructions_sent` and notifies the tenant's
+ * admins in-app so the dead intermediate state is actually reachable.
+ */
+export async function sendPaymentInstructions(requestId: string) {
+  const userId = await verifySuperAdmin()
+  const adminClient = createAdminClient()
+
+  const { data: request } = await adminClient
+    .from('platform_payment_requests')
+    .select('request_id, tenant_id, status')
+    .eq('request_id', requestId)
+    .single()
+
+  if (!request) throw new Error('Request not found')
+  if (request.status !== 'pending') {
+    throw new Error('Instructions can only be sent for pending requests')
+  }
+
+  await adminClient
+    .from('platform_payment_requests')
+    .update({ status: 'instructions_sent', updated_at: new Date().toISOString() })
+    .eq('request_id', requestId)
+
+  // Best-effort in-app notification to the tenant's admins — never block the
+  // status change on a notification failure.
+  try {
+    const { data: adminUsers } = await adminClient
+      .from('tenant_users')
+      .select('user_id')
+      .eq('tenant_id', request.tenant_id)
+      .eq('role', 'admin')
+      .eq('status', 'active')
+
+    const adminIds = (adminUsers || []).map((u: { user_id: string }) => u.user_id)
+    if (adminIds.length > 0) {
+      const { data: notification } = await adminClient
+        .from('notifications')
+        .insert({
+          title: 'Bank transfer instructions sent',
+          content:
+            'Bank transfer instructions for your plan payment are on the way. Check your email, complete the transfer, then upload your proof of payment from the billing page.',
+          notification_type: 'info',
+          priority: 'normal',
+          target_type: 'user',
+          target_user_ids: adminIds,
+          status: 'sent',
+          sent_at: new Date().toISOString(),
+          created_by: userId,
+          tenant_id: request.tenant_id,
+        })
+        .select('id')
+        .single()
+
+      if (notification) {
+        await adminClient
+          .from('user_notifications')
+          .insert(adminIds.map((uid) => ({ notification_id: notification.id, user_id: uid })))
+      }
+    }
+  } catch (err) {
+    console.error('Failed to notify tenant admins about payment instructions:', err)
+  }
+
+  revalidatePath('/platform/billing')
+  return { success: true }
+}
+
 export async function forceTenantPlanChange(tenantId: string, planSlug: string) {
   await verifySuperAdmin()
   const adminClient = createAdminClient()
@@ -133,9 +202,11 @@ export async function forceTenantPlanChange(tenantId: string, planSlug: string)
 
   if (!plan) throw new Error('Plan not found')
 
+  const nowIso = new Date().toISOString()
+
   await adminClient
     .from('tenants')
-    .update({ plan: planSlug, updated_at: new Date().toISOString() })
+    .update({ plan: planSlug, updated_at: nowIso })
     .eq('id', tenantId)
 
   // Update revenue split
@@ -145,9 +216,85 @@ export async function forceTenantPlanChange(tenantId: string, planSlug: string)
       tenant_id: tenantId,
       platform_percentage: plan.transaction_fee_percent,
       school_percentage: 100 - plan.transaction_fee_percent,
-      updated_at: new Date().toISOString(),
+      updated_at: nowIso,
     }, { onConflict: 'tenant_id' })
 
+  // Keep platform_subscriptions in sync with the forced plan (issue #468).
+  // Previously this action changed tenants.plan + the split but left the
+  // subscription row pointing at the old plan, so the two disagreed after an
+  // override.
+  const { data: existingSub } = await adminClient
+    .from('platform_subscriptions')
+    .select('subscription_id, status, current_period_end')
+    .eq('tenant_id', tenantId)
+    .maybeSingle()
+
+  if (planSlug === 'free') {
+    // Free needs no active subscription — cancel any existing row so the
+    // subscription and the tenant's plan agree.
+    if (existingSub) {
+      await adminClient
+        .from('platform_subscriptions')
+        .update({
+          plan_id: plan.plan_id,
+          status: 'canceled',
+          canceled_at: nowIso,
+          updated_at: nowIso,
+        })
+        .eq('tenant_id', tenantId)
+    }
+  } else if (existingSub) {
+    // Point the existing subscription at the forced plan. Preserve the billing
+    // period only when the sub is on a live paid cycle (active with a future
+    // period end); otherwise — canceled/expired row, or a lapsed period —
+    // reactivating with the stale current_period_end would hand the row
+    // straight to the expire-platform-subscriptions cron (past_due, then
+    // auto-downgrade after grace), silently undoing the override. Clear the
+    // period instead so the override is indefinite, like the insert below.
+    const liveCycle =
+      existingSub.status === 'active' &&
+      existingSub.current_period_end != null &&
+      new Date(existingSub.current_period_end) > new Date()
+    await adminClient
+      .from('platform_subscriptions')
+      .update({
+        plan_id: plan.plan_id,
+        status: 'active',
+        updated_at: nowIso,
+        ...(liveCycle
+          ? {}
+          : {
+              current_period_end: null,
+              grace_period_end: null,
+              cancel_at_period_end: false,
+              canceled_at: null,
+            }),
+      })
+      .eq('tenant_id', tenantId)
+  } else {
+    // No subscription yet (e.g. tenant was on free): create a manual override
+    // row so the paid plan is backed by an active subscription.
+    //
+    // current_period_end stays NULL on purpose: a super-admin override is
+    // indefinite, not a one-month grant. The expire-platform-subscriptions
+    // cron filters every phase on `.not('current_period_end', 'is', null)`,
+    // so a NULL period end is never reminded, never lapses to past_due, and
+    // never auto-downgrades — the override holds until a super admin changes
+    // it again or the school starts paying (confirmManualPayment then upserts
+    // a real dated cycle over this row).
+    await adminClient
+      .from('platform_subscriptions')
+      .insert({
+        tenant_id: tenantId,
+        plan_id: plan.plan_id,
+        status: 'active',
+        payment_method: 'manual_transfer',
+        interval: 'monthly',
+        current_period_start: nowIso,
+        current_period_end: null,
+      })
+  }
+
   revalidatePath('/platform/tenants')
   return { success: true }
 }

app/api/stripe/billing-portal/route.ts

@@ -3,9 +3,18 @@ import { getStripe } from '@/lib/stripe'
 import { createClient } from '@/lib/supabase/server'
 import { createAdminClient } from '@/lib/supabase/admin'
 import { getCurrentTenantId } from '@/lib/supabase/tenant'
+import { resolveRequestLocale } from '@/lib/i18n/request-locale'
 
 export async function POST(req: NextRequest) {
   try {
+    // Optional JSON body carrying the caller's locale; tolerate an empty body.
+    let bodyLocale: unknown
+    try {
+      bodyLocale = (await req.json())?.locale
+    } catch {
+      bodyLocale = undefined
+    }
+
     const supabase = await createClient()
     const adminClient = await createAdminClient()
     const tenantId = await getCurrentTenantId()
@@ -40,7 +49,8 @@ export async function POST(req: NextRequest) {
     }
 
     const origin = req.headers.get('origin') || req.headers.get('referer')?.replace(/\/[^/]*$/, '') || ''
-    const returnUrl = `${origin}/en/dashboard/admin/billing`
+    const locale = resolveRequestLocale(req, bodyLocale)
+    const returnUrl = `${origin}/${locale}/dashboard/admin/billing`
 
     const session = await getStripe().billingPortal.sessions.create({
       customer: tenant.stripe_customer_id,