用量与额度

MinuteShip 可以对任意功能做计量，不只是 AI 调用。每个功能从三种计费模式中选 一种，因此同一个站点可以同时有免费转换器、订阅专属工具和按次计费的生成器。

计费模式

模式	适用场景	用户体验
unlimited	免费工具、靠广告变现的页面	不拦截、不扣费
daily-limit	有升级引导的免费额度	每天固定次数，UTC 零点重置
credits	AI 调用、按次付费工具	每次使用扣除账户积分

没有配置模式的功能默认是 unlimited，所以新增工具不会在你不经意间挡住用户。

配置一个功能

打开 src/config/usage.ts，在 usagePolicies 里添加：

export const usagePolicies = {
  generateAiImage: { mode: 'credits', cost: 10 },
  'pdf.merge': { mode: 'daily-limit', perDay: 3 },
  'json.format': { mode: 'unlimited' },
};

字段	含义
mode	unlimited、daily-limit 或 credits
cost	每次调用消耗的积分（credits 模式）
perDay	每天允许的次数，按 UTC 计算（daily-limit 模式）

给某个 server function 加计量，只需在它的中间件里加上 usageGuard('功能标识')。调用失败会自动退回，生成失败不会扣用户积分。

设置套餐与注册赠送的积分

同样在 src/config/usage.ts：

export const walletConfig = {
  signupBonus: { enabled: true, amount: 50 },
  planCredits: { free: 0, pro: 1000, lifetime: 5000 },
};

• signupBonus —— 注册时赠送的积分，把 enabled 设为 false 即可关闭
• planCredits —— 每个套餐的每月额度，每个计费周期发放一次，下一周期开始时重置

让付费套餐拥有更高限额

套餐可以覆盖某个功能的策略，甚至可以切换模式：

export const planPolicyOverrides = {
  pro: {
    'pdf.merge': { mode: 'daily-limit', perDay: 100 },
  },
  lifetime: {
    'pdf.merge': { mode: 'unlimited' },
  },
};

套餐按用户的付费记录判定：优先有效订阅，其次买断，最后回落到 free。

用户看到什么

/settings/usage 展示积分余额（套餐额度与购买额度）以及用量记录。如果站点只 使用免费或每日限额功能，额度卡片会自动隐藏，只显示用量列表。

管理员可以做什么

页面	用途
/admin/usage	按用户查看余额和最近的用量记录
/admin/credits	手动加减积分，必须填写备注
/admin/orders	查看客户购买了什么、是否已支付

未登录访客

免费工具不要求登录：系统用 cookie 识别匿名访客，每日限额按浏览器计算。这足以 引导用户注册，但不是防刷措施——需要更强保护时请在边缘加限流。

说明

• 一次性购买的积分不会过期；套餐额度按周期重置。
• 订阅额度会在下一次读取余额时生效，因此支付成功后可能稍有延迟。
• 退款请在支付渠道后台处理。