配额管理

配额管理是 配额订阅模式（subscription_quota） 的专属功能。如果你使用的是其他模式，可以跳过这一页。

什么是配额

用户订阅后，每月获得固定的使用次数（配额）。比如 Pro 用户每月 500 次，用完就需要额外购买积分包。

配额配置

在 config/payment.ts 的 SUBSCRIPTION_PLANS 中设置：

pro: {
  priceMonthly: 29.99,
  priceYearly: 299.99,
  name: 'Pro',
  quota: 500,          // 月付用户每月 500 次
  quotaYearly: 750,    // 年付用户每月 750 次
  // ...
}

年付用户可以设置更高的月度配额作为优惠（quotaYearly），如果不设则和月付一样。

配额重置机制

配额按月重置，但月付和年付的重置逻辑不同：

月付用户

每次续费成功（收到支付方式的续费 Webhook）时重置配额。不提前发放——只有付了钱才重置。

年付用户

采用懒重置机制：每次用户访问服务时，系统检查是否到了重置日期。如果到了，自动重置配额并推进重置日期到下个月。

这样设计的原因是：年付用户一次付了一整年的钱，但配额是按月发放的，不需要等 Webhook。

配额用完怎么办

配额用完后，系统会自动降级到用户的积分余额（赠送积分 → 购买积分）。全部用完则拒绝访问。详见积分消费。

前端展示配额信息

通过 useAccess Hook 获取配额信息：

import { useAccess } from '@/hooks/useAccess'

function QuotaDisplay() {
  const { status } = useAccess()
  const { quota } = status.details

  if (!quota) return null

  return (
    <div>
      <p>本月配额: {quota.monthlyLimit}</p>
      <p>已使用: {quota.used}</p>
      <p>剩余: {quota.remaining}</p>
      <p>下次重置: {new Date(quota.resetDate).toLocaleDateString()}</p>
    </div>
  )
}

升降级时的配额变化

升级（立即生效）： 配额按新计划重置，已用量清零
降级（下个周期生效）： 当前周期保留原配额，下个周期切换为新计划的配额

On this page