feat: add usage overage billing

apps/api/src/features/platform-admin/index.ts

@@ -5,6 +5,7 @@ import {
   createSubscriptionRoute,
   createTenantInvoiceFromSubscriptionRoute,
   createTenantInvoicesBatchFromSubscriptionsRoute,
+  createTenantInvoicesFromUsageOverageRoute,
   createTenantRoute,
   invoiceRemindersRoute,
   platformAuditAlertRulesRoute,
@@ -25,6 +26,7 @@ import {
   questionBankGrantsRoute,
   recordUsageRoute,
   subscriptionInvoiceCandidatesRoute,
+  usageOverageInvoiceCandidatesRoute,
   tenantDetailRoute,
   tenantInvoicesRoute,
   tenantsRoute,
@@ -70,8 +72,10 @@ export const platformAdminRoutes: RouteDefinition[] = [
   ['GET', '/api/platform-admin/invoices', tenantInvoicesRoute],
   ['POST', '/api/platform-admin/invoices', createInvoiceRoute],
   ['GET', '/api/platform-admin/invoices/subscription-candidates', subscriptionInvoiceCandidatesRoute],
+  ['GET', '/api/platform-admin/invoices/usage-overage-candidates', usageOverageInvoiceCandidatesRoute],
   ['POST', '/api/platform-admin/invoices/from-subscription', createTenantInvoiceFromSubscriptionRoute],
   ['POST', '/api/platform-admin/invoices/from-subscriptions-batch', createTenantInvoicesBatchFromSubscriptionsRoute],
+  ['POST', '/api/platform-admin/invoices/from-usage-overage', createTenantInvoicesFromUsageOverageRoute],
   ['POST', '/api/platform-admin/invoices/process-overdue', processOverdueInvoicesRoute],
   ['GET', '/api/platform-admin/invoices/reminders', invoiceRemindersRoute],
   ['POST', '/api/platform-admin/invoices/payments/manual-confirm', confirmInvoicePaymentRoute],

apps/api/src/features/platform-admin/routes.ts

@@ -349,6 +349,36 @@ function tenantInvoiceStatusFrom(value: string) {
   return status;
 }
 
+function usageOverageInvoiceStatusFrom(value: string) {
+  const status = tenantInvoiceStatusFrom(value);
+  if (!['draft', 'issued'].includes(status)) {
+    throw new HttpError(400, 'usage overage invoices can only be draft or issued', 'INVALID_INVOICE_STATUS');
+  }
+  return status;
+}
+
+function dateTextFrom(value: unknown, key: string, required = true) {
+  const text = typeof value === 'string' ? value.trim() : '';
+  if (!text) {
+    if (required) throw new HttpError(400, `${key} is required`, 'REQUIRED_FIELD');
+    return '';
+  }
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(text)) {
+    throw new HttpError(400, `${key} must use YYYY-MM-DD format`, 'INVALID_DATE');
+  }
+  const date = new Date(`${text}T00:00:00.000Z`);
+  if (!Number.isFinite(date.getTime()) || date.toISOString().slice(0, 10) !== text) {
+    throw new HttpError(400, `${key} must be a valid date`, 'INVALID_DATE');
+  }
+  return text;
+}
+
+function assertDateRange(periodStart: string, periodEnd: string) {
+  if (periodStart > periodEnd) {
+    throw new HttpError(400, 'periodStart must be before or equal to periodEnd', 'INVALID_DATE_RANGE');
+  }
+}
+
 function platformAuditDetails(value: unknown) {
   return JSON.stringify(value && typeof value === 'object' && !Array.isArray(value) ? value : {});
 }
@@ -2688,9 +2718,9 @@ export async function recordUsageRoute(ctx: RequestContext) {
   const tenantId = requiredString(body, 'tenantId');
   const metricKey = requiredString(body, 'metricKey');
   const metricValue = quantityFrom(body.metricValue, 0);
-  const periodStart = optionalString(body, 'periodStart');
-  const periodEnd = optionalString(body, 'periodEnd');
-  if (!periodStart || !periodEnd) throw new HttpError(400, 'periodStart and periodEnd are required', 'REQUIRED_FIELD');
+  const periodStart = dateTextFrom(body.periodStart, 'periodStart');
+  const periodEnd = dateTextFrom(body.periodEnd, 'periodEnd');
+  assertDateRange(periodStart, periodEnd);
 
   const item = await queryOne(
     `
@@ -2732,6 +2762,387 @@ export async function tenantUsageRoute(ctx: RequestContext) {
   return { items };
 }
 
+interface UsageMetricSnapshot {
+  value: number;
+  recordId: string;
+  source: string | null;
+  createdAt: string | null;
+}
+
+interface UsageOverageItem {
+  itemType: string;
+  description: string;
+  quantity: number;
+  unitAmountCents: number;
+  metadata: Record<string, unknown>;
+}
+
+interface UsageOverageCandidate {
+  tenantId: string;
+  tenantSlug: string;
+  tenantName: string;
+  billingStatus: string;
+  subscriptionId: string;
+  planCode: string;
+  planName: string | null;
+  subscriptionStatus: string;
+  billingCycle: string | null;
+  periodStart: string;
+  periodEnd: string;
+  existingInvoiceId: string | null;
+  existingInvoiceNo: string | null;
+  existingInvoiceStatus: string | null;
+  hasExistingInvoice: boolean;
+  wouldCreate: boolean;
+  totalCents: number;
+  items: UsageOverageItem[];
+}
+
+const USAGE_METRIC_ALIASES: Record<string, string[]> = {
+  students: ['students', 'studentCount'],
+  active_students: ['active_students', 'activeStudents', 'activeStudentCount'],
+  questions: ['questions', 'questionCount'],
+  assets: ['assets', 'assetCount'],
+  storage_gb: ['storage_gb', 'storageGb', 'storageGB', 'storage'],
+  videos: ['videos', 'videoCount'],
+  video_plays: ['video_plays', 'videoPlays', 'videoPlayCount'],
+  video_quota_consumed: ['video_quota_consumed', 'videoQuotaConsumed', 'videoQuota'],
+  paid_orders: ['paid_orders', 'paidOrders', 'paidOrderCount'],
+  paid_order_amount_cents: ['paid_order_amount_cents', 'paidOrderAmountCents', 'paidOrderGmvCents'],
+  active_entitlements: ['active_entitlements', 'activeEntitlements', 'activeEntitlementCount'],
+};
+
+const USAGE_METRIC_LABELS: Record<string, string> = {
+  students: '学生数',
+  active_students: '活跃学生数',
+  questions: '题目数量',
+  assets: '资源数量',
+  storage_gb: '存储容量 GB',
+  videos: '视频数量',
+  video_plays: '视频播放次数',
+  video_quota_consumed: '视频次数消耗',
+  paid_orders: '已支付订单数',
+  paid_order_amount_cents: '已支付订单金额',
+  active_entitlements: '有效权益数',
+};
+
+function numberOrNull(value: unknown) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function positiveIntegerOrNull(value: unknown) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return null;
+  return Math.max(1, Math.trunc(parsed));
+}
+
+function metricAliases(metricKey: string) {
+  return [...new Set([metricKey, ...(USAGE_METRIC_ALIASES[metricKey] || [])])];
+}
+
+function camelMetricKey(metricKey: string) {
+  return metricKey.replace(/_([a-z])/g, (_, char: string) => char.toUpperCase());
+}
+
+function snakeMetricKey(metricKey: string) {
+  return metricKey.replace(/[A-Z]/g, char => `_${char.toLowerCase()}`);
+}
+
+function objectOrNull(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : null;
+}
+
+function nestedMetricSpec(source: Record<string, unknown>, metricKey: string) {
+  for (const key of metricAliases(metricKey)) {
+    if (Object.prototype.hasOwnProperty.call(source, key)) return source[key];
+  }
+  return undefined;
+}
+
+function firstMetricValue(sources: Array<Record<string, unknown> | null>, metricKey: string, suffixes: string[]) {
+  const camel = camelMetricKey(metricKey);
+  const snake = snakeMetricKey(metricKey);
+  const directKeys = metricAliases(metricKey);
+  const generatedKeys = suffixes.flatMap(suffix => [
+    `${camel}${suffix}`,
+    `${snake}_${suffix.replace(/[A-Z]/g, char => `_${char.toLowerCase()}`).replace(/^_/, '')}`,
+  ]);
+
+  for (const source of sources) {
+    if (!source) continue;
+    for (const key of [...directKeys, ...generatedKeys]) {
+      if (Object.prototype.hasOwnProperty.call(source, key)) return source[key];
+    }
+  }
+  return undefined;
+}
+
+function quotaForMetric(metricKey: string, planQuotas: Record<string, unknown>, subscriptionMetadata: Record<string, unknown>) {
+  const metadataQuotaSources = [
+    objectOrNull(subscriptionMetadata.includedQuotas),
+    objectOrNull(subscriptionMetadata.quotas),
+    objectOrNull(subscriptionMetadata.quotaOverrides),
+  ];
+  const sources = [...metadataQuotaSources, planQuotas];
+  const direct = firstMetricValue(sources, metricKey, ['Included', 'Quota', 'Limit']);
+  if (direct && typeof direct === 'object' && !Array.isArray(direct)) {
+    const spec = direct as Record<string, unknown>;
+    return numberOrNull(spec.included ?? spec.includedQuota ?? spec.quota ?? spec.limit ?? spec.value);
+  }
+  const numeric = numberOrNull(direct);
+  if (numeric !== null) return numeric;
+
+  for (const source of sources) {
+    if (!source) continue;
+    const nested = objectOrNull(nestedMetricSpec(source, metricKey));
+    if (nested) {
+      const value = numberOrNull(nested.included ?? nested.includedQuota ?? nested.quota ?? nested.limit ?? nested.value);
+      if (value !== null) return value;
+    }
+  }
+  return null;
+}
+
+function priceForMetric(metricKey: string, planPrices: Record<string, unknown>, subscriptionMetadata: Record<string, unknown>) {
+  const metadataPriceSources = [
+    objectOrNull(subscriptionMetadata.overagePrices),
+    objectOrNull(subscriptionMetadata.overagePriceOverrides),
+    objectOrNull(subscriptionMetadata.prices),
+  ];
+  const sources = [...metadataPriceSources, planPrices];
+  const suffixes = [
+    'UnitAmountCents',
+    'AmountCents',
+    'PriceCents',
+    'OverageCents',
+    'PerUnitCents',
+    'ExtraCents',
+    'ExtraPerMonthCents',
+    'ExtraPerYearCents',
+    'PerMonthCents',
+    'PerYearCents',
+  ];
+  const direct = firstMetricValue(sources, metricKey, suffixes);
+  const directObject = objectOrNull(direct);
+  let unitAmountCents = directObject
+    ? positiveIntegerOrNull(directObject.unitAmountCents ?? directObject.amountCents ?? directObject.priceCents ?? directObject.overageCents ?? directObject.cents ?? directObject.perUnitCents)
+    : positiveIntegerOrNull(direct);
+  let unitSize = directObject ? numberOrNull(directObject.unitSize ?? directObject.step ?? directObject.per ?? directObject.quantityUnit) : null;
+
+  for (const source of sources) {
+    if (!source) continue;
+    const nested = objectOrNull(nestedMetricSpec(source, metricKey));
+    if (!nested) continue;
+    unitAmountCents = unitAmountCents ?? positiveIntegerOrNull(nested.unitAmountCents ?? nested.amountCents ?? nested.priceCents ?? nested.overageCents ?? nested.cents ?? nested.perUnitCents);
+    unitSize = unitSize ?? numberOrNull(nested.unitSize ?? nested.step ?? nested.per ?? nested.quantityUnit);
+  }
+
+  if (!unitAmountCents) return null;
+  return {
+    unitAmountCents,
+    unitSize: unitSize && unitSize > 0 ? unitSize : 1,
+  };
+}
+
+function usageSnapshotMap(value: unknown) {
+  const usage = objectOrNull(value) || {};
+  const output: Record<string, UsageMetricSnapshot> = {};
+  for (const [metricKey, rawSnapshot] of Object.entries(usage)) {
+    const snapshot = objectOrNull(rawSnapshot);
+    if (!snapshot) continue;
+    const metricValue = numberOrNull(snapshot.value);
+    if (metricValue === null) continue;
+    output[metricKey] = {
+      value: metricValue,
+      recordId: String(snapshot.recordId || ''),
+      source: typeof snapshot.source === 'string' ? snapshot.source : null,
+      createdAt: typeof snapshot.createdAt === 'string' ? snapshot.createdAt : null,
+    };
+  }
+  return output;
+}
+
+function buildUsageOverageItems(row: {
+  planCode: string;
+  planName: string | null;
+  includedQuotas: Record<string, unknown> | null;
+  overagePrices: Record<string, unknown> | null;
+  subscriptionMetadata: Record<string, unknown> | null;
+  usageSnapshots: unknown;
+}) {
+  const planQuotas = row.includedQuotas || {};
+  const planPrices = row.overagePrices || {};
+  const subscriptionMetadata = row.subscriptionMetadata || {};
+  const usage = usageSnapshotMap(row.usageSnapshots);
+  const items: UsageOverageItem[] = [];
+
+  for (const [metricKey, snapshot] of Object.entries(usage)) {
+    const includedQuota = quotaForMetric(metricKey, planQuotas, subscriptionMetadata);
+    const price = priceForMetric(metricKey, planPrices, subscriptionMetadata);
+    if (includedQuota === null || !price) continue;
+    const overageValue = snapshot.value - includedQuota;
+    if (overageValue <= 0) continue;
+
+    const billableUnits = Math.ceil(overageValue / price.unitSize);
+    if (billableUnits <= 0) continue;
+    const label = USAGE_METRIC_LABELS[metricKey] || metricKey;
+    items.push({
+      itemType: 'usage_overage',
+      description: `${row.planName || row.planCode} ${label}超额 ${Number(overageValue.toFixed(4))}`,
+      quantity: billableUnits,
+      unitAmountCents: price.unitAmountCents,
+      metadata: {
+        metricKey,
+        metricLabel: label,
+        metricValue: snapshot.value,
+        includedQuota,
+        overageValue: Number(overageValue.toFixed(4)),
+        billableUnits,
+        unitSize: price.unitSize,
+        unitAmountCents: price.unitAmountCents,
+        usageRecordId: snapshot.recordId || null,
+        usageSource: snapshot.source,
+      },
+    });
+  }
+
+  return items;
+}
+
+async function usageOverageCandidateQuery(params: {
+  tenantIds: string[];
+  periodStart: string;
+  periodEnd: string;
+  includeExisting: boolean;
+  includeZero: boolean;
+  limit: number;
+}) {
+  const rows = await query<{
+    tenantId: string;
+    tenantSlug: string;
+    tenantName: string;
+    billingStatus: string;
+    subscriptionId: string;
+    planCode: string;
+    planName: string | null;
+    subscriptionStatus: string;
+    billingCycle: string | null;
+    includedQuotas: Record<string, unknown> | null;
+    overagePrices: Record<string, unknown> | null;
+    subscriptionMetadata: Record<string, unknown> | null;
+    usageSnapshots: unknown;
+    existingInvoiceId: string | null;
+    existingInvoiceNo: string | null;
+    existingInvoiceStatus: string | null;
+  }>(
+    `
+    select t.id as "tenantId", t.slug::text as "tenantSlug", t.name as "tenantName",
+           t.billing_status as "billingStatus",
+           s.id as "subscriptionId", s.plan_code as "planCode",
+           p.name as "planName", s.status as "subscriptionStatus",
+           s.billing_cycle as "billingCycle",
+           p.included_quotas as "includedQuotas",
+           p.overage_prices as "overagePrices",
+           s.metadata as "subscriptionMetadata",
+           coalesce(usage_snapshots.metrics, '{}'::jsonb) as "usageSnapshots",
+           existing.id as "existingInvoiceId",
+           existing.invoice_no as "existingInvoiceNo",
+           existing.status as "existingInvoiceStatus"
+    from public.tenants t
+    join lateral (
+      select id, tenant_id, plan_code, status, billing_cycle, metadata, created_at, expires_at
+      from public.tenant_subscriptions
+      where tenant_id = t.id
+        and status in ('trial', 'active', 'past_due')
+      order by case status when 'active' then 0 when 'trial' then 1 else 2 end,
+               expires_at desc nulls last,
+               created_at desc
+      limit 1
+    ) s on true
+    join public.platform_saas_plans p on p.code = s.plan_code
+    left join lateral (
+      select jsonb_object_agg(metric_key, jsonb_build_object(
+        'value', metric_value,
+        'recordId', id,
+        'source', metadata->>'source',
+        'createdAt', created_at
+      )) as metrics
+      from (
+        select distinct on (u.metric_key)
+               u.id, u.metric_key, u.metric_value, u.metadata, u.created_at
+        from public.tenant_usage_records u
+        where u.tenant_id = t.id
+          and u.period_start = $2::date
+          and u.period_end = $3::date
+        order by u.metric_key,
+                 case when u.metadata->>'source' = 'platform_usage_worker' then 0 else 1 end,
+                 u.created_at desc
+      ) latest
+    ) usage_snapshots on true
+    left join lateral (
+      select id, invoice_no, status
+      from public.tenant_invoices i
+      where i.tenant_id = t.id
+        and i.invoice_type = 'usage_overage'
+        and i.status <> 'void'
+        and i.billing_period_start = $2::date
+        and i.billing_period_end = $3::date
+        and i.metadata->>'source' = 'usage_overage_auto'
+      order by i.created_at desc
+      limit 1
+    ) existing on true
+    where t.status = 'active'
+      and ($1::uuid[] = '{}'::uuid[] or t.id = any($1::uuid[]))
+      and ($4::boolean = true or existing.id is null)
+    order by t.created_at asc
+    limit $5
+    `,
+    [params.tenantIds, params.periodStart, params.periodEnd, params.includeExisting, params.limit],
+  );
+
+  const candidates: UsageOverageCandidate[] = rows.map(row => {
+    const items = buildUsageOverageItems(row);
+    return {
+      tenantId: row.tenantId,
+      tenantSlug: row.tenantSlug,
+      tenantName: row.tenantName,
+      billingStatus: row.billingStatus,
+      subscriptionId: row.subscriptionId,
+      planCode: row.planCode,
+      planName: row.planName,
+      subscriptionStatus: row.subscriptionStatus,
+      billingCycle: row.billingCycle,
+      periodStart: params.periodStart,
+      periodEnd: params.periodEnd,
+      existingInvoiceId: row.existingInvoiceId,
+      existingInvoiceNo: row.existingInvoiceNo,
+      existingInvoiceStatus: row.existingInvoiceStatus,
+      hasExistingInvoice: Boolean(row.existingInvoiceId),
+      wouldCreate: items.length > 0 && !row.existingInvoiceId,
+      totalCents: invoiceSubtotal(items),
+      items,
+    };
+  });
+
+  return candidates.filter(item => params.includeZero || item.items.length > 0);
+}
+
+export async function usageOverageInvoiceCandidatesRoute(ctx: RequestContext) {
+  await requirePlatformAdmin(ctx, 'platform:billing:read');
+
+  const tenantIds = optionalUuidList(ctx.url.searchParams.get('tenantIds'), 'tenantIds');
+  const periodStart = dateTextFrom(ctx.url.searchParams.get('periodStart'), 'periodStart');
+  const periodEnd = dateTextFrom(ctx.url.searchParams.get('periodEnd'), 'periodEnd');
+  assertDateRange(periodStart, periodEnd);
+  const includeExisting = listQuery(ctx, 'includeExisting') === 'true';
+  const includeZero = listQuery(ctx, 'includeZero') === 'true';
+  const limit = intParam(ctx, 'limit', 100, 500);
+  const items = await usageOverageCandidateQuery({ tenantIds, periodStart, periodEnd, includeExisting, includeZero, limit });
+
+  return { items };
+}
+
 async function subscriptionInvoiceCandidateQuery(params: {
   tenantIds: string[];
   subscriptionIds: string[];
@@ -3034,3 +3445,170 @@ export async function createTenantInvoicesBatchFromSubscriptionsRoute(ctx: Reque
 
   return { item: result };
 }
+
+export async function createTenantInvoicesFromUsageOverageRoute(ctx: RequestContext) {
+  await requirePlatformAdmin(ctx, 'platform:billing:write');
+
+  const body = await readJsonBody(ctx);
+  const tenantIds = optionalUuidList(body.tenantIds, 'tenantIds');
+  const periodStart = dateTextFrom(body.periodStart, 'periodStart');
+  const periodEnd = dateTextFrom(body.periodEnd, 'periodEnd');
+  assertDateRange(periodStart, periodEnd);
+  const dueDate = dateTextFrom(body.dueDate, 'dueDate', false) || null;
+  const status = usageOverageInvoiceStatusFrom(optionalString(body, 'status'));
+  const note = optionalString(body, 'note') || null;
+  const dryRun = booleanFrom(body.dryRun, false);
+  const limit = Math.min(Math.max(tenantIds.length || 0, 100), 500);
+
+  const candidates = await usageOverageCandidateQuery({
+    tenantIds,
+    periodStart,
+    periodEnd,
+    includeExisting: true,
+    includeZero: false,
+    limit,
+  });
+
+  if (!candidates.length) {
+    return { item: { dryRun, createdCount: 0, skippedCount: 0, totalCents: 0, items: [], skipped: [] } };
+  }
+
+  if (dryRun) {
+    const wouldCreate = candidates.filter(item => !item.hasExistingInvoice);
+    const existing = candidates.filter(item => item.hasExistingInvoice);
+    return {
+      item: {
+        dryRun: true,
+        createdCount: 0,
+        skippedCount: existing.length,
+        totalCents: wouldCreate.reduce((sum, item) => sum + item.totalCents, 0),
+        items: candidates.map(item => ({ ...item, wouldCreate: !item.hasExistingInvoice })),
+        skipped: existing.map(item => ({
+          tenantId: item.tenantId,
+          subscriptionId: item.subscriptionId,
+          reason: 'USAGE_OVERAGE_INVOICE_EXISTS',
+          invoiceId: item.existingInvoiceId,
+          invoiceNo: item.existingInvoiceNo,
+        })),
+      },
+    };
+  }
+
+  const result = await transaction(async client => {
+    const created: Array<UsageOverageCandidate & { invoice: Record<string, unknown> }> = [];
+    const skipped: unknown[] = [];
+
+    for (const candidate of candidates) {
+      const lock = await client.query(
+        `
+        select id
+        from public.tenant_subscriptions
+        where tenant_id = $1
+          and id = $2
+        for update
+        `,
+        [candidate.tenantId, candidate.subscriptionId],
+      );
+      if (!lock.rows[0]) {
+        skipped.push({ tenantId: candidate.tenantId, subscriptionId: candidate.subscriptionId, reason: 'SUBSCRIPTION_NOT_FOUND' });
+        continue;
+      }
+
+      const existing = await client.query<{ id: string; invoiceNo: string; status: string }>(
+        `
+        select id, invoice_no as "invoiceNo", status
+        from public.tenant_invoices
+        where tenant_id = $1
+          and invoice_type = 'usage_overage'
+          and status <> 'void'
+          and billing_period_start = $2::date
+          and billing_period_end = $3::date
+          and metadata->>'source' = 'usage_overage_auto'
+        order by created_at desc
+        limit 1
+        `,
+        [candidate.tenantId, periodStart, periodEnd],
+      );
+      if (existing.rows[0]) {
+        skipped.push({
+          tenantId: candidate.tenantId,
+          subscriptionId: candidate.subscriptionId,
+          reason: 'USAGE_OVERAGE_INVOICE_EXISTS',
+          invoiceId: existing.rows[0].id,
+          invoiceNo: existing.rows[0].invoiceNo,
+        });
+        continue;
+      }
+
+      if (!candidate.items.length) {
+        skipped.push({ tenantId: candidate.tenantId, subscriptionId: candidate.subscriptionId, reason: 'NO_USAGE_OVERAGE' });
+        continue;
+      }
+
+      const invoice = await createInvoiceRecordWithClient(client, {
+        tenantId: candidate.tenantId,
+        invoiceType: 'usage_overage',
+        status,
+        dueDate,
+        billingPeriodStart: periodStart,
+        billingPeriodEnd: periodEnd,
+        note,
+        metadata: {
+          source: 'usage_overage_auto',
+          periodStart,
+          periodEnd,
+          subscriptionId: candidate.subscriptionId,
+          planCode: candidate.planCode,
+          tenantSlug: candidate.tenantSlug,
+        },
+        items: candidate.items.map(item => ({
+          ...item,
+          metadata: {
+            ...item.metadata,
+            periodStart,
+            periodEnd,
+            subscriptionId: candidate.subscriptionId,
+            planCode: candidate.planCode,
+          },
+        })),
+      });
+
+      await recordPlatformAudit(client, ctx, 'platform.invoice.usage_overage_created', 'tenant_invoice', invoice.id, {
+        tenantId: candidate.tenantId,
+        subscriptionId: candidate.subscriptionId,
+        planCode: candidate.planCode,
+        periodStart,
+        periodEnd,
+        totalCents: candidate.totalCents,
+        metrics: candidate.items.map(item => item.metadata.metricKey),
+        invoiceNo: invoice.invoiceNo,
+      }, candidate.tenantId);
+
+      created.push({ ...candidate, invoice });
+    }
+
+    const totalCents = created.reduce((sum, item) => sum + Number(item.totalCents || 0), 0);
+
+    await recordPlatformAudit(client, ctx, 'platform.invoice.usage_overage_batch_created', 'tenant_invoice_batch', null, {
+      createdCount: created.length,
+      skippedCount: skipped.length,
+      totalCents,
+      tenantIds,
+      periodStart,
+      periodEnd,
+      dueDate,
+      status,
+    });
+
+    return {
+      dryRun: false,
+      createdCount: created.length,
+      skippedCount: skipped.length,
+      totalCents,
+      items: created,
+      skipped,
+    };
+  });
+
+  return { item: result };
+}

apps/api/src/features/platform-admin/service.ts

@@ -97,7 +97,6 @@ export async function recalculateInvoiceTotals(client: pg.PoolClient, invoiceId:
         status = case
           when status = 'void' then status
           when $3 >= greatest(0, $2 - discount_cents + tax_cents) and greatest(0, $2 - discount_cents + tax_cents) > 0 then 'paid'
-          when status = 'draft' then 'issued'
           else status
         end,
         paid_at = case