fix(billing): apply margin multiplier to subscription quota consumption

Subscription plans now deduct period_tokens_used as upstream tokens ×
marginMultiplier, aligning package quota burn with wallet cost-mode pricing.

Co-authored-by: Cursor <cursoragent@cursor.com>

billing-admin-config.mjs

@@ -366,7 +366,7 @@ export function createBillingAdminConfigService(pool, { env = process.env, cache
         updatedBy: active.updatedBy,
         source: active.source,
         envOverrideActive: active.source === SOURCE_ENV_OVERRIDE,
-        formula: '最终扣费 = 上游成本(USD) × 汇率 × 毛利倍数（成本模式）；无上游成本时回退 Token 单价',
+        formula: '最终扣费 = 上游成本(USD) × 汇率 × 毛利倍数（成本模式）；无上游成本时回退 Token 单价；套餐额度扣减 = 实际上游 Token × 毛利倍数',
       };
     },
 

billing-subscription.mjs

@@ -197,10 +197,10 @@ export function createSubscriptionService(pool, { getPlanAsync = null } = {}) {
   };
 
   // Called inside an existing transaction (conn already in transaction).
-  // Deducts deltaTokens from the active subscription quota if available.
+  // Deducts quotaTokens (upstream tokens × billing marginMultiplier) from the active subscription.
   // Returns { fullyCovers: bool, overageRate: number }
