订阅管理

创建和维护订阅套餐，配置有效期、额度周期、分组权益与支付方式，并管理套餐的发布状态。

订阅套餐把价格、有效期、可用额度、额度重置周期、用户分组和支付方式组合成一项可购买的权益。
订阅管理仅 Admin 和 Root 可访问，从侧边栏「管理员」 → 「订阅」或访问 /subscriptions 进入，可以创建、编辑、启用、禁用套餐，以及批量重置某个套餐下的有效订阅额度。

Root 在「系统设置」 → 「计费与支付」 → 「支付网关」中确认支付合规条款之前，订阅管理页面只能查看套餐列表：页面顶部显示「管理员在支付网关设置中确认合规条款之前，订阅套餐的创建和修改会被锁定。」，「新建套餐」以及行内的编辑、重置订阅额度、启用/禁用按钮均不可用。

订阅管理概览

订阅管理-套餐列表

订阅管理-套餐列表页面

订阅管理列表同时显示启用和禁用的套餐。
页面右上角提示「Stripe/Creem 需在第三方平台创建商品并填入 ID」，旁边是「新建套餐」按钮。

列	说明
ID	套餐的唯一编号。排查订单、订阅或接口问题时，可用它确认关联的套餐。
套餐	套餐标题和副标题。
价格	用户购买套餐需要支付的金额。
有效期	每份新订阅从创建时开始计算的有效时长。
额度重置	可设置不重置、每天、每周、每月或自定义(秒)。
优先级	对应编辑表单中的「排序」值，只控制套餐展示顺序，不是模型或渠道路由优先级。
状态	启用表示可进入用户侧公开购买流程；禁用表示不再向用户展示。
支付渠道	已填写产品 ID 的支付渠道以徽标显示（Stripe、Creem、Waffo Pancake）；都未填写时为空。
套餐额度	每份订阅包含的总额度；`0` 显示为「无限制」。
升级分组	订阅创建后升级到的用户分组；也可配置「不升级」。
操作	提供编辑、重置订阅额度，以及启用或禁用操作。

使用前准备

创建套餐前，建议先完成以下检查：

Root 需要在「系统设置」 → 「计费与支付」 → 「支付网关」中确认支付合规条款。
明确套餐面向的用户、售价、有效期、总额度和额度重置方式。
如需改变用户分组，先在分组定价中创建并核对升级分组和降级分组。
如需第三方支付，先完成对应网关的全局凭证、回调地址和 Webhook 配置。
决定是否允许钱包余额兑换，以及订阅额度耗尽后是否允许继续使用钱包余额。

套餐保存成功不等于所有支付方式已经可用。第三方支付同时依赖套餐产品 ID、全局网关配置、回调可达性和支付平台中的产品状态；发布前应使用测试账户完成一次端到端购买验证。

创建订阅套餐

订阅管理-创建套餐

订阅管理-创建套餐页面

在订阅管理页面点击「新建套餐」。
在「基本信息」中填写套餐标题、价格、额度、分组、限购和排序等字段。
设置套餐是否立即启用、是否允许余额兑换，以及额度用尽后是否允许使用钱包余额。
在「有效期设置」中选择有效期单位和值。
在「额度重置」中选择重置周期；选择自定义周期时填写秒数。
如需 Stripe、Creem 或 Waffo Pancake 支付，填写或选择对应的产品标识。
点击「保存更改」。保存成功后，套餐状态由「启用状态」开关决定；新建表单默认启用。
返回列表核对价格、有效期、重置周期、状态、套餐额度和升级分组，再到用户侧检查展示与购买流程。

基本信息参数

