赠金与签到
三个额度窗口（5 小时、每周、每月）是每个账户日常的额度。赠金条是管理员在窗口之外另加的一条额度，有自己的规则；签到是让用户每天点一次，攒够天数就能领取赠金或重置卡。
两者都在后台的「赠金」页管理（需要「用量」权限）。设计的完整规则见赠金与签到（设计），这一页讲怎么用。
名词
| 名词 | 含义 |
|---|---|
| 赠金条 | 一组规则：名称、谁能开关、是否公开数额、适用哪些模型、默认到期时间 |
| 赠金 | 某个账户在某条赠金条里的一笔额度：数额、已用多少、何时到期、来源 |
| 备用额度 | 一种赠金条，只在所有其他额度都用完之后才动用 |
赠金的单位是积分，和模型定价、窗口里的「积分」上限是同一把尺子。因此没有设置价格的模型（每次 0 积分）不会动用赠金，赠金条对它们没有意义。
新建赠金条
点「新建赠金条」，填写：
| 字段 | 说明 |
|---|---|
| 名称 / 说明 | 都会显示给用户；说明按纯文本显示，不解析标记 |
| 类型 | 「赠金」，或「备用额度」（见下） |
| 开关 | 「用户自选」：用户决定要不要优先用它；「始终优先」：不管用户怎么想都优先用；「仅在额度用完后」：留到窗口用完之后才用。备用额度没有这一项 |
| 默认开启 | 只对「用户自选」有意义：用户还没选过时是开还是关，默认开 |
| 显示数额 | 关闭后，用户只看到剩余的百分比和「已用完」，看不到 1000 这样的总数。这一项只在系统设置里的「用量显示为」是「具体数值」时才起作用：选「剩余」或「已用」时，所有赠金条本来就只显示百分比 |
| 适用模型 | 勾选后，只有这些模型的请求会动用这条赠金条；一个都不勾表示全部模型 |
| 默认到期时间 | 发放时没有另外指定有效期，就用它；留空表示不过期 |
| 使用中 | 关闭后停止动用和显示，已发的数额保留 |
改规则立刻对所有人生效，已经发出去的数额不受影响。
一次请求怎么扣
请求先确定要用的模型，然后按这个顺序找额度，够了就停：
- 优先使用的赠金：「始终优先」的，以及「用户自选」且用户开着的。同一个用户有多笔时，先到期的先用。这一步付掉的部分不占用窗口额度。
- 窗口额度：和没有赠金时完全一样。
- 后备赠金：窗口不够时，才动用「仅在额度用完后」的、用户自选但关着的，以及备用额度（备用额度排最后）。后备必须整笔覆盖这次请求才动用，不拆分。
- 重置卡：用户开了「自动使用重置卡」时，再花一张卡。赠金会过期而卡是用户自己攒的，所以赠金排在卡前面。
- 都不行：照旧返回 429，并告诉用户什么时候恢复。
「用户自选但关着」的赠金条不是不能用，只是「先不用」，会退到第 3 步。想让一条赠金用户绝对用不了，就别发给他。
每分钟的频率限制（RPM、TPM）不受赠金影响。 它们是保护上游服务商的突发限制，不是额度：一个请求即使整笔由赠金支付，也照样计入并受限制，被拒绝的请求不会动用赠金。
不设限的账户不动用赠金：默认设置下管理员不受额度限制，请求根本不预留额度，赠金也就不会被扣。
发放赠金
在赠金条的面板里点「发放」：
| 字段 | 说明 |
|---|---|
| 发给谁 | 所有人、某个用户组，或指定用户名（逗号分隔，不区分大小写） |
| 每个账户的积分 | 大于 0、不超过 1,000,000；填错三个零不会悄悄发给所有人 |
| 有效期（天） | 自现在起多少天后到期；留空则用赠金条的默认到期时间，两者都没有就不过期 |
| 备注 | 一句话，会写进这笔赠金的记录 |
一次发放是一个整体：任何一个用户名不存在，整次都不发。「所有人」包括全部账户，含已停用的。每个收到赠金的账户会收到一条站内通知。
查看、收回、停用与删除
- 查看：赠金条面板里的「已发放」列出每笔赠金——账户、已用/总额、到期时间、来源（管理员发放或签到）、备注。
- 收回：点某笔赠金的「收回」，只收回没用完的部分；已经用掉的部分保留在记录里。
- 停用：把「使用中」关掉，停止动用和显示，数额保留，重新开启后继续。
- 删除：连同其中所有赠金一起删除，不能恢复，所以要先确认一次。
到期
到期时刻之后，那一笔不再被动用（不会被删除，仍在记录里）。到期前 3 天，系统给持有人发一条站内通知，每笔赠金只通知一次，同一个账户同一条赠金条里快到期的几笔合并成一条。
备用额度
类型选「备用额度」，就是所有额度（窗口和各条赠金）都用完之后才动用的一笔，比如「用完之后再送 20 积分」。它没有用户开关，永远排在最后，也可以像赠金一样限定模型、设置到期时间。
备用额度是预先发好、最后才动用的，用户在到账前就能看见它；不是「用完之后才凭空出现」。
共享额度池
类型选「共享额度池」，就是所有账户共用的一份余额，只给它勾选的模型用（一个都不勾表示所有模型）。它没有「发放」，管理员直接给池子充值；每个用户都能看到它，不需要持有什么。
| 字段 | 说明 |
|---|---|
| 开关 | 「用户自选」：每个用户自己决定要不要优先用池子，关着的话池子退到窗口用完之后再用；「强制启用」：这些模型的请求先扣池子，池子用完（或当天份额用完）就改扣用户自己的额度；「只能用额度池」：这些模型只从池子扣，不碰窗口、不碰用户自己的赠金、不用重置卡，池子用完或当天份额用完就直接拒绝（429，告诉用户什么时候恢复） |
| 重置 | 「不重置」：充多少用多少；「每天 / 每周（周一）/ 每月」：每个周期开始时把余额重置为「重置为」的数额。周期按签到设置的时区算。手动充值的部分只保留到下次重置 |
| 初始余额 | 只在新建时填；留空则等于「重置为」 |
| 每人每天上限 | 一个账户一天最多从池子里用多少，留空或 0 表示不限，用来防止一个人把池子吃光 |
建好之后，打开池子的面板可以看到剩余余额和今天有几个账户用过，在「调整余额」里选「增加」（填负数是扣掉，最多扣到 0）或「设为剩余」。
几点要知道：
- 池子排在扣费顺序的最前面：在「优先使用的赠金」之前先扣池子；后备阶段同样先扣池子。
- 「只能用额度池」时，请求结束后的实际花费即使超过预留，也全部记到池子上，不会转到用户的窗口。
- 不设限的账户（默认是管理员）不动用池子，和赠金一样。
- 池子不能用作签到奖励，也不能和别的类型互相转换。
用户看到什么
用户在 /usage 的「赠金」一节看到自己持有的每条赠金条：
- 名称、剩余多少、最近的到期时间、适用模型数量。「剩余多少」的措辞跟额度窗口一致，由系统设置里的「用量显示为」决定：「剩余」显示「还剩 60%」，「已用」显示「已用 40%」，「具体数值」显示「剩余 6 / 10」（不公开数额的赠金条仍显示百分比）。
- 一行说明这条赠金现在是「先于额度使用」还是「在额度之后使用」。
- 「用户自选」的赠金条有一个「优先使用」开关；强制的那几条只显示状态。
- 共享额度池也显示在这里，标着「所有人共用」，有每人每天上限的话会写「今天已用 X，每人每天 Y」，定期重置的会写下次重置时间。
签到
后台「赠金」页下方的「签到」一节：
| 设置 | 说明 |
|---|---|
| 签到 | 整体开关，关闭时用户端什么都不显示 |
| 时区 | 「一天」按这个时区算，默认 Asia/Shanghai；写错的名字按 UTC 处理，保存时会拒绝 |
| 每次签到的奖励 | 可以什么都不给，也可以每次给一笔赠金（选哪条赠金条、数额、几天后到期）或重置卡 |
| 里程碑 | 一张表，每行是「连续签到 N 天」或「本月累计签到 N 天」→ 奖励，最多 30 行 |
奖励有两种：赠金（选赠金条、数额、有效天数；有效天数留 0 则用赠金条的默认到期时间）和重置卡（名称、重置范围、张数、有效天数）。
里程碑要**用户自己点「领取」**才发。一个周期内每行只能领一次：连续天数的周期是这一段连续，本月累计的周期是自然月。用户漏签一天，连续天数就从头算。
防刷：
- 每个账户每天只能签到一次，靠数据库唯一键保证，多个请求同时到达也只记一天、只发一次奖励；里程碑的领取同理。
- 已停用的账户不能签到；实例要求验证邮箱才能对话的，没验证邮箱的账户也不能签到。
- 保存设置时就检查：赠金奖励指向的赠金条必须存在且在使用中，数额、天数、张数都要在合理范围内。
如果每次签到的奖励发不出去（比如它指向的赠金条后来被删了），签到本身仍然记录，界面会提示奖励没有到账。这时去后台修正奖励设置。
控制台命令
| 命令 | 作用 |
|---|---|
bonus list create edit delete | 管理赠金条 |
bonus grant grants revoke | 发放、查看、收回 |
bonus pool | 给共享额度池充值或设定剩余（--add N / --set N） |
checkin config config set | 查看和修改签到设置 |
credit bonus credit bonus switch | 用户查看自己的赠金条、开关「优先使用」 |
checkin checkin now checkin claim | 用户查看签到、签到、领取里程碑 |
以上管理命令需要「用量」权限；用户命令所有账户都可用。bonus grant、bonus revoke、bonus delete 需要加 --yes 才会执行。checkin config set 的奖励和里程碑用 JSON 传入。详细参数用 <命令> --help 查看。
接口
| 接口 | 权限 | 说明 |
|---|---|---|
GET/POST /api/admin/bonus/bars | 用量 | 列出、新建赠金条 |
PUT/DELETE /api/admin/bonus/bars/{id} | 用量 | 修改、删除赠金条 |
GET/POST /api/admin/bonus/bars/{id}/grants | 用量 | 列出、发放 |
DELETE /api/admin/bonus/grants/{id} | 用量 | 收回一笔 |
POST /api/admin/bonus/bars/{id}/pool | 用量 | 给共享额度池充值（{"op":"add","amount":N}）或设定剩余（"op":"set"） |
GET/PUT /api/admin/checkin | 用量 | 读取、保存签到设置 |
GET /api/bonus、PUT /api/bonus/{id}/choice | 登录用户 | 自己的赠金条、开关 |
GET/POST /api/checkin、POST /api/checkin/claims/{rule} | 登录用户 | 签到状态、签到、领取 |