feat: add audited async task reconciliation and frozen bindings

This commit is contained in:
xpp committed 2026-10-21 20:08:38 +08:00
1 parent 5be06a97c1
commit c716ec7478
28 files changed
+1312 -76

No files matched your search

+1 -1
View File
@@ -64,7 +64,7 @@ PostgreSQL 集成测试由 `MOYI_AUTH_TEST_JDBC_URL` 启用,当前测试限制
## 下一阶段优先级
1. 已完成 `V45`:异步创建 `Idempotency-Key`、请求哈希和数据库唯一性/锁语义,客户端同键重试不重复排队或预留。
2. 已完成 `V46` 的未知受理持久状态与冻结保护;审计化人工核账入口仍待实现。详情及本阶段 190 项后端验证结果见 `22-async-task-safety.md`。
2. 已完成 `V46` 的未知受理持久状态与冻结保护;V47/V48 后续补人工核账与执行绑定,详见 `23-audited-task-reconciliation.md`。本阶段原始 190 项后端验证结果见 `22-async-task-safety.md`。
3. 已增加异步已观察终态的结算恢复与待核账提示;继续完善执行路由快照、重试退避、人工对账和不可原子提交窗口。
4. HTTP Transport 生命周期继续拆分;真实 Redis 并发、租约回收与队列公平性回归。
5. 再进入用户/角色/会话、管理操作与密钥生命周期的后续安全优化;本轮模块改造不替代完整审计。
+2 -2
View File
@@ -46,11 +46,11 @@
1. 本阶段只验证隔离测试数据库,没有迁移业务数据库或部署线上服务。发布时先停旧 worker,再迁移 `V45` / `V46` 并启新 worker,避免混跑旧的自动退款逻辑。
2. 不回溯改写历史失败任务或重新冻结曾经释放的资金。历史的提交中断、超时、凭据丢失记录须独立审计,不能自动扣款。
3. 待核账状态不会按 TTL 自动退款,不会自动重发。收集本地任务 ID、用户、时间、模型路由、预留金额、上游任务/账单记录;不要把完整凭据放进工单或日志。
4. 暂不提供“无证据一键退款/重新生成”的管理接口。受审计的人工核账入口、关联上游任务编号、人工确认终态以及差额结算是下一阶段产品工作;在该入口完成前,只允许按受控运维流程核对证据,不直接修改钱包余额替代结算事务。
4. 后续 V47/V48 已补受审计的人工核账入口:恢复只读查询、确认失败释放原冻结、按原快照确认成功,详见 `23-audited-task-reconciliation.md`。不提供无证据一键退款、重新生成、任意改余额或追扣已释放资金。
5. 成功的 token 图片任务缺少可核验用量时,仍沿用既有 `TASK_USAGE_PENDING` 规则:保留结果、暂不扣费、释放该次预留并标记待核账。本阶段没有把“已知完成但计量缺失”与“是否受理未知”混为一类。
6. HTTP 受理至观察日志提交之间仍有无法跨外部系统原子提交的窗口。数据库完全不可用时也不能承诺保存回执;恢复后转入待核账,而非声称精确恢复所有生成结果。
后续重点:审计化人工核账入口、异步路由/上游模型的执行快照、共享有界 HTTP Transport 与媒体下载安全、上游有证明的幂等能力适配。
后续人工核账与 provider/model 执行绑定已在 V47/V48 完成,范围及剩余限制见 `23-audited-task-reconciliation.md`。继续重点处理共享有界 HTTP Transport、媒体下载安全、完整配置版本绑定与上游有证明的幂等能力适配。
### 最终验证
+73
View File
@@ -0,0 +1,73 @@
# 人工任务核账与执行绑定
日期:2026-10-21。本阶段只在本地隔离环境实现和验证,未迁移业务数据库、未调用真实供应商生成接口、未发布线上服务。
## 模块边界
| 模块 | 职责 | 明确禁止 |
| --- | --- | --- |
| `TaskReconciliationController` | 管理会话 HTTP 适配,JSON / 自定义头防跨站表单屏障 | 上游生成、直接改账 |
| `TaskReconciliationService` | 管理员校验、证据引用、版本检查、幂等收据、人工决策事务 | 任意指定扣款金额、自动重发生成 |
| `TaskSettlementService` | worker 与人工核账共享的任务/钱包/用量原子结算及预留释放 | 另起一套人工钱包加减逻辑 |
| `TaskOutcomeJournal` | 记录已观察终态和未知结果 | 代替财务决策 |
| `AsyncProviderClient.requirePollableBinding` | 本地验证查询能力及已有凭据指纹 | 验证时发 HTTP、接受原始 API Key |
| `TaskReconciliationResult` | 有界结果地址与规范化数值用量白名单 | 原始上游响应、任意字段、base64、大段内容 |
`AsyncTaskService` 的钱包结算逻辑已移动到共享 `TaskSettlementService`,worker 门面只委派调用;不复制两份扣费逻辑。已知成功但用量缺失的既有 `TASK_USAGE_PENDING` 语义暂不改变;人工成功确认则必须严格校验用量,校验失败不修改状态、不释放冻结。
## 管理端入口
“价格版本与成本对账”页面增加“异步任务人工核账”区块。它与原采购成本核对是不同流程:采购成本核对不改用户消费,任务核账可能将原冻结额转为消费或释放。
- `GET /api/admin/task-reconciliation?page=1`:每页 50 笔待核账任务,返回总数。
- `GET /api/admin/task-reconciliation/{taskId}`:最小任务视图与最近 50 条操作历史。查询不加载任务提示词、输入或生成媒体。
- `POST /api/admin/task-reconciliation/{taskId}/quote`:只读金额预览,请求体为规范化结果/用量对象;使用任务原价格快照,返回金额和版本,不写账。
- `POST /api/admin/task-reconciliation/{taskId}`:执行有证据的核账决定;须有 `Content-Type: application/json`、`X-Moyi-Source: console` 和有效管理员 Cookie 会话。自定义头只是与已有严格 CORS 白名单配合的跨站屏障,不是身份或风控来源证明。
每次操作必须包含 UUID `requestId`、原 `expectedUpdatedAt`(保留服务器完整精度)、`evidenceReference`(3–500 字)、`note`(10–2000 字)。不得将凭据粘入证据/说明。证据为管理员人工核对后填写的引用,服务端不自动证明引用真实,不会访问或下载证据 URL。
### 三类决定
1. **`resume_polling`**:恢复原任务的只读轮询,不生成、不退款、不扣款。需要已证实的上游编号和原账号 SHA-256 指纹;账号须仍在服务端凭据池中,执行器须支持该媒体类型的查询。已知编号/账号不能改绑;原执行绑定无法证明的历史任务禁止猜测恢复。允许对有证据的新式回执丢失任务补原编号。
2. **`confirm_failed`**:管理员根据上游失败或明确未受理的记录,确认失败;共享结算事务释放原冻结和预算占用,不额外给钱包充值。不能附带金额或成功结果。
3. **`confirm_succeeded`**:管理员核实成功与计费用量,先预览并确认 `expectedCost`;金额必须等于原价格快照结合该用量的计算结果。没有快照的历史固定价任务沿用原预留额,不拿当前目录价补算。不能任意填写价格、改变上游绑定,缺少 token 用量时拒绝操作。实际费用可超过原预留,沿用现有真实用量记债语义,界面须显式确认。
结果/用量 JSON 最多 32 KiB,仅允许 HTTP(S) 资产地址、format/mimeType 和数值 usage/usageMetadata。URL 不会被后台下载;禁止 userinfo 和非 HTTP(S) scheme。结果字段仍保存在任务既有 result 列,操作收据不复制媒体或提示词。
## 并发、账务与审计
- 操作前使用真实会话鉴权;事务内锁住仍启用的管理员角色并再次检查会话,防止使用过期的预检查结果。普通用户和无会话请求不可访问,幂等重放也要鉴权。
- 同一操作编号取 PostgreSQL advisory lock,以 `request_id` 主键兜底;请求摘要包含任务、动作、版本、证据、说明、规范化结果及确认金额。只有同一管理员原请求可重放;编号用于不同动作/内容或不同管理员返回 409。
- 锁任务行,验证 `reconciling`、无已观察终态、无既有 cost 和完整 updatedAt 版本;锁钱包验证原冻结额仍存在。不同管理员竞争只有一个成功,另一方刷新后再决定,不覆盖可信终态,不用平衡数填补资金缺口。
- 状态、原价结算/释放、用量审计、`task_reconciliations` 收据及 `auth_audit_log` 在同一数据库事务提交;审计失败时全部回滚。Redis 新租约回滚只释放新租约,不删除事务前已存在的任务租约。
- `V48` 收据保存操作者、操作编号、时间、动作、证据引用、说明和最小前后状态。数据库触发器禁止 UPDATE / DELETE;这不是防数据库所有者、超级用户或禁用触发器的防篡改承诺,生产仍需最小权限和独立审计备份。
- 页面提交后如果响应丢失,原样重试保留同一操作编号;服务端返回原收据,不重复扣款。页面不能在缺少报价/明确确认时提交成功核账;展示超过预留金额的风险。
## 执行绑定 `V47`
- 新创建任务冻结 `provider_id_snapshot` 与 `upstream_model_snapshot`;派发和轮询使用快照,不再从改过的模型目录读取另一个渠道/上游模型。当前目录开关仍可停止新任务派发。
- 升级时只对尚未发往上游的 queued 任务冻结可用的当前绑定。已经受理的历史任务不猜测原渠道,缺少原绑定时保留冻结并进入待核账。
- 已有证明的 provider + 原账号指纹 + 上游任务编号有部分唯一索引,阻止同一上游任务关联两笔本地任务。原始密钥不落库。
- 这不是供应商全部配置的不可变快照:provider 的 base URL、协议、别名与凭据池仍可能被管理员修改。生产应避免修改有在途任务的 provider,后续补配置版本引用、执行适配器版本以及更强关联证据。
## Redis 任务租约
独立 `acquire-task-slot.lua` 用 Redis TIME:同一个任务续期不占第二个槽位,满额时另一任务不能进入。返回值区分“新建租约”和“既有租约续期”;数据库回滚不能误删旧租约。既有租约续期后回滚可能保留延长后的 TTL(保守占位),不是承诺 Redis 与数据库跨系统原子提交。
## 上线要求与剩余范围
1. 先停所有旧 worker,备份数据库并检查在途任务,再按顺序迁移 V47/V48、发布新后端和前端;本轮没有执行这些线上步骤。不能混跑按可变目录轮询的旧 worker。
2. 历史任务没有证明的执行绑定会变为待核账,这是安全失败,不是自动补绑或自动退款。安排运营逐笔核实,不批量猜测。
3. 当前是单管理员明确确认模式,未实现双人审批、强制二次验证、证据真实性校验或自动供应商账单同步;不要将它宣传成已完成完整财务审批。
4. 当前人工入口只覆盖“受理/结果未知且原冻结仍在”的 reconciling 任务;不重开已成功/失败任务、不追扣已释放额度、不解决既有 TASK_USAGE_PENDING 的后补消费。
5. 后续继续共享有界 HTTP Transport、媒体下载 SSRF/DNS 重绑定与响应体读取限制、配置版本绑定、真实供应商端到端联调,以及用户会话/角色/管理操作全面安全复核。本阶段不代表整个仓库已安全。
## 验证记录
先前基础改造 74 项回归和核账首批 21 项专项测试已通过。前端 `npm run build`(含 vue-tsc)与 `npm test` 通过,25 项测试零失败。Browser 技能用于隔离 fixture 的真实交互检查:未报价禁提交、金额确认、模拟提交已落地但响应丢失、原编号重放、历史回执、处理后移出待核账列表;两次模拟 HTTP 提交只产生一条收据。未接触真实钱包、会话或供应商。截图保存在被忽略的 `.tools/reconciliation-ui-proof.png`。
最终验证在 2026-10-21 20:06(Asia/Shanghai)完成:Docker / Java 21 / Maven 3.9.9 执行 `mvn -B -o clean verify`,后端 **221 项测试,0 失败、0 错误、0 跳过**,Spring Boot JAR 构建成功。包含 21 项真实 PostgreSQL 核账集成测试、38 项异步任务事务测试和 3 项真实 Redis 租约测试。独立 PostgreSQL 15.18 与 Redis 7 测试容器和 Maven 共享隔离 network namespace,没有映射到业务数据库。
新增关键覆盖:管理员会话和普通用户越权拒绝、自定义头屏障、8 路同操作编号并发一次扣费、不同决定并发一个胜者、幂等编号跨动作/管理员冲突、任务版本过期、冻结不足不补平、原快照报价与 Token 精确结算、缺少用量不释放、审计失败整体回滚、收据禁止改删、同一上游身份不能关联两笔任务、目录修改不改变已冻结执行绑定、旧绑定未知不猜测轮询、Redis 同任务续期及回滚保护。
本地通过不等于生产发布验收、供应商真实账单正确性或完整财务安全审计。测试日志、构建产物和截图均为忽略文件,不进入 Git 提交。