界面字段	API 字段	类型、默认值与范围	生效方式与注意事项
套餐标题	`title`	必填文本；新建时为空。	显示在管理列表和用户侧套餐卡片中。只填写空白字符会被拒绝。
套餐副标题	`subtitle`	可选文本；新建时为空。	用于补充适用场景或权益摘要，不参与计费。
套餐价格	`price_amount`	数值；默认 `0`；后端允许 `0–9999`。	表示用户购买一次套餐需要支付的金额。套餐记录的 `currency` 固定保存为 `USD`，具体支付币种和结算行为仍受网关配置影响。
额度	`total_amount`	非负数；默认 `0`；`0` 表示不限总额度。	界面显示单位跟随实例的计费显示设置，保存时会换算为内部 quota。该额度会在创建用户订阅时写入权益快照。
升级分组	`upgrade_group`	可选；默认「不升级」；选项来自当前分组配置。	创建订阅时把用户切换到目标分组，并保存购买前分组。目标分组不存在时无法保存。
降级分组	`downgrade_group`	可选；默认「降级到购买前分组」；选项来自当前分组配置。	订阅到期、作废或删除时优先切换到指定分组；留空时按条件尝试恢复购买前分组。
限购	`max_purchase_per_user`	非负整数；默认 `0`；`0` 表示不限。	统计该用户在此套餐下仍存在的全部订阅记录，包括已过期、已作废和管理员添加的记录。删除记录后才会释放对应次数。
排序	`sort_order`	整数；默认 `0`。	数值越大，套餐在管理列表和用户侧越靠前；列表中显示为「优先级」。
启用状态	`enabled`	开关；默认开启。	控制套餐是否进入公开展示和普通购买流程，不会终止已经创建的订阅。
允许余额兑换	`allow_balance_pay`	开关；默认开启。	开启后，余额足够的用户可以用钱包余额购买；关闭后，购买弹窗中的「使用余额支付」不可用，并提示「该套餐不允许使用余额兑换」。
额度用尽后允许使用钱包余额	`allow_wallet_overflow`	开关；默认开启。	创建订阅时写入权益快照。是否实际回退钱包还取决于用户选择的计费偏好。

界面中的「额度」不是所有部署都固定显示为美元。其标签和步进值会跟随实例的货币或 Token 显示设置，最终保存为 AIMirrorX 内部 quota；配置和核对时应使用当前实例显示的单位。

有效期参数

界面字段	API 字段	可选值与默认值	计算方式
有效期单位	`duration_unit`	年、个月、天、小时、自定义(秒)；默认「个月」。	决定如何从订阅创建时间计算结束时间。
有效期数值	`duration_value`	正整数；默认 `1`；单位选择「自定义(秒)」时不显示，改为填写「自定义秒数」。	年和月按日历增加；日按 24 小时、小时按固定小时数增加。
自定义秒数	`custom_seconds`	单位选择「自定义(秒)」时必须大于 `0`。	直接把指定秒数加到订阅创建时间。非正值会导致订阅无法创建。

有效期在每份用户订阅创建时计算并保存。之后修改套餐的有效期，不会延长或缩短已经存在的订阅。

额度重置参数

界面字段	API 字段	可选值与默认值	生效方式
重置周期	`quota_reset_period`	不重置、每天、每周、每月、自定义(秒)；默认「不重置」。	决定订阅的下一次额度重置时间。每天推进到次日，每周推进到下一个周一，每月推进到下月第一天。
自定义秒数	`quota_reset_custom_seconds`	重置周期为「自定义(秒)」时才可填写，必须大于 `0`。	从当前计算基准向后增加指定秒数。下一次重置晚于订阅结束时间时，不再安排重置。

重置额度只会把已用额度清零，不会改变套餐总额度，也不会延长订阅有效期。

第三方支付参数

界面字段	API 字段	套餐侧用途	权限与依赖
Stripe Price ID	`stripe_price_id`	将套餐关联到 Stripe Price，并用 Stripe Checkout 的 `subscription` 模式创建首次购买会话。	还需配置全局 Stripe API Secret、Webhook Secret 和充值用 Stripe Price ID；套餐 Price ID 与系统充值 Price ID 是两个独立配置。套餐 Price 必须适用于订阅模式。
Creem Product ID	`creem_product_id`	将套餐关联到 Creem 产品。	还需配置全局 Creem API Key、Webhook Secret 和产品列表；套餐 Product ID 与系统充值产品配置是两个层级。
Waffo Pancake Product ID	`waffo_pancake_product_id`	从已保存店铺的一次性产品中选择套餐产品。	产品列表和「+ 新建」接口要求 Root，并依赖 Merchant ID、Private Key、Store ID 和回调配置。当前网关启用判定还要求系统已配置钱包充值用 Pancake Product ID；它与套餐 Product ID 不能混用。

