diff --git a/docs/00-ai-start-here.md b/docs/00-ai-start-here.md index 3817c4a..6a8186b 100644 --- a/docs/00-ai-start-here.md +++ b/docs/00-ai-start-here.md @@ -57,8 +57,8 @@ T-205 原子领取/租约状态机、T-206 Android 登录/有限离线、T-207 本地 VLM/候选/ 证据回传、T-211 参考图召回和 SKU 硬匹配、T-212 候选身份映射，以及 T-213 受控 规格组合/价格核验均已完成。T-208 的原始候选观测、模型评估、确定性推荐、逐候选 -结构化人工理由和修订历史也已完成；下一步需先把商品持久身份和 Admin 下单授权落成 -独立任务，不得直接把候选链接当成下单授权。 +结构化人工理由和修订历史也已完成。当前正在实现 T-214 商品持久身份和重新定位 +指纹；之后才能实现 Admin 下单授权，不得直接把候选链接或列表 ordinal 当成授权。 手机从管理后端领取任务并回传结果，VLM、拼多多自动化和人工确认在 App 本地完成。 T-206 增加有限离线执行；T-207 已复用 Roubao 端上 OpenAI 兼容适配器并加密本地 Key。 管理后端不保存/代理 VLM，后台任务不能覆盖手机 provider 配置。 diff --git a/docs/06-tasks.md b/docs/06-tasks.md index 0c417d7..baab2f6 100644 --- a/docs/06-tasks.md +++ b/docs/06-tasks.md @@ -46,6 +46,7 @@ | T-211 | 参考图召回与 SKU 硬匹配 Top 5 | T-207、T-210 | 参考图进入拼多多图片搜索；颜色/尺码均匹配才回传 `0..5` 个候选 | | T-212 | 修复 Top 5 ordinal 与证据映射 | T-211 | 重排、推荐、证据和人工接受引用同一原始候选 | | T-213 | 拼多多候选 SKU 组合与价格核验 | T-212 | 受控选择唯一颜色/尺码并读取组合价；不确认购买，不进入订单或支付 | +| T-214 | 建立候选商品持久身份与重新定位指纹 | T-208、T-213 | candidate key 绑定原 observation、卡片/详情/双证据指纹；不伪造平台链接 | ## Phase 3：端到端验证 diff --git a/docs/current-state.md b/docs/current-state.md index 2f492a4..a5fb0a2 100644 --- a/docs/current-state.md +++ b/docs/current-state.md @@ -5,7 +5,7 @@ ## 当前快照 - 日期：2026-07-28 -- 阶段：T-208 候选决策数据与人工理由闭环已完成 +- 阶段：T-214 候选商品持久身份与重新定位指纹进行中 - Git：当前分支为 `main`；T-001 至 T-004、T-101 至 T-104、T-201 至 T-207、T-209、 T-208、T-210、T-211、T-212、T-213 均已纳入 Git 历史 - 生产代码：`android-buyer/` 已接入 Roubao Android 源码 @@ -118,6 +118,7 @@ | `docs/tasks/T-212.md` | DONE | 修复重排候选、推荐、证据与人工接受的身份映射 | | `docs/tasks/T-213.md` | DONE | 真机选择目标 SKU、读取组合价并安全返回 | | `docs/tasks/T-208.md` | DONE | 归一化候选决策数据并增加结构化人工 review | +| `docs/tasks/T-214.md` | DOING | 建立 execution-scoped candidate key 与设备采集指纹 | | `docs/design/` | 已确认 | T-202 原型索引、4 个管理页和 7 个 Android 页面 | | `deepseek总结.txt` | 已有 | 历史讨论摘要，不是正式需求权威 | | `android-buyer/` | 已有 | Roubao `main` 固定 commit 的 Android 基线 | @@ -129,9 +130,9 @@ ## 任务摘要 - 已完成：T-001 至 T-004、T-101 至 T-104、T-201 至 T-213。 -- 正在进行：无。 -- 下一步：先落独立任务，依次实现商品持久身份、Admin 下单授权、设备命令、 - 订单 dry-run、单次提交对账和付款提醒。 +- 正在进行：T-214 商品持久身份与重新定位指纹。 +- 下一步：依次实现 Admin 下单授权、设备命令、订单 dry-run、单次提交对账和 + 付款提醒。 ## 当前可运行内容 diff --git a/docs/tasks/T-214.md b/docs/tasks/T-214.md new file mode 100644 index 0000000..a5f397c --- /dev/null +++ b/docs/tasks/T-214.md @@ -0,0 +1,93 @@ +--- +id: T-214 +title: 建立候选商品持久身份与重新定位指纹 +phase: 2 +deps: + - T-208 + - T-213 +status: DOING +created: 2026-07-28 +context_ref: e7f4c3e +work_branch: null +write_paths: + - docs/tasks/T-214.md + - docs/00-ai-start-here.md + - docs/04-architecture.md + - docs/06-tasks.md + - docs/api.md + - docs/current-state.md + - backend-api/migrations/** + - backend-api/internal/domain/** + - backend-api/internal/usecase/** + - backend-api/internal/repository/sqlite/** + - backend-api/internal/transport/httpapi/** + - backend-api/internal/transport/webui/** + - android-buyer/app/src/main/java/com/roubao/autopilot/MainActivity.kt + - android-buyer/app/src/main/java/com/roubao/autopilot/pinduoduo/** + - android-buyer/app/src/main/java/com/roubao/autopilot/procurement/** + - android-buyer/app/src/test/java/com/roubao/autopilot/pinduoduo/** + - android-buyer/app/src/test/java/com/roubao/autopilot/procurement/** +--- + +## 问题 / 背景 + +T-208 已能保存原始候选 observation 和人工结论，但 Admin 与后续设备命令仍只能用 +`execution_id + ordinal` 描述候选。拼多多结果排序会变化，ordinal 不能作为商品身份； +当前 8.17.0 无障碍树也不提供可验证的商品 URL 或平台 goods ID，不能伪造链接。 + +本任务为每个 observation 建立后台持久 `candidate_key`，并保存手机当时采集的卡片、 +详情和证据指纹。后续设备重新以图搜图时，必须用任务参考图、指纹、已确认 SKU 和 +价格重新核验，不能按旧 ordinal 盲点。真实平台 URL/图片 URL 仍允许作为可选观测值， +但不是授权或主证据。 + +## 关联需求与交互 + +- 功能：F-008；为后续订单提交审批建立候选引用。 +- 用户故事：US-008，以及后续“人工授权后下单”故事。 +- 交互：IX-009；本任务只增强 Admin 候选详情可识别性，不新增下单按钮。 +- 架构/API：候选决策数据集、`POST /api/v1/tasks/{id}/candidates`。 + +## 冻结合约 + +1. App 为每个原始候选回传： + - `card_signature`：结果卡片可见语义的 SHA-256； + - `detail_signature`：详情页可见语义的 SHA-256； + - `detail_evidence_sha256` 与 `specification_evidence_sha256`； + - 可可靠提取时回传 `observed_title`，否则保留明确的候选占位标题； + - `product_url`、`image_url` 只有设备确实取得并通过 URL 校验时才允许非空。 +2. 后端验证四个指纹均为小写 SHA-256，并核对两个 evidence 哈希属于该 + execution/observation 已上传的受控证据。不得信任客户端提交的任意哈希。 +3. 后端用版本化输入生成 64 位小写 `candidate_key`： + `execution_id + original ordinal + detail signature + specification evidence hash`。 + 相同候选请求幂等重放必须得到相同 key；key 只表示本次 execution 的持久 + observation，不宣称是拼多多全局商品 ID。 +4. 新表 `candidate_observation_identities` 与 + `candidate_observations(execution_id, ordinal)` 一对一，旧 v6 历史允许没有 + identity；v7 以后新候选批次必须同事务生成 identity。 +5. Admin API/Web 在每个 observation 区块显示 candidate key、原 ordinal、规格、 + 价格、卡片/详情签名和受控截图引用。外链只作为不可执行审计文本，不由后端请求。 +6. 后续 Admin 选品和设备命令只能引用 `candidate_key`，并同时绑定 task、 + execution、task content hash 和 review version，不能只传 ordinal 或 URL。 + +## 验收要点 + +- [ ] v7 migration `up/down/up` 可重复；有 identity 数据时破坏性 down 失败。 +- [ ] App 回传全部 observation 的卡片/详情/双证据 SHA-256，不因模型拒绝而缺失。 +- [ ] 后端拒绝格式错误、跨 execution、与 evidence 实际哈希不一致的指纹。 +- [ ] 同一请求重放 candidate key 稳定，不同 observation key 不同。 +- [ ] Admin API/Web 可按 candidate key 查看 observation、模型判断、人工结论和截图。 +- [ ] 后端不会请求候选 URL；没有真实 URL 时保持空值而不是生成伪链接。 +- [ ] Android/Go 测试、race、migration、Debug/Release 和根验证通过。 + +## 边界 + +- 不实现 Admin 选品按钮和下单授权；属于 T-215。 +- 不实现设备命令、重新搜索或 SKU/数量操作；属于 T-216/T-217。 +- 不通过分享面板、剪贴板、root 或 dumpsys 抓取商品链接。 +- 不把截图 SHA-256 当作跨时间相同商品的唯一证明；重新定位仍需多信号复核。 + +## 执行记录 + +- 2026-07-28：T-208 实现提交 `e7f4c3e` 后领取。确认当前 observation 已有可选 + product/image URL 和受控 evidence，但 App 实际无法从拼多多无障碍树取得可信 URL， + 因此冻结 execution-scoped candidate key 与多指纹方案。