feat: 支持排名分档额度固定计划

2026-07-18 06:41:49 +02:00
parent be33ce8881
commit dd98cb0735
7 changed files with 213 additions and 24 deletions
@@ -0,0 +1,30 @@
+# R3.9 任务报告
+
+## 目标
+
+完成 [UniDesk #2498](https://github.com/pikasTech/unidesk/issues/2498)，把按排名分档的异额客户发放从多批手工调用收敛为固定计划入口，不修改 Sub2API 源码、版本或生产运行面。
+
+## 通用能力
+
+- `--rank-tiers '<人数>:<金额>,...,*:<金额>'` 只允许用于活跃窗口 dry-run。
+- 排名固定按总 Token 降序、请求数降序、用户 ID 升序。
+- dry-run 输出窗口、排名、Token、逐人金额、总额及规范化 `--allocations-json`。
+- `--allocations-json` 使用稳定用户 selector 到正数金额的映射，一个 confirm 完成异额幂等写入与逐用户余额回读。
+- 排名窗口禁止 confirm，确认阶段不重新读取移动窗口决定名单。
+- 既有统一金额 `--users + --amount-usd` 的参数与幂等身份保持不变。
+- credits 与 announcements 局部 help 直接进入子命令，不再被平台根帮助截获。
+
+## 最短流程
+
+- 第一次 credits 调用生成排名计划，固定完整名单、逐人金额和总额。
+- 用户明确授权该计划后，第二次 credits 调用使用原样 allocations 加 confirm。
+- 公告继续独立 dry-run 和 confirm，避免把两个外部写操作伪装为原子事务。
+- 同类三档 credits 操作由 6 次降为 2 次；包含公告时整套流程由 9 次降为 4 次。
+
+## 验证
+
+- 局部 `credits --help` 与 `announcements --help` 均返回紧凑文本，无 target job、无输出保护。
+- 缺少最终通配档的 `--rank-tiers` 在本地失败并明确提示。
+- PK01 只读排名 smoke：11 名用户、1 名管理员排除、三档总额 520 USD，输出完整排名和固定 allocations，`mutation=false`、写入数 0。
+- PK01 固定 allocations smoke：11 名用户、异额总计 520 USD，`selection=exact-allocations`、`mutation=false`、写入数 0。
+- 未使用 `--confirm`，未重复充值、未发布公告、未修改 PK01 运行面。
@@ -293,7 +293,7 @@

 基于 PK01 Sub2API 原生最近24小时 usage 盘点活跃客户，按 Token 排名制定约 500 USD 的整额分档计划；经用户明确确认后，对固定11名用户按100、50、20 USD三档实际增发总计520 USD，逐用户回读余额，并发布包含北京时间窗口、排名、Token、稳定用户ID、脱敏邮箱和逐人金额的 active popup 公告并完成字段对账，完成任务后将详细报告写入[任务报告](./details/sub2api-upstream-reliability/R3.8_Task_Report.md)。

-### R3.9
+### R3.9 [completed]

 完成 [UniDesk #2498](https://github.com/pikasTech/unidesk/issues/2498)：增强 Sub2API 排名分档额度发放的固定计划入口，一个 dry-run 从原生 usage 生成包含窗口、排名、Token、稳定用户ID、逐人金额和总额的不可变计划，一个 confirm 完成异额批量幂等写入及逐用户余额回读；档位、金额、窗口和排除项全部参数化，不修改 Sub2API 源码、版本或生产运行面，并将本次流程沉淀为不含一次性值的通用案例，完成任务后将详细报告写入[任务报告](./details/sub2api-upstream-reliability/R3.9_Task_Report.md)。
 ## R4 [completed]