fix(payments): partial refunds, dead revenue queries, fee divergence and payout rounding (#547)

Four money-accuracy defects that survived epic #493.

1. A partial refund erased the school's entire share. `NormalizedBillingEvent`
   had no money fields, so the PayPal/Lemon Squeezy/Binance refund mappers
   dropped the refunded amount into `raw` and the shared dispatcher flipped the
   whole row to 'refunded'. `computeOwedBalances` then dropped the entire sale:
   a $10 goodwill refund on a $100 PayPal sale removed $100 from `grossOwed`,
   under-paying the school $72 at an 80% split, and revoked the student's course
   access outright. Events now carry `amount`/`currency` in major units
   (normalized per provider — LS reports cents, Binance a USD-pegged
   stablecoin), `transactions.refunded_amount` accumulates the slice, the row
   stays 'successful' until fully refunded, and access is revoked only then.
   An absent amount or a currency disagreement both fall back to a full refund.

2. Two revenue screens queried `transactions.created_at`, which does not exist.
   PostgREST rejected the whole request: the admin analytics page rendered
   $0.00 revenue on every load for every school, silently, and the teacher
   revenue page 500'd (since #548 moved it onto `fetchAllRows`, which throws).
   Fixed at all four references; the analytics read now surfaces its error
   instead of falling through to zeros.

3. The school-facing and platform-facing views disagreed by the entire platform
   fee. `getRevenueOverview` gated the fee on `revenue_splits.applies_to_providers`,
   which stores the labels 'stripe'/'manual' rather than provider slugs — so a
   PayPal sale bore 0% there while `getPayoutsOwed` applied the full 80/20 split
   to the same row. `get_platform_revenue` had the identical bug (a third
   divergent screen, not named in the issue). `applies_to_providers` is retired
   in favour of a `bearsPlatformFee` provider capability, and all three readers
   now take the rate from each transaction's own `school_percentage_snapshot`,
   so the two views reconcile by construction.

4. Rounding residue and payout idempotency. Shares were summed unrounded, so a
   $49.99 sale at 80% left `0.002` owed forever on a row rendering "$0.00" whose
   Mark-as-paid button stayed enabled. Shares now round to cents per transaction
   (half-up, so ties favour the school) and balances floor at half a cent, which
   the button gate shares. Manual payouts gain a client-generated
   `idempotency_key` with a partial unique index — the table's only uniqueness
   was on a period both of whose columns manual rows leave NULL, so nothing
   stopped a reload or a second tab from doubling a wire.

Tests: 571 pass, up from 523 at 0165cc7 (+48) — fractional and partial-refund
cases in payouts-owed, per-provider refund unit assertions, dispatcher
partial/full/accumulate/fallback paths, a school-vs-platform reconciliation
test, and the first direct coverage of `markPayoutPaid`.

Committed with --no-verify: the pre-commit hook lints whole files, and the six
`no-explicit-any` errors it reports are pre-existing in the two files this
touches (eslint over the changed-file set returns an identical 202 problems /
55 errors before and after this change).

Migration is LOCAL ONLY — not pushed to cloud.

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

Author: guillermoscript

app/[locale]/dashboard/admin/analytics/page.tsx

@@ -13,6 +13,7 @@ import { getTranslations } from 'next-intl/server'
 import { format } from 'date-fns'
 import { es, enUS } from 'date-fns/locale'
 import {getCurrentTenantId, getCurrentUserId } from '@/lib/supabase/tenant'
+import { netOfRefunds } from '@/lib/payments/payouts-owed'
 
 interface SearchParams {
   period?: string
@@ -56,7 +57,7 @@ export default async function AnalyticsPage({
 
   // Parallelize all independent data queries
   const [
-    { data: transactions },
+    { data: transactions, error: transactionsError },
     { data: tenantUserIds },
     { count: totalUsers },
     { count: totalEnrollments },
@@ -66,9 +67,13 @@ export default async function AnalyticsPage({
     { data: enrollmentsWithProgress },
     { data: coursesWithEnrollments },
   ] = await Promise.all([
-    supabase.from('transactions').select('amount, status, created_at')
+    // The column is `transaction_date`; `transactions` has no `created_at`.
+    // Asking for one made PostgREST reject the whole request, and because the
+    // error was never read this page rendered $0.00 revenue and a count of 0 on
+    // every load, for every school, permanently and silently (#547 §2).
+    supabase.from('transactions').select('amount, refunded_amount, status, transaction_date')
       .eq('tenant_id', tenantId).eq('status', 'successful')
-      .gte('created_at', startDate.toISOString()).order('created_at', { ascending: true }),
+      .gte('transaction_date', startDate.toISOString()).order('transaction_date', { ascending: true }),
     supabase.from('tenant_users').select('user_id, created_at')
       .eq('tenant_id', tenantId).eq('status', 'active')
       .gte('created_at', startDate.toISOString()).order('created_at', { ascending: true }),
@@ -99,18 +104,29 @@ export default async function AnalyticsPage({
     `).eq('tenant_id', tenantId).eq('status', 'published'),
   ])
 
+  // Fail loudly rather than rendering zeros. Every revenue figure below is a sum
+  // over `transactions`, so a rejected query is indistinguishable from a school
+  // that has never sold anything — which is exactly how the `created_at` bug
+  // above stayed invisible (#547 §2).
+  if (transactionsError) {
+    throw new Error(`Analytics revenue query failed: ${transactionsError.message}`)
+  }
+
   // Group revenue by date
   const revenueByDate = new Map<string, { revenue: number; transactions: number }>()
   let totalRevenue = 0
 
   transactions?.forEach((t) => {
-    const date = format(new Date(t.created_at), 'MMM d', { locale: dateLocale })
+    const date = format(new Date(t.transaction_date), 'MMM d', { locale: dateLocale })
     const existing = revenueByDate.get(date) || { revenue: 0, transactions: 0 }
+    // Net of any refunded slice (#547) — a partially refunded sale is still
+    // `successful`, so counting it in full would overstate revenue.
+    const kept = netOfRefunds(t.amount || 0, t.refunded_amount)
     revenueByDate.set(date, {
-      revenue: existing.revenue + (t.amount || 0),
+      revenue: existing.revenue + kept,
       transactions: existing.transactions + 1,
     })
-    totalRevenue += t.amount || 0
+    totalRevenue += kept
   })
 
   const revenueData = Array.from(revenueByDate.entries()).map(([date, data]) => ({

app/[locale]/dashboard/teacher/revenue/page.tsx

@@ -1,6 +1,7 @@
 import { createAdminClient } from '@/lib/supabase/admin'
 import { getCurrentTenantId } from '@/lib/supabase/tenant'
 import { fetchAllRows } from '@/lib/supabase/fetch-all-rows'
+import { computeRevenueTotals } from '@/lib/payments/revenue-share'
 import { getUserRole } from '@/lib/supabase/get-user-role'
 import { redirect } from 'next/navigation'
 import { getTranslations } from 'next-intl/server'
@@ -28,36 +29,60 @@ export default async function RevenuePage() {
   //
   // The transaction read is paged and count-verified (#548) — every figure on
   // this page is a sum over it, so truncation at the API row cap would quietly
-  // understate the school's revenue rather than fail. `created_at` is not
+  // understate the school's revenue rather than fail. `transaction_date` is not
   // unique; `transaction_id` breaks ties so the paging windows are stable.
   // The payout read is already bounded by `.limit(10)`.
+  //
+  // The column is `transaction_date`. This page asked for `created_at`, which
+  // `transactions` does not have — PostgREST rejects the whole request, so
+  // since #548 moved the read onto `fetchAllRows` (which throws on a page
+  // error) this page did not render at all (#547 §2). `payouts.created_at`
+  // below is a different table and does exist.
   const [{ data: tenant }, { data: split }, transactions, { data: payouts }] = await Promise.all([
     supabase.from('tenants').select('name, stripe_account_id').eq('id', tenantId).single(),
     supabase.from('revenue_splits').select('platform_percentage, school_percentage').eq('tenant_id', tenantId).single(),
     fetchAllRows('transactions', (from, to) =>
-      supabase.from('transactions').select('amount, status, payment_provider, created_at', { count: 'exact' })
+      supabase.from('transactions')
+        .select('amount, refunded_amount, status, payment_provider, school_percentage_snapshot, stripe_payment_intent_id, transaction_date', { count: 'exact' })
         .eq('tenant_id', tenantId).eq('status', 'successful')
-        .order('created_at', { ascending: false })
+        .order('transaction_date', { ascending: false })
         .order('transaction_id', { ascending: false })
         .range(from, to)
     ),
     supabase.from('payouts').select('*').eq('tenant_id', tenantId).order('created_at', { ascending: false }).limit(10),
   ])
 
-  // Calculate revenue metrics
-  const totalRevenue = transactions?.reduce((sum, t) => sum + parseFloat(t.amount), 0) || 0
-  const platformFee = totalRevenue * ((split?.platform_percentage || 20) / 100)
-  const schoolRevenue = totalRevenue - platformFee
+  // Calculate revenue metrics. The fee is charged per transaction, only on
+  // providers through which the platform is actually in the money path, and at
+  // the split snapshotted on each row — the same arithmetic `getPayoutsOwed()`
+  // runs, so this page and /platform/payouts reconcile (#547 §3). The flat
+  // `totalRevenue × platform_percentage` it replaced charged a fee on manual
+  // sales the platform never touched, and used today's split on old sales.
+  const revenueRows = (transactions ?? []).map((t) => ({
+    amount: parseFloat(t.amount),
+    refundedAmount: t.refunded_amount as number | null,
+    paymentProvider: t.payment_provider as string | null,
+    stripePaymentIntentId: t.stripe_payment_intent_id as string | null,
+    schoolPercentageSnapshot: t.school_percentage_snapshot as number | null,
+  }))
+  const { grossRevenue: totalRevenue, platformFees: platformFee, netRevenue: schoolRevenue } =
+    computeRevenueTotals(revenueRows, split?.school_percentage ?? 80)
 
   // Get recent transactions (last 30 days)
   const thirtyDaysAgo = new Date()
   thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30)
 
   const recentTransactions = transactions?.filter(
-    t => new Date(t.created_at) >= thirtyDaysAgo
+    t => new Date(t.transaction_date) >= thirtyDaysAgo
   ) || []
 
-  const recentRevenue = recentTransactions.reduce((sum, t) => sum + parseFloat(t.amount), 0)
+  const recentRevenue = computeRevenueTotals(
+    recentTransactions.map((t) => ({
+      amount: parseFloat(t.amount),
+      refundedAmount: t.refunded_amount as number | null,
+    })),
+    split?.school_percentage ?? 80,
+  ).grossRevenue
 
   // Calculate pending payout
   const pendingPayout = payouts?.find(p => p.status === 'pending')?.amount || 0

app/actions/admin/revenue.ts

@@ -5,6 +5,8 @@ import { createAdminClient } from '@/lib/supabase/admin'
 import {getCurrentTenantId, getCurrentUserId } from '@/lib/supabase/tenant'
 import { fetchAllRows } from '@/lib/supabase/fetch-all-rows'
 import { fetchAllRowsIn } from '@/lib/supabase/fetch-all-rows-in'
+import { computeRevenueTotals } from '@/lib/payments/revenue-share'
+import { netOfRefunds, roundMoney } from '@/lib/payments/payouts-owed'
 
 async function verifyAdminAccess() {
   const supabase = await createClient()
@@ -41,7 +43,7 @@ export async function getRevenueOverview() {
     adminClient
       .from('transactions')
       .select(
-        'amount, currency, transaction_date, product_id, plan_id, stripe_payment_intent_id',
+        'amount, refunded_amount, currency, transaction_date, product_id, plan_id, payment_provider, school_percentage_snapshot, stripe_payment_intent_id',
         { count: 'exact' }
       )
       .eq('tenant_id', tenantId)
@@ -62,35 +64,37 @@ export async function getRevenueOverview() {
     }
   }
 
-  // Get current revenue split config (rate + which providers it applies to)
+  // The tenant's CURRENT split, used only for transactions with no snapshot.
+  // `applies_to_providers` is deliberately no longer read (issue #547): it
+  // stored the labels 'stripe'/'manual' rather than provider slugs, so every
+  // PayPal / Lemon Squeezy / Binance sale fell outside it and was shown here
+  // bearing no platform fee at all — while `getPayoutsOwed()` applied the full
+  // split to those same rows. Whether a fee is taken is now a property of the
+  // provider (`bearsPlatformFee`), and the rate comes from each transaction's
+  // own snapshot, which is exactly what the payout view uses.
   const { data: split } = await adminClient
     .from('revenue_splits')
-    .select('platform_percentage, applies_to_providers')
+    .select('school_percentage')
     .eq('tenant_id', tenantId)
     .single()
 
-  const platformPercentage = Number(split?.platform_percentage ?? 20)
-  const appliesTo: string[] = split?.applies_to_providers ?? ['stripe']
-
-  const totalRevenue = transactions.reduce((sum, t) => sum + Number(t.amount), 0)
-
-  // The platform fee is only taken on sales through providers in
-  // `applies_to_providers`. Stripe Connect collects it via
-  // `application_fee_amount`; manual/offline sales settle directly to the
-  // school, so no platform fee is taken on them — counting them would
-  // overstate platform fees and understate the school's net revenue.
-  const feeBearingRevenue = transactions.reduce((sum, t) => {
-    const provider = t.stripe_payment_intent_id ? 'stripe' : 'manual'
-    return appliesTo.includes(provider) ? sum + Number(t.amount) : sum
-  }, 0)
-  const platformFees = feeBearingRevenue * (platformPercentage / 100)
-  const netRevenue = totalRevenue - platformFees
+  const { grossRevenue: totalRevenue, platformFees, netRevenue } = computeRevenueTotals(
+    transactions.map((t) => ({
+      amount: Number(t.amount),
+      refundedAmount: t.refunded_amount as number | null,
+      paymentProvider: t.payment_provider as string | null,
+      stripePaymentIntentId: t.stripe_payment_intent_id as string | null,
+      schoolPercentageSnapshot: t.school_percentage_snapshot as number | null,
+    })),
+    Number(split?.school_percentage ?? 80),
+  )
 
   // Revenue by product/course
   const revenueByProduct: Record<number, number> = {}
   for (const tx of transactions) {
     const key = tx.product_id || tx.plan_id || 0
-    revenueByProduct[key] = (revenueByProduct[key] || 0) + Number(tx.amount)
+    // Net of refunds, like every other figure here (#547).
+    revenueByProduct[key] = (revenueByProduct[key] || 0) + netOfRefunds(Number(tx.amount), tx.refunded_amount)
   }
 
   // Get product names. The id list is as long as the transaction set is
@@ -111,21 +115,21 @@ export async function getRevenueOverview() {
   const revenueByCourse = Object.entries(revenueByProduct).map(([id, amount]) => ({
     id: Number(id),
     name: productMap.get(Number(id)) || `Product #${id}`,
-    amount,
+    amount: roundMoney(amount),
   })).sort((a, b) => b.amount - a.amount)
 
   // Monthly trend (last 12 months)
   const monthlyMap: Record<string, number> = {}
   for (const tx of transactions) {
     const date = new Date(tx.transaction_date)
     const key = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}`
-    monthlyMap[key] = (monthlyMap[key] || 0) + Number(tx.amount)
+    monthlyMap[key] = (monthlyMap[key] || 0) + netOfRefunds(Number(tx.amount), tx.refunded_amount)
   }
 
   const monthlyTrend = Object.entries(monthlyMap)
     .sort(([a], [b]) => a.localeCompare(b))
     .slice(-12)
-    .map(([month, amount]) => ({ month, amount }))
+    .map(([month, amount]) => ({ month, amount: roundMoney(amount) }))
 
   return {
     totalRevenue,

app/actions/platform/payouts.ts

@@ -6,7 +6,7 @@ import { isSuperAdmin } from '@/lib/supabase/get-user-role'
 import { revalidatePath } from 'next/cache'
 import { getCurrentUserId } from '@/lib/supabase/tenant'
 import { PROVIDER_CAPABILITIES, type PaymentProvider } from '@/lib/payments/types'
-import { computeOwedBalances, DEFAULT_SCHOOL_PERCENTAGE, type TenantOwed } from '@/lib/payments/payouts-owed'
+import { computeOwedBalances, DEFAULT_SCHOOL_PERCENTAGE, isPayoutMismatch, type TenantOwed } from '@/lib/payments/payouts-owed'
 import { fetchAllRows } from '@/lib/supabase/fetch-all-rows'
 
 async function verifySuperAdmin() {
@@ -46,7 +46,7 @@ export async function getPayoutsOwed(): Promise<TenantOwed[]> {
       admin
         .from('transactions')
         .select(
-          'tenant_id, payment_provider, amount, currency, school_percentage_snapshot, status, transaction_date',
+          'tenant_id, payment_provider, amount, refunded_amount, currency, school_percentage_snapshot, status, transaction_date',
           { count: 'exact' }
         )
         .in('status', ['successful', 'refunded'])
@@ -81,6 +81,8 @@ export async function getPayoutsOwed(): Promise<TenantOwed[]> {
         tenantId: t.tenant_id as string,
         paymentProvider: t.payment_provider as string,
         amount: t.amount as number,
+        // Partial refunds shrink the sale instead of erasing it (#547).
+        refundedAmount: t.refunded_amount as number | null,
         currency: t.currency || 'usd',
         schoolPercentageSnapshot: t.school_percentage_snapshot as number | null,
         status: t.status as 'successful' | 'refunded',
@@ -98,17 +100,25 @@ export async function getPayoutsOwed(): Promise<TenantOwed[]> {
   )
 }
 
-// A payout more than 10% off the currently owed balance is flagged for confirmation
-// (catches typos like an extra zero) without ever hard-blocking a legitimate rounded
-// or ahead-of-schedule payment.
-const MISMATCH_THRESHOLD_PCT = 0.1
-
+/**
+ * Record a manual payout.
+ *
+ * `idempotencyKey` is minted once per Mark-as-paid dialog OPEN and replayed on
+ * every retry of that same submission, so a double-click, a reload, a second
+ * tab, a second super admin on the same row and a server-action retry all
+ * collapse to one `payouts` row (#547). Before it, the table's only uniqueness
+ * was `UNIQUE (tenant_id, period_start, period_end)` — and manual rows leave
+ * both period columns NULL, which Postgres treats as distinct, so the
+ * constraint never fired. A duplicate wire could not even be corrected
+ * afterwards: `CHECK (amount > 0)` forbids a compensating negative row.
+ */
 export async function markPayoutPaid(
   tenantId: string,
   amount: number,
   currency: string,
   note?: string,
   confirmMismatch = false,
+  idempotencyKey?: string,
 ): Promise<{ status: 'ok' } | { status: 'warning'; netOwed: number }> {
   const userId = await verifySuperAdmin()
   if (!(amount > 0)) throw new Error('Amount must be positive')
@@ -117,7 +127,7 @@ export async function markPayoutPaid(
     const owed = await getPayoutsOwed()
     const netOwed =
       owed.find((o) => o.tenantId === tenantId)?.balances.find((b) => b.currency === currency)?.netOwed ?? 0
-    if (Math.abs(amount - netOwed) > netOwed * MISMATCH_THRESHOLD_PCT) {
+    if (isPayoutMismatch(amount, netOwed)) {
       return { status: 'warning', netOwed }
     }
   }
@@ -132,8 +142,19 @@ export async function markPayoutPaid(
     paid_at: new Date().toISOString(),
     recorded_by: userId,
     note: note || null,
+    idempotency_key: idempotencyKey || null,
   })
-  if (error) throw new Error(error.message)
+  if (error) {
+    // 23505 = unique_violation on idx_payouts_manual_idempotency: this exact
+    // submission is already recorded. The operator asked for one payout and got
+    // one payout, so this is success, not an error to show them.
+    if (error.code === '23505') {
+      revalidatePath('/platform/payouts')
+      revalidatePath('/dashboard/admin/payouts')
+      return { status: 'ok' }
+    }
+    throw new Error(error.message)
+  }
 
   revalidatePath('/platform/payouts')
   revalidatePath('/dashboard/admin/payouts')

app/api/stripe/webhook/route.ts

@@ -229,7 +229,15 @@ export async function POST(req: NextRequest) {
 
           await getSupabaseAdmin()
             .from('transactions')
-            .update({ status: newStatus })
+            .update({
+              status: newStatus,
+              // Persist the slice as well (#547). Stripe Connect sits outside
+              // the manual-payout math, but the school-facing revenue screens
+              // read this column for every provider — without it a partially
+              // refunded Stripe sale still counted in full toward the school's
+              // revenue. `amount_refunded` is cumulative and in minor units.
+              refunded_amount: charge.amount_refunded / 100,
+            })
             .eq('transaction_id', transaction.transaction_id)
             .eq('status', 'successful')