EPay 没有套餐级产品 ID。启用全局 EPay、配置至少一种支付方式且套餐价格不低于 0.01 后，用户可以按套餐价格创建 EPay 订单。钱包余额购买同样不需要第三方产品 ID。

Stripe 和 Creem 下单时分别以套餐的外部 Price ID 或 Product ID 为准，实际扣款金额与币种由第三方产品决定；AIMirrorX 列表展示和订单记录使用本地「套餐价格」。发布前必须确保外部产品与本地价格完全一致。修改一端不会自动同步另一端。
Stripe 套餐使用 subscription 模式创建周期性订阅。Stripe 会按所选 Price 的周期自动续费，直到订阅被取消。Stripe 后续的续费扣款不会在 AIMirrorX 中创建或延长订阅，本地订阅仍按套餐有效期到期；上线前请在 Stripe 后台确认取消方式，并告知用户续费规则。

创建 Waffo Pancake 产品

「Waffo Pancake Product ID」右侧的「+ 新建」会使用当前表单中的套餐标题和价格，在已保存的 Pancake 店铺中创建并发布一个一次性产品，然后把返回的产品 ID 填入表单。

执行前需要满足：

当前账户是 Root；
已在计费与支付设置中完成 Waffo Pancake 凭证和店铺配置；
套餐标题不为空；
套餐价格大于 0。

该操作会先在第三方平台创建产品，之后仍需保存套餐表单。若第三方产品创建成功但套餐保存失败，Pancake 中的产品不会由 AIMirrorX 自动删除，应到第三方平台核对并按需清理。

编辑订阅套餐

订阅管理-编辑套餐

订阅管理-编辑套餐页面

在目标套餐右侧点击编辑图标。
核对表单中回填的基本信息、有效期、重置周期和产品 ID。
修改需要调整的字段并点击「保存更改」。
返回列表确认新值；如涉及支付、分组或重置周期，再完成相应的购买或额度重置验证。

编辑套餐主要影响后续购买和新建订阅，不是批量迁移既有订阅的工具。各类字段对已有订阅的影响如下：

套餐字段	对已有订阅的影响
价格、允许余额兑换、启用状态、排序、支付产品 ID	影响后续展示或购买，不改变已购买订阅的权益。
有效期、总额度、升级分组、降级分组、额度用尽后允许使用钱包余额	购买订阅时写入快照；修改套餐不会重写已有订阅中的对应值。
额度重置周期、自定义重置秒数	自动重置或管理员选择推进下次重置时间时，会读取套餐当前规则，因此可能影响已有的有效订阅。
限购	后续购买或管理员添加订阅时重新统计现存记录并应用当前上限。

待支付订单保存的是套餐 ID 和下单金额。支付回调完成订单时会重新读取套餐并创建权益；用户支付期间若修改套餐的有效期、额度、分组或「额度用尽后允许使用钱包余额」配置，最终创建的权益可能与下单时看到的内容不同。高风险调整应先暂停公开购买并处理待支付订单。

启用和禁用套餐

订阅管理-启用套餐

订阅管理-启用套餐页面

订阅管理-禁用套餐

订阅管理-禁用套餐页面

在套餐行末点击状态图标（已启用的套餐显示「禁用」图标，已禁用的套餐显示「启用」图标），再在「确认启用」或「确认禁用」对话框中点击「启用」或「禁用」。两项操作的效果如下：

启用：套餐重新进入用户侧公开展示和普通购买流程。
禁用：套餐不再向用户显示，也不能发起新的普通购买。

禁用套餐不会：

取消或暂停已经购买的用户订阅；
清零订阅额度或改变结束时间；
使历史订单失效；
阻止已经创建的待支付订单在成功回调后完成；
阻止管理员在用户管理中为指定用户添加该套餐。

当前订阅管理页面没有删除套餐功能。禁用是发布状态控制，不是撤销权益；如需立即终止某个用户的订阅，应在「用户管理」 → 「管理订阅」中执行作废操作，并先确认分组回退和其他有效订阅的影响。