-  const consumeQuota = async (userId, deltaTokens, conn) => {
-    if (!deltaTokens || deltaTokens <= 0) {
+  const consumeQuota = async (userId, quotaTokens, conn) => {
+    if (!quotaTokens || quotaTokens <= 0) {
       return { fullyCovers: true, overageRate: 1.0 };
     }
     const now = Date.now();
@@ -217,12 +217,12 @@ export function createSubscriptionService(pool, { getPlanAsync = null } = {}) {
     const unlimited = sub.periodTokensLimit === 0;
     const remaining = unlimited ? Infinity : sub.periodTokensLimit - sub.periodTokensUsed;
 
-    if (unlimited || remaining >= deltaTokens) {
+    if (unlimited || remaining >= quotaTokens) {
       await conn.query(
         `UPDATE h5_subscriptions
          SET period_tokens_used = period_tokens_used + ?, updated_at = ?
          WHERE id = ?`,
-        [deltaTokens, now, sub.id],
+        [quotaTokens, now, sub.id],
       );
       return { fullyCovers: true, overageRate: sub.overageRate };
     }

billing.mjs

@@ -78,3 +78,17 @@ export function computeDeltaCostCents(previous, current, config = loadBillingCon
   if (raw <= 0) return 0;
   return Math.max(config.minBillCents, Math.ceil(raw));
 }
+
+/**
+ * Subscription quota consumes weighted tokens: actual upstream tokens × marginMultiplier,
+ * mirroring wallet cost mode (upstream × rate × margin). Usage records still store raw
+ * input/output; only period_tokens_used applies this weight.
+ */
+export function computeSubscriptionQuotaTokens(deltaIn, deltaOut, config = loadBillingConfig()) {
+  const rawTokens = Math.max(0, Number(deltaIn ?? 0)) + Math.max(0, Number(deltaOut ?? 0));
+  if (rawTokens <= 0) return 0;
+  const margin = Number(config.marginMultiplier ?? 1);
+  const multiplier = Number.isFinite(margin) && margin > 0 ? margin : 1;
+  if (multiplier === 1) return rawTokens;
+  return Math.max(1, Math.ceil(rawTokens * multiplier));
+}

billing.test.mjs

@@ -1,6 +1,10 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { computeDeltaCostCents, normalizeTokenState } from './billing.mjs';
+import {
+  computeDeltaCostCents,
+  computeSubscriptionQuotaTokens,
+  normalizeTokenState,
+} from './billing.mjs';
 
 const config = {
   useBackendCost: false,
@@ -76,3 +80,14 @@ test('computeDeltaCostCents falls back to token path when accumulatedCost missin
   const costConfig = { ...config, useBackendCost: true, marginMultiplier: 3 };
   assert.equal(computeDeltaCostCents(previous, current, costConfig), 5);
 });
+
+test('computeSubscriptionQuotaTokens scales subscription quota by marginMultiplier', () => {
+  const billing = { ...config, marginMultiplier: 6 };
+  assert.equal(computeSubscriptionQuotaTokens(8000, 2000, billing), 60_000);
+  assert.equal(computeSubscriptionQuotaTokens(100, 0, billing), 600);
+});
+
+test('computeSubscriptionQuotaTokens leaves raw tokens when margin is 1', () => {
+  assert.equal(computeSubscriptionQuotaTokens(8000, 2000, config), 10_000);
+  assert.equal(computeSubscriptionQuotaTokens(0, 0, config), 0);
+});

user-auth.mjs

@@ -3,7 +3,12 @@ import fs from 'node:fs';
 import net from 'node:net';
 import path from 'node:path';
 import { Algorithm as Argon2Algorithm, hashRawSync as argon2HashRawSync } from '@node-rs/argon2';
-import { computeDeltaCostCents, loadBillingConfig, normalizeTokenState } from './billing.mjs';
+import {
+  computeDeltaCostCents,
+  computeSubscriptionQuotaTokens,
+  loadBillingConfig,
+  normalizeTokenState,
+} from './billing.mjs';
 import { buildInsufficientBalancePayload, loadRechargeConfig } from './billing-recharge.mjs';
 import {
   buildAgentExtensionPolicy,
@@ -1444,6 +1449,7 @@ export function createUserAuth(pool, options = {}) {
         tokenState.accumulatedOutputTokens - Number(previous?.lastOutputTokens ?? 0),
       );
       const deltaTokens = deltaIn + deltaOut;
+      const subscriptionQuotaTokens = computeSubscriptionQuotaTokens(deltaIn, deltaOut, config);
 
       await conn.query(
         `INSERT INTO h5_session_billing_state
@@ -1467,7 +1473,7 @@ export function createUserAuth(pool, options = {}) {
       // Subscription quota check: consume tokens from active plan before touching balance.
       let subscriptionCovered = false;
       if (costCents > 0 && subscriptionService) {
-        const coverage = await subscriptionService.consumeQuota(userId, deltaTokens, conn);
+        const coverage = await subscriptionService.consumeQuota(userId, subscriptionQuotaTokens, conn);
         if (coverage.fullyCovers) {
           costCents = 0;
           subscriptionCovered = true;

user-auth.test.mjs

@@ -878,6 +878,108 @@ test('billSessionUsage writes usage record when subscription fully covers tokens
   assert.equal(walletBalance, 200);
 });
 
+test('billSessionUsage applies marginMultiplier to subscription quota consumption', async () => {
+  const userRow = {
+    id: 'user-sub-2',
+    username: 'pro_user_2',
+    slug: 'pro_user_2',
+    email: 'pro2@example.com',
+    display_name: 'Pro User 2',
+    role: 'user',
+    status: 'active',
+    plan_type: 'pro',
+    workspace_root: '/tmp/pro-user-2',
+    balance_cents: 200,
+    tokens_used: 0,
+    spent_cents: 0,
+  };
+  const stateBySession = new Map();
+  let consumeQuotaTokens = null;
+
+  const subscriptionService = {
+    async consumeQuota(userId, quotaTokens) {
+      assert.equal(userId, userRow.id);
+      consumeQuotaTokens = quotaTokens;
+      return { fullyCovers: true, overageRate: 0.8 };
+    },
+  };
+
+  const billingConfigService = {
+    async getEffectiveBillingConfig() {
+      return {
+        useBackendCost: true,
+        usdCnyRate: 7.2,
+        marginMultiplier: 6,
+        inputCentsPer1k: 10,
+        outputCentsPer1k: 9,
+        minBillCents: 1,
+      };
+    },
+  };
+
+  const pool = {
+    async query(sql) {
+      if (sql.includes('FROM h5_users u') && sql.includes('WHERE u.id = ?')) {
+        return [[{ ...userRow }]];
+      }
+      throw new Error(`unexpected pool query: ${sql}`);
+    },
+    async getConnection() {
+      return {
+        async beginTransaction() {},
+        async commit() {},
+        async rollback() {},
+        release() {},
+        async query(sql, params = []) {
+          if (sql.includes('SELECT cost_cents FROM h5_usage_records WHERE request_id = ? LIMIT 1')) return [[]];
+          if (sql.includes('INSERT INTO h5_session_billing_state') && sql.includes('agent_session_id = agent_session_id')) {
+            return [{ affectedRows: 1 }, []];
+          }
+          if (sql.includes('FROM h5_session_billing_state') && sql.includes('FOR UPDATE')) {
+            const row = stateBySession.get(params[0]);
+            return [row ? [row] : []];
+          }
+          if (sql.includes('INSERT INTO h5_session_billing_state') && sql.includes('ON DUPLICATE KEY UPDATE')) {
+            stateBySession.set(params[0], {
+              last_accumulated_cost: params[2],
+              last_input_tokens: params[3],
+              last_output_tokens: params[4],
+            });
+            return [{ affectedRows: 1 }, []];
+          }
+          if (sql.includes('SELECT balance_cents, tokens_used FROM h5_user_wallets WHERE user_id = ?')) {
+            return [[{ balance_cents: 200, tokens_used: 0 }]];
+          }
+          if (sql.includes('INSERT INTO h5_usage_records')) {
+            return [{ affectedRows: 1 }, []];
+          }
+          throw new Error(`unexpected connection query: ${sql}`);
+        },
+      };
+    },
+  };
+
+  const auth = createUserAuth(pool, {
+    persistSessions: false,
+    subscriptionService,
+    billingConfigService,
+  });
+  const result = await auth.billSessionUsage(
+    userRow.id,
+    'session-sub-2',
+    {
+      accumulatedInputTokens: 8000,
+      accumulatedOutputTokens: 2000,
+      accumulatedCost: 0.01,
+    },
+    'req-sub-2',
+  );
+
+  assert.equal(result.ok, true);
+  assert.equal(result.costCents, 0);
+  assert.equal(consumeQuotaTokens, 60_000);
+});
+
 test('updateUser rejects quota smaller than occupied bytes', async () => {
   const userRow = {
     id: 'user-3',