cmroubao

Table of Contents

需求 / 背景
修订契约

三阶段搜索
增量回传
外部动作节奏

方案
验收要点
边界
执行记录

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

同步来源：docs/tasks/T-248.md · commit afc651f75a3a

id: T-248 title: 增量回传准确候选并增加第三轮保底搜索 phase: 2 deps:

T-247 status: DONE created: 2026-07-30 context_ref: bef6408 work_branch: null write_paths:
docs/tasks/T-248.md
docs/current-state.md
docs/api.md
backend-api/migrations/**
backend-api/internal/**
android-buyer/app/src/main/**
android-buyer/app/src/test/**

需求 / 背景

T-247 将自动图片搜索限制为两轮，并要求同一轮凑齐两个 SKU 硬匹配候选后才回传。真实拼多多结果中，准确候选可能分布在不同轮次；只在整批完成后回传会丢失已经确认的商品，也让 Admin 无法观察当前进度。

目标流程调整为：

Roubao 始终使用任务参考图进行拼多多图片搜索。
前两轮使用解析后的款式/颜色、尺码和价格信息检查商品；每得到一个完整准确候选就立即回传 Admin，并在后续轮次继续累计。
两轮结束仍不足 2 个准确候选时，执行第三轮图片搜索，采集拼多多默认结果前两个不重复商品作为保底候选。
Admin 必须能区分准确候选和未通过 SKU 硬匹配的保底候选。
Roubao 操作拼多多的外部 UI 动作之间增加 1 至 3 秒随机停顿。

修订契约

三阶段搜索

execution 持久化阶段为 EXACT_ROUND_1、EXACT_ROUND_2、 FALLBACK_ROUND_3 和 COMPLETE，进程重启后不得从第一轮重新开始。
前两轮累计准确候选，按规范 goods_id 去重；同一商品不得重复回传或占用多个名额。
累计准确候选达到 2 个时跳过剩余轮次并完成采集。
两轮结束不足 2 个时必须执行第三轮图片搜索。第三轮按结果排序采集前两个不重复且身份、链接和证据完整的商品，不要求 SKU 硬匹配；最多有 1 个准确候选加 2 个保底候选。
三轮均有界；第三轮完成或稳定失败后停止外部操作，不进入下单、订单确认或支付。

增量回传

App 每发现一个准确候选，立即将当前累计候选快照加入加密 outbox；网络不可用时本地保留并按原幂等机制重传。
候选提交增加 collection_complete 和 search_round。后台只在 collection_complete=true 时将任务从 RUNNING 改为 WAITING_CONFIRMATION。
同一 execution 的后续快照只能追加或保持已有 goods_id，不能删除、替换或降级已有准确候选；完成后的快照不可再修改。
候选增加 match_type、search_round 和 result_rank： EXACT_MATCH 表示颜色/款式和尺码硬约束均复读匹配，FALLBACK 表示仅来自第三轮默认排序。保底候选不能生成自动推荐。
Admin 在搜索未完成时显示候选和当前轮次，但保持选择/推送禁用；完成后准确候选优先，保底候选显示明确警告。

外部动作节奏

打开拼多多、打开图片搜索、选择图片、打开/返回商品、滑动结果、打开/关闭规格、选择规格和分享复制链接等外部 UI 动作之间，使用可取消的 1 至 3 秒随机停顿。
页面识别、OCR、截图哈希、SQLite/SharedPreferences 和 HTTP/outbox 操作不增加随机停顿；页面跳转继续以状态检测和有界 timeout 为准，随机停顿不能替代就绪检查。
停顿使用协程 delay，不得阻塞 Android 主线程；测试可注入确定性延迟。

方案

将两次 attempt gate 升级为持久化三阶段 gate，记录当前轮次、已完成和最后失败。
候选自动化增加准确/保底采集模式、跨轮已见商品集合及采集事件；准确模式保留严格 SKU 选择，保底模式读取规格和身份但不强制选择目标 SKU。
MainActivity 按 execution 累计候选；准确候选新增时立即排队提交累计快照，第三轮完成后提交最终快照。
扩展候选 API 和 SQLite batch 表，允许同一 execution 在 RUNNING 状态幂等更新未完成快照；只允许候选单调追加，并在完成快照事务中保存决策数据集、产生 CANDIDATES_READY 事件和切换任务状态。
Admin 候选数据沿用现有详情接口与鉴权证据路由，补充采集阶段、匹配类型和完成状态。
提供统一 PinduoduoActionPacer，由各 Android driver 在成功发出外部动作后调用，默认随机 1000 至 3000 毫秒，单测使用零延迟 fake。

验收要点

第一、第二轮准确候选跨轮累计，按 goods_id 去重。
每新增一个准确候选就产生可幂等重试的未完成累计快照，后台任务保持 RUNNING。
累计两个准确候选后发送完成快照并进入 WAITING_CONFIRMATION，不执行第三轮。
两轮不足两个时执行第三轮，回传默认排序前两个不重复 FALLBACK 候选。
Admin 数据明确展示 EXACT_MATCH/FALLBACK、轮次、排序和采集是否完成。
完成快照不能被旧快照或重试覆盖，已有准确候选不能删除或降级。
拼多多外部动作之间默认随机停顿 1 至 3 秒，等待可取消且不阻塞主线程。
Android/Go 单测、race、vet、Debug/Release 构建通过。
真机 smoke 不进入下单、订单确认或支付，结束后按用户要求保持 Roubao 停止。

边界

保底候选只是图片搜索默认排序结果，不宣称 SKU 匹配成功。
本任务最多保存 2 个准确候选和 2 个保底候选，总候选数不超过 3。
不绕过拼多多登录、验证码、风险控制或支付边界。
不记录拼多多 Cookie、Token、原始分享短链或参考图内容日志。

执行记录

2026-07-30：新增 v19 迁移和累计候选 API。未完成快照只更新 Admin 执行审计并保持 RUNNING；最终快照才生成候选决策数据集、CANDIDATES_READY 事件并切换 WAITING_CONFIRMATION。后端事务拒绝候选删除、替换、轮次回退和完成后的旧快照。
2026-07-30：Android attempt gate 从两轮升级为三阶段；候选证据、来源类型、轮次和排名按 execution 持久化。前两轮严格选择并复读 SKU，第三轮不选择目标 SKU，只收集默认结果中两个身份完整且未重复的保底商品。
2026-07-30：每个新增候选立即把累计快照加入既有加密 outbox；最终最多为两个准确候选，或一个准确候选加两个保底候选。Admin 显示匹配类型、轮次、结果排名和采集状态。
2026-07-30：新增统一拼多多动作 pacer；打开、点击、滑动、返回、规格选择和分享复制成功后随机等待 1000 至 3000 ms，页面识别、OCR、截图和网络回传不增加随机延迟。
2026-07-30：go test ./...、go test -race ./...、go vet ./... 和三个 Go 入口构建通过；Android 单测及 Debug/Release 构建通过。Debug APK 1.4.16 (21) 已覆盖安装到 PKG110，随后 force-stop 并确认进程不存在。
2026-07-30：按用户要求未启动真实采购，因此真实拼多多三轮搜索和 Admin 最终候选展示仍需使用新任务完成 smoke；本次没有触发下单、订单确认或支付。