cmroubao/docs/tasks/T-207.md

id, title, phase, deps, status, created, context_ref, work_branch, write_paths

id	title	phase	deps	status	created	context_ref	work_branch	write_paths
T-207	接入后端 VLM、候选、事件和结果回传	2	T-206	TODO	2026-07-27	45d4d11	null	README.md android-buyer/** backend-api/** docs/00-ai-start-here.md docs/02-requirements.md docs/04-architecture.md docs/05-coding-rules.md docs/07-user-stories.md docs/08-interaction-checklist.md docs/api.md docs/current-state.md docs/routes.md docs/tasks/T-207.md progress.md

问题 / 背景

T-206 跑通任务领取和执行生命周期后，App 仍不能安全使用真实 VLM，也不能把候选、 步骤、截图、失败和人工结论保存到后端。Roubao 原有端上 provider 设置会把供应商 选择和密钥交给采购手机，难以统一审计、限流、切换模型和积累可比较数据。

第一版需要支持管理员配置一个 OpenAI 兼容 VLM 服务商，由后端代理所有模型调用； App 只传任务/execution 标识和受控候选证据。候选优化用的完整结构化人工标签仍由 T-208 后置，不能阻塞本任务的端到端闭环。

关联需求与交互

• 功能：F-002、F-004、F-005、F-006、F-007、F-009。
• 用户故事：US-002、US-004、US-005、US-006、US-009。
• 交互：IX-003、IX-006、IX-007、IX-008、IX-010。
• 架构/API：后端托管 VLM、OpenAI 兼容 adapter、AI 合约、执行事件/资产、 complete/fail 和管理 Web VLM 设置。

已定合约

1. 生产数据流固定为 Android App -> 肉包后端 -> VLM Provider。BUYER 不能读取、 选择或覆盖 provider、Base URL、model、prompt version、timeout、retry 或 API Key。
2. 第一版 provider 协议只支持 OpenAI 兼容 /v1/chat/completions 多模态请求； /v1/responses 和供应商私有协议后置。管理员配置名称、HTTPS Base URL、模型、 超时、重试上限、启用状态和默认版本。
3. MVP 同时只有一个默认 provider 版本供新 execution 使用。配置修改创建新版本； execution 在首次 AI 调用时绑定不可变的 provider/model/config version 和 prompt version，后续调用不得漂移。
4. API Key 是 write-only secret。后端使用环境变量提供的 256 bit master key，以 AEAD 和随机 nonce 加密后落库；AAD 绑定 provider/version。GET、HTML、日志、 错误、审计事件和备份说明均不回显明文。缺少 master key 时禁止保存含 Key 的配置 和真实调用，但仍可启动管理/任务功能。
5. 远程端点只允许 HTTPS，禁止 userinfo、query、fragment 和重定向；解析/连接阶段 阻断 loopback、私网、链路本地、组播和云 metadata 地址，避免 SSRF/DNS rebinding。 无 Key 的 loopback HTTP 仅允许显式 Debug 测试配置，不能从生产管理页面创建。
6. 管理员可用内置脱敏文本和测试图片检查连接，不发送订单、店铺、SKU 或任务图片。 测试失败只显示稳定分类和 request ID，不显示供应商响应正文或密钥。
7. 后端从原任务读取需求图片/文字；App 不能替换 SKU、数量、预算或参考图。候选评估 只接受当前 execution 已上传、已鉴权和解码的截图资产。
8. 每个 execution 最多一次需求提取、最多 5 次按 ordinal 串行候选评估。默认不重试； 配置最多允许 1 次仅限确定未收到响应的临时网络失败，schema/4xx/安全错误不重试。
9. provider 响应经过严格 schema、大小、置信度和确定性硬约束校验。模型不能产生 点击动作、候选授权、人工结论或订单授权，MVP 始终 order_submitted=false。
10. App 用本地持久 outbox 幂等回传步骤事件、受控截图、候选摘要、complete/fail； 上传失败可以补报，但不得恢复已经安全停止的自动化。
11. T-207 保存第一版候选和模型理由及必填 operator_reason，足以审计完整流程； 逐候选结构化 reason code、改选修订和训练/离线评估数据合约属于 T-208。

方案

1. 新增版本化 provider 配置、加密 secret、execution provenance、候选、执行事件、 outcome/error 和 evidence 资产 migration；原始任务事实与模型派生值分表保存。
2. 后端实现 provider 管理 usecase、SSR 设置页和 CSRF 保护的写入动作。配置更新只 追加版本，停用只影响新 execution，审计记录 actor、时间和非秘密字段。
3. 实现安全 HTTP transport、OpenAI Chat Completions adapter、严格请求映射/响应 schema、调用预算、取消、超时、重试和错误分类；普通测试只连接本机 mock。
4. 实现 extract-requirements、evaluate-candidate、event、asset、complete 和 fail API；全部验证 BUYER/device/claim/execution/version/租约和幂等键。
5. Android 用后端 AI client 替换生产工作流的端上 provider client，上传受控截图， 按最多 5 个候选执行并在硬停止点要求人工填写简短理由。
6. 管理任务详情展示原始需求、provider provenance、候选评估、人员结论、事件和鉴权 证据；模型理由、确定性推荐和人员理由视觉及数据上保持分离。
7. 清除采购模式遗留的端上 provider secret，并用测试证明 Release 不再读取或发出 直连 provider 请求。Debug 探针继续使用独立、被忽略的本机配置。

验收要点

• ADMIN 能新增/更新/启用一个 OpenAI 兼容 provider 版本并执行脱敏连接测试； 非 ADMIN/BUYER 不能访问，API Key 永不回显。
• 数据库只含带随机 nonce 的密文；错误 master key、篡改密文和缺少 master key 均安全失败，日志/HTML/JSON/事件不包含 Key 或供应商正文。
• 私网、loopback、metadata、重定向、DNS rebinding 和非法 URL 被拒绝；生产只 连接受控 HTTPS 目标。
• 真机领取后台任务后，需求提取和最多 5 个候选评估均经肉包后端完成，抓包/测试 证明 App 不直连 VLM，不携带 provider Key。
• SKU、数量、预算和参考图只能来自原任务；低置信度、无效 schema、超预算、 证据不完整和模型越权输出均转人工或拒绝。
• 事件、截图、候选、complete/fail 在断网重试后不重复，管理详情可以还原执行 过程；人工接受/拒绝/无匹配/转人工均要求 operator_reason。
• 任一路径不提交订单，终态明确保存 order_submitted=false；取消和安全错误不 自动重试或继续点击。
• migration up/down/up、Go unit/integration/race/vet、Android unit/instrumented、 Playwright 三视口、根 init.ps1 和 OnePlus PKG110 真机 smoke 通过。

边界

• 不支持 /v1/responses、供应商私有协议、多 provider 按任务选择、采购员切换模型、 自动模型路由、实时价格或成本报表。
• 不实现 T-208 的逐候选结构化人工标签、修订历史、离线评估或训练管线。
• 不下载客户端提交的任意商品/图片 URL，不自动提交订单、支付或绕过平台风险控制。
• 不把真实 provider Key、订单、截图、模型正文或解密 master key 纳入 Git。

执行记录

• 尚未开始。