兑换码

兑换码用于领取重置卡。用户领取后，可以自行决定何时使用卡片恢复额度。领取兑换码不会立刻重置用量。

创建兑换码

在后台的兑换码页面创建，主要参数如下：

参数	含义
生成数量	本次生成多少个兑换码，最多 200 个
自定义码	单个创建时可填写；批量生成使用随机码
卡片名称	可选自定义卡片名称；留空时默认按重置范围命名
重置范围	决定使用卡片时恢复的额度窗口：全部重置、仅 5 小时、仅 1 周、仅 1 个月，或勾选组合
可领取数量	一个兑换码最多发放多少张卡
卡片有效天数	从领取时开始计算的重置卡有效期
兑换截止时间	超过后不能再领取；未设置时不过期

每个账号对同一个兑换码只能领取一次，每次获得一张卡。例如可领取数量为 10，表示最多供 10 个不同账号各领取一次。

这里没有“自定义前缀后自动拼接”的表单规则。自定义的是完整兑换码；批量创建不支持指定同一个自定义码。控制台对应 code create [--name NAME] [--windows WINS] [--code TEXT] [--cards N] [--card-days D] [--expires-at MS] [--count N]，查看已有兑换码对应 code list。

导出兑换码

点击「导出兑换码」，可按创建时间选择起止范围。时间使用浏览器本地时区，结束时间包含所选分钟；任一端留空表示该方向不设限制。

面板会显示匹配数量，下载为每行一个兑换码的 TXT 文件。筛选依据是创建时间，不是兑换或到期时间；结果包含已兑换和已过期的码。没有匹配项或起止范围无效时不能下载。

领取与使用

用户在 /usage 输入兑换码，领取的卡会出现在可用卡片中，并按卡片名称、重置范围和到期日期聚合展示。使用一张卡后，该卡不能再次使用，且仅重置该卡指定的额度窗口（若为全部重置则清空该账号所有周期窗口计数）。

额度重置作用于计数，不删除历史用量账本，也不提高管理员配置的上限。

改掉已发出去的卡的到期时间与直接发放

在后台的用户页面打开一个账户，「重置卡」一节会列出它手上还能用的卡（展示卡片名称、重置范围与到期时间）。控制台里用 user cards held <id|用户名> 查看同一份列表。

管理员也可以在这里直接向用户发放指定名称与重置范围的卡片。下面的「重置卡到期日期」同时服务两个动作：

• 「发放重置卡」按填写的名称、重置范围与这个日期新发卡。控制台对应 user cards <id|用户名> [--name NAME] [--windows WINS] [--cards N] [--expires-at MS]。
• 「把手上的卡改到这个时间」把这个账户还没用掉的卡（包括已经过期的）统一 改到这个日期，不会新发卡。已经用掉的卡不会被改动——它换到的那次重置已经 发生了。

单张卡也可以在列表里用行末的「改期」按钮单独改。控制台里对应的是 user cards move <id|用户名> --expires-at <毫秒时间戳> [--ids ...].

收回一张卡

同一行末尾的「删除」按下第一次只是待确认，再按一次才真的删。只能删还没用掉 的卡（包括已过期的）；已经用掉的卡是那次重置的记录，删了会留下一个额度凭空恢复 过的账户，所以接口会拒绝。控制台里是 user cards drop <id|用户名> <卡 id>。

改期和删除都不会通知用户。 卡发出去的时候没有通知，收回来也没有；用户那边只 会在用量面板下次刷新时看到列表变了。

查看与删除

列表展示已领取数量、总数量和有效期。数量耗尽或超过截止时间后，不能继续领取。

删除兑换码会停止后续领取，已经领取到用户账户中的卡片不会被自动追回。

兑换失败

检查兑换码是否存在、是否过期、是否已领完，以及该账号是否已经领取过。连续尝试错误兑换码会受到限制，应等待提示的时间后再试。

实际用户接口为 POST /api/usage/redeem；使用卡片的接口为 POST /api/usage/cards/{id}/use，都需要登录会话。

如果卡片已消耗但额度重置因数据库错误失败，保留时间与账号信息，由管理员检查并处理。