# 人工任务核账与执行绑定 日期: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 提交。