重置订阅额度

订阅管理-重置订阅额度

订阅管理-重置订阅额度页面

套餐列表中的重置操作会处理该套餐下所有状态为生效的订阅：

点击目标套餐右侧的重置图标。
确认对话框中的套餐名称。
决定是否开启「推进下次重置时间」。该开关默认开启。
点击「重置额度」。成功提示会显示实际重置的有效订阅数量。

选项	实际行为
开启「推进下次重置时间」	清零已用额度，并按套餐当前重置规则重新计算下一次重置时间。
关闭「推进下次重置时间」	只清零已用额度，保留订阅原有的下一次重置时间。

这是对套餐下所有用户的批量操作。执行前应确认目标套餐、重置周期和影响人数；尤其不要把它当作给单个用户补额度的快捷方式。单个用户的重置应从「用户管理」 → 「管理订阅」执行。

用户订阅与权益状态

订阅管理页面维护的是「套餐定义」。某个用户已经获得的订阅，需要在「用户管理」中打开该用户的「管理订阅」进行维护。管理员可以在那里添加订阅、按套餐重置额度、使订阅作废或删除订阅记录。

用户订阅状态	含义
`active`（生效）	订阅处于有效期内，可以按计费偏好参与额度结算。
`expired`（已过期）	到达结束时间后，被后台维护流程标记为已过期。
`cancelled`（已作废）	管理员提前执行作废，结束时间同时改为当前时间。

「作废」会保留订阅历史记录；「删除」会硬删除该条订阅记录且没有恢复入口。删除订阅并不表示相关支付订单、充值流水、使用日志或任务记录也会被一并删除。完整操作说明参阅用户管理。

分组升级与回退

如果套餐配置了升级分组，订阅创建时系统会立即尝试把用户切换到该分组，并在订阅中记录购买前分组。订阅到期、被管理员作废或删除时，回退逻辑如下：

用户还有其他生效中、且设置了升级分组的订阅时，保持当前分组不变。
否则，订阅设置了降级分组时，直接切换到该分组；即使用户分组已被手动修改，也会被改为降级分组。
没有设置降级分组时，只有用户当前仍处于该订阅的升级分组，才恢复购买前分组。购买时用户已在升级分组中的，订阅没有记录购买前分组，因此不回退。

执行作废或删除前，应先检查用户的当前分组和其他有效订阅。

支付方式与续费边界

支付方式	套餐要求	创建订阅的方式
钱包余额	开启「允许余额兑换」，用户余额充足。	按 `ceil(套餐价格 × QuotaPerUnit)` 扣除内部额度，并立即创建一份订阅。
EPay	全局 EPay 已启用且有可用支付方式；套餐价格至少为 `0.01`。	支付回调成功后创建一份订阅，不需要套餐产品 ID。
Stripe	套餐填写 Stripe Price ID，全局 Stripe 与 Webhook 配置完整。	首次 Checkout 支付确认后创建一份本地订阅。
Creem	套餐填写 Creem Product ID，全局 Creem 和回调配置完整。	支付回调成功后创建一份订阅。
Waffo Pancake	套餐选择独立的 Waffo Pancake Product ID，全局凭证、店铺和回调配置完整。	购买一次性产品并在回调成功后创建一份订阅。

用户可以在钱包页面选择「优先订阅」「优先钱包」「仅用订阅」或「仅用钱包」。
套餐的「额度用尽后允许使用钱包余额」只在用户选择「优先订阅」时起作用：订阅额度不足时，只有用户所有生效中的订阅都开启了该选项，才会继续使用钱包余额。该选项不会覆盖用户自己的计费偏好。
用户侧购买、订阅状态和计费偏好说明参阅钱包与订阅。

自动维护机制

订阅到期和周期额度重置由后台维护任务处理：

只在 Master 节点运行；
服务启动后先执行一次，之后约每分钟检查一次；
每批最多处理 300 条记录；
到期处理会更新订阅状态，并按条件执行用户分组回退；
周期重置只处理状态仍为生效的订阅。

若订阅长时间未被标记为已过期，或到期后分组没有回退，应检查 Master 节点、后台任务运行情况和应用日志。