# 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 运行面。
