Files
cmroubao/docs/current-state.md
T

272 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
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.
# 当前实现状态
> 可覆盖的项目级快照。任务执行日志写入对应任务文件。
## 当前快照
- 日期:2026-07-28
- 阶段:T-220 至 T-224 ERP 货运接入闭环已完成
- Git:当前分支为 `main`;T-001 至 T-004、T-101 至 T-104、T-201 至 T-219
均按文档提交、实现提交的顺序纳入历史
- 生产代码:`android-buyer/` 已接入 Roubao Android 源码
- Android:固定 `main@c8a6d7f03422eb01744b01f3ee77bf7757741f7e`;MIT 许可证已保留
- 后端:Go 1.23.0 + Gin 1.11.0 + SQLite + Goose 3.26.0;已实现图片/任务业务、
SSR 管理 Web、ADMIN/BUYER 联合认证、设备 readiness、原子 claim、租约状态机、
task-scoped 参考图和 `authctl`
- ERP 货运:Go 后端通过仅限 loopback、服务密钥鉴权的 Python Connector 异步按
完整单号同步;v12 保存同步记录、货运头和全部明细,canonical hash 控制 revision,
Admin 已有 `/freight`、`/freight/import`、`/freight/{id}` 与对应 JSON API。
- ERP 增量同步:v14 支持 Asia/Shanghai 创建日期闭区间和“同步至现在”,Connector
单窗最多 7 天,后端对较长水位范围切窗并从成功水位前 10 分钟所在自然日回看。
货运落库、同步成功和水位推进同事务完成;失败与较旧范围成功不推进水位。Admin
可查看查询范围、计数、稳定错误码和最近成功水位。
- 采购需求:v13 按货运商品 revision 保存可复核快照;ADMIN 显式确认采购、上传参考
图后生成不可变 PENDING 任务。来源变化不会改写任务,Roubao 可沿用现有 claim 流程。
- 本机 Android 工具:JDK 17.0.13、Command-line Tools 22.0、SDK 34、
Build Tools 34.0.0、Platform Tools/ADB 37.0.0;用户级 SDK 环境变量已设置
- Android Studio:未安装;`winget` 静默安装卡住后已终止,不阻塞命令行构建
- 测试:T-219 Android Debug/Release 单元测试与构建和根 `init.ps1` 通过;
Debug APK `1.4.16 (21)` 已覆盖安装到 PKG110
- 后端测试:T-224 运行 `go test ./...`、`go test -race ./...`、`go vet ./...`;
覆盖 v14 上下迁移、7 天切窗、水位重叠、中途失败、空窗口、重复页、来源 revision、
水位事务/不回退、Admin API/SSR 和 Connector 严格响应窗口;Python 22 项伪响应
测试通过,未访问真实 ERP
- 原型:4 个管理 Web 页面和 7 个 Android 页面均可离线独立打开;Playwright
以 1440×900、390×844、360×800 验证 36 个页面/视口组合,无页面横向溢出、
脚本错误或外部请求,Android 可见交互控件均不小于 44px
- 管理 Web:真实 Gin/SQLite 流程已完成图片上传、任务创建、列表、详情参考图和
非终态取消;执行中只显示“请求安全停止”,ADMIN 登录/退出和安全返回路径已接入,
货运列表/导入/详情在 1440×900、390×844、360×800 无横向溢出或页头重叠
- 鉴权:bcrypt 密码、8 小时管理 session、1 小时 App access token 和设备 secret
均不明文落库;设备首次绑定原子化,禁用/过期/撤销每次请求重新检查;管理/App
登录各自按来源地址执行内存有界限流,账号和设备支持 `authctl` 启停
- 生命周期:设备 heartbeat 记录三个版本、两个就绪位和服务端活跃任务;claim 使用
client-generated 256 bit token + 独立幂等 key、SQLite immediate transaction、
10 分钟 CLAIMED/默认 30 分钟运行授权和 2 分钟 readiness TTL。start/heartbeat/release/
cancel-ack、过期回收、跨连接并发唯一领取、管理安全停止与 task-scoped 参考图均
已实现;运行授权允许配置 5-120 分钟并显式返回截止时间,过期状态同步不延长旧
授权;原 claim token/hash 不进入响应或日志
- Android 后台采购:新增独立“任务”入口、BUYER/设备登录、Keystore-backed 加密
状态、严格 HTTPS/Debug loopback 地址策略、`HttpTaskSource`、参考图校验、手动领取、
预览/start 二次确认、release、30 秒前台 heartbeat、有限离线、`SAFE_STOPPED`、
取消确认和进程恢复;后台任务不读取或覆盖本地 VLM provider
- 登录重试:采购登录失败、本地校验失败或网络失败时保留当前页面输入,只有成功才清理
Compose 内存中的密码和设备密钥;敏感值不新增持久化或日志路径
- T-207 结果闭环:`execution_events`、受控截图、候选批次、模型出处、人工结论与
失败记录均按 execution 存储;Android 使用加密 outbox 按事件、截图、候选和终态
顺序回传,授权到期补报单独审计,所有终态固定 `order_submitted=false`。管理任务
详情展示模型/候选/人工理由/事件/证据摘要,不保存 VLM Key、完整 endpoint 或原始响应。
- T-208 决策数据:候选批次同事务规范化为 search run、原始 observation、逐项
model evaluation 和确定性 recommendation;模型拒绝项不再被过滤或重排。App 在
COMPLETE 前提交幂等 HUMAN_REVIEW,接受项和其余拒绝项均有结构化理由;修订按
supersedes/version 追加。Admin/API 分区显示 observation、prediction、
recommendation 和完整人工 review 历史。
- T-211 图片检索:后台任务固定使用经 SHA-256 校验的参考 JPEG,经一次性 MediaStore
图片进入拼多多拍照搜索;App 本地从 SKU 唯一提取颜色和尺码,schema v3 逐项返回
`MATCH/MISMATCH/UNKNOWN`。实际曝光的 `0..5` 项全部按原 ordinal 回传;只有两项
均匹配且分数/置信度不低于 `0.75` 的候选能成为确定性 recommendation。
- T-213 规格核验:`DISCOVERY_INSPECT` 可从唯一“免拼购买”进入规格弹层,按任务
SKU 唯一选择颜色/尺码并复核 selected/已选摘要,最多滚动 2 次;严格保存单一
人民币组合价和详情/规格双证据,并允许明确的“首件¥金额”当前单件价。区间、
券后、对照促销、冲突或缺失价格降级 `UNKNOWN`,直达订单确认页只系统返回。候选
探查不能加入购物车、提交订单或触发支付。
- T-214 候选身份:App 回传卡片/详情语义签名和详情/规格双证据 hash;后端逐一核对
已上传 asset 后,在 v7 表中生成 execution-scoped `candidate_key`。Admin API/Web
展示 key、指纹、原始 observation、模型/人工结论和截图;缺少真实平台 URL 时保持
空值,后端不请求第三方 URL。
- T-215 下单授权:非空候选回传原子进入 `WAITING_CONFIRMATION`;Admin 按
candidate key 选择并为全部候选填写结构化理由,服务端在同一事务追加人工 review、
不可变授权快照、事件和幂等记录。领取前可按版本改选,已投递后禁改;页面明确仅
授权创建设备端待付款订单,不授权付款。
- T-216 设备命令:App 在 heartbeat 后主动拉取同一条不可变授权,严格校验跨端
canonical hash、任务内容和候选四组指纹,先写 Keystore-backed 状态再幂等 ACK。
网络响应丢失和进程重启复用同一 ACK key;后台候选不再允许手机本地选择或重复
采集。本任务只同步授权,未打开拼多多或执行下单。
- T-217 订单 dry-run:App 自动用参考图重新搜索并以旧 card/detail 指纹、标题、
唯一颜色/尺码、数量和预算重新核验 Admin 选择;确认页 WebView 折叠时使用端上
中文 OCR 做只读 fail-closed 证据提取。后端保存 v10 READY、截图、SKU、数量、
单价/总额和事件;无障碍动作集中不含订单提交或支付。
- T-218 单次提交:后端先创建唯一 submission fence,App 点击前持久化
`CLICK_ASSUMED`,最多点击一次精确“提交订单”;进程/网络不确定和租约到期后只
回读待付款订单或转人工,绝不重复提交或点击支付。v11 保存围栏、幂等操作、订单号/
时间、证据和审计事件,唯一对账后才写 `order_submitted=true`。
- T-219 待付款提醒:Admin API/SSR 按任务鉴权读取 submission,区分围栏中、人工
对账和唯一对账成功;成功态展示完整订单号、平台时间、授权 SKU/数量/金额及受控
证据,只提醒采购员打开拼多多人工核对付款。Roubao 显示相同终态;Web/App 均没有
付款、重复提交或自动支付动作。隔离数据库真实 SSR 已通过三个响应式视口验收。
- T-220/T-221 ERP 来源:字段契约已固定 stock/detail/item 外部身份、PII 最小化和
缺图边界;Python Connector 只监听 loopback,服务密钥鉴权,受控验证码登录后按
完整单号读取全部商品并输出 allowlist schema。16 项伪响应测试和真实 HTTP 健康
smoke 通过,未访问线上 ERP。
- Workflow:纯 Kotlin runner 已支持步骤 timeout、最多 3 次 retry、安全阻塞、
用户停止和单 runner 并发拒绝;T-102 已接入搜索加有界候选采集五步
- TaskSource:严格 CLI 已生成并验证真实私有 ProbeTask;默认 APK 不含私有 fixture
- VLM:需求提取与候选评估均使用严格 schema、0.75 阈值、受控证据源、安全端点和
单次调用边界;候选最多 5 个并按 ordinal 串行评估,本地产生建议并停在人工确认,
SKU/数量由本地原值回填,颜色/尺码硬约束由本地生成,预算保持空,订单提交状态固定
为 false
- VLM 部署决策:手机本地调用已配置的 OpenAI 兼容 provider;管理后端只负责身份、
任务控制和结果审计,不保存/代理模型。T-207 保留 Roubao 独立模式并把端上 Key
迁移到 Keystore-backed 加密存储
- 离线执行:默认 30 分钟有限授权和 30 秒 best-effort heartbeat 已实现;PKG110
真机断开临时后端 95 秒后保持同一 execution,重连后滑动续期;到期持久安全停止,
RUNNING 不自动重新分配
- 测试设备:OnePlus PKG110,Android 16/API 36;已安装肉包 `1.4.16 (21)`;拼多多
`8.17.0 (81700)`
- 设备就绪:拼多多首页、文字/图片搜索、双列候选卡、详情截图和返回均已通过 8.17.0
真机验证;ColorOS 本次覆盖安装后移除了肉包采购无障碍,重新启用后服务已连接,
因此每次覆盖安装后都必须复核该系统授权
- 拼多多 8.17 兼容:结果页可识别新版显示查询词的文本搜索栏和“推荐、手机、女装”等
分类栏,也保留旧版“综合、销量、价格、筛选”识别;长任务搜索词的拼多多省略显示须
至少两个按序片段对应原词才通过。每次候选探针会重写本次搜索词,不复用已有结果页。
PKG110 真机已验证确认结果页完成、5 份候选证据采集、详情截图及返回结果页;未进入
下单或支付页面。
- 版本控制内测试数据:仅有脱敏、运行时生成的单元测试 fixture;没有真实订单内容
- 本地私有样本:仓库根目录存在一组未跟踪、已本地排除的同名蝦皮文本/JPEG;
已用 CLI 真实导入并逐字段/图片哈希验证,生成物位于被忽略的 `.local/`
- 标准启动路径:`$env:RUN_START_COMMAND="1"; .\init.ps1`
- 标准验证路径:`.\init.ps1`
- 当前 blocker:当前真机确认页缺少已配置收货地址且显示
“立即支付/先用后付”,T-218 已按合约证明不创建围栏、不点击。不能为测试自动添加
地址或跨过付款边界。真实 VLM 服务地址、模型、
设备级测试凭证、成本上限和数据留存尚未确认;当前只支持单 SKU/JPEG;候选探针
截图要求 Android 11/API 30+
## 当前目录
| 路径 | 状态 | 说明 |
| --- | --- | --- |
| `AGENTS.md` | 已有 | agent 权威入口 |
| `docs/` | 已有 | Harness Coding 文档 |
| `docs/tasks/T-001.md` | DONE | Android 可构建、可安装、可启动基线 |
| `docs/tasks/T-002.md` | DONE | 设备版本、无障碍、前台和登录阻塞就绪检查 |
| `docs/tasks/T-003.md` | DONE | 可注入 Fake automation 的受限 workflow runner |
| `docs/tasks/T-004.md` | DONE | 私有蝦皮文本/JPEG 严格导入和 Debug TaskSource |
| `docs/tasks/T-101.md` | DONE | 固定脱敏词拼多多搜索和结果页真机验证 |
| `docs/tasks/T-102.md` | DONE | 最多 5 个候选详情截图、证据 manifest 和结果页返回 |
| `docs/tasks/T-103.md` | DONE | 私有任务需求 schema、硬约束、隐私边界和 VLM 适配器 |
| `docs/tasks/T-104.md` | DONE | 动态搜索、候选严格评估、本地建议和人工确认点 |
| `docs/tasks/T-201.md` | DONE | Go-Gin、SQLite、Goose migration 和健康检查骨架 |
| `docs/tasks/T-202.md` | DONE | 生成并确认 P0 Web/App 低保真原型 |
| `docs/tasks/T-203.md` | DONE | 图片/任务 API、SQLite 业务层和 SSR 管理 Web |
| `docs/tasks/T-204.md` | DONE | 用户、管理会话和预授权设备联合身份 |
| `docs/tasks/T-205.md` | DONE | 原子 claim、租约、execution 和取消安全确认 |
| `docs/tasks/T-206.md` | DONE | App 领取、默认 30 分钟有限离线执行、恢复和安全停止 |
| `docs/tasks/T-207.md` | DONE | App 本地 VLM、Key 加密、候选、事件、截图和结果回传 |
| `docs/tasks/T-209.md` | DONE | 登录失败保留采购员和设备输入以便直接重试 |
| `docs/tasks/T-210.md` | DONE | 兼容拼多多 8.17 搜索结果页与长词省略显示 |
| `docs/tasks/T-211.md` | DONE | 参考图召回、SKU 颜色尺码硬匹配与 0..5 候选回传 |
| `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` | DONE | 建立 execution-scoped candidate key 与设备采集指纹 |
| `docs/tasks/T-215.md` | DONE | Admin 按 candidate key 选择并创建不可变待投递授权 |
| `docs/tasks/T-216.md` | DONE | App 主动拉取并先加密落盘再确认同一条下单命令 |
| `docs/tasks/T-217.md` | DONE | 重新核对已授权商品并选择 SKU/数量,停在最终提交前 |
| `docs/tasks/T-218.md` | DONE | 单次提交围栏、最多一次提交动作和待付款订单唯一对账 |
| `docs/tasks/T-219.md` | DONE | Admin 待付款提醒、Roubao 终态和跨端闭环验收 |
| `docs/tasks/T-220.md` | DONE | 顺运宝 ERP 字段契约与凭证安全基线 |
| `docs/tasks/T-221.md` | DONE | 顺运宝精确单号 Connector |
| `docs/tasks/T-222.md` | DONE | 货运信息存储、API 与 Admin 页面 |
| `docs/tasks/T-223.md` | DONE | 待采购需求提取与任务生成 |
| `docs/tasks/T-224.md` | DONE | ERP 日期增量同步 |
| `docs/design/` | 已确认 | T-202 原型索引、4 个管理页和 7 个 Android 页面 |
| `deepseek总结.txt` | 已有 | 历史讨论摘要,不是正式需求权威 |
| `android-buyer/` | 已有 | Roubao `main` 固定 commit 的 Android 基线 |
| `android-buyer/task-contract/` | 已有 | Android/CLI 共享 ProbeTask 与 TaskSource |
| `android-buyer/tools/shopee-importer/` | 已有 | 开发机私有 fixture 导入 CLI |
| `backend-api/` | 已有 | Go-Gin 任务 API、SQLite、图片存储、管理 Web 和 migration |
| `erp-connector/` | 已有 | 顺运宝 loopback Python Connector 与无网络伪响应测试 |
| `init.ps1` / `init.sh` | 已验证/待跨平台 | Windows 同时验证 Android/Go;Unix 入口待 Linux/WSL 复核 |
## 任务摘要
- 已完成:T-001 至 T-004、T-101 至 T-104、T-201 至 T-219。
- 已完成:另含 T-220 至 T-224 ERP 契约、Connector、货运存储、采购需求生成和
日期增量同步。
- 进行中:无。
- 下一步:进入 T-301 P0 UI 完整交互验收;真实 ERP 上线前仍需确认开放 API、
数据使用权限并由人员完成验证码登录。
## 当前可运行内容
```powershell
.\init.ps1
$env:RUN_START_COMMAND = "1"
.\init.ps1
Set-Location backend-api
$env:GOTOOLCHAIN = "local"
go run ./cmd/migrate up
$env:CMROUBAO_AUTH_PASSWORD = "至少 6 个 UTF-8 字节"
go run ./cmd/authctl create-user ADMIN admin
Remove-Item Env:CMROUBAO_AUTH_PASSWORD
go run ./cmd/api
```
2026-07-25 已在 PKG110、Android 16/API 36、拼多多 8.17.0 上完成 Debug APK
固定词搜索和 5 个候选采集。默认首屏为候选探针,用户点击后五步全部完成,5 张
匿名 PNG 与 manifest 哈希一致并返回结果页;logcat 无崩溃或 ANR。
同日用显式私有 fixture 和一次性本机 OpenAI 兼容 mock 完成 T-103 Android smoke:
只发出 1 次 POST 和 1 张 JPEG data URL,请求不含订单/店铺字段或数量键;严格响应
进入 READY,UI 保留原 SKU/数量、空预算和警告。恢复无密钥 provider 后失败状态会
清空旧结果;设备原 API provider 设置已恢复。该 smoke 只证明集成与隐私边界,不
代表真实 VLM 提取质量;真实凭证调用未执行。
同日完成 T-104 真机 smoke:结构化需求搜索词驱动拼多多搜索并采集 5 份候选证据,
本机 mock 精确收到 5 次按 ordinal 排序的单图 POST;请求未包含订单、店铺、本机
路径或数量字段。严格评估进入“等待人工确认”,人员可标记建议候选可用或拒绝,
`order_submitted` 始终为 false;日志敏感词、Base64、原始响应和 schema/prompt
命中均为 0。该结果不代表真实模型的商品匹配质量。
2026-07-27 完成 T-211 真机 smoke:PKG110 上从后台任务下载并校验参考 JPEG,写入
一次性匿名 MediaStore 图片后进入拼多多拍照搜索并选择该图。App 完成 4 个有界候选
详情和证据采集并以 `PDD_IMAGE_SEARCH` 回传后台;不足 5 个未凑数,临时图库图片在
流程结束后删除。验证期间修复相机自动结果页竞态和 MediaStore volume URI 差异;
测试任务随后取消,全程未进入购物车、订单或支付。真实 VLM provider 尚未参与本次
smoke,当前结论只覆盖图片召回、严格契约和回传链路。
同日完成 T-201 后端 smoke:本机迁移执行 `status -> up -> up -> down -> up`,
第二次 `up` 应用数为 0;API 真实进程的 `GET /healthz` 返回 `200` 和稳定 JSON,
未知路由返回 `404`,错误方法返回 `405`,无默认 CORS,stdout/stderr 均为空。
`http.Server.Shutdown` 由集成测试验证在 1 秒预算内结束。当前 Windows 没有可用 WSL
发行版,因此 `init.sh` 未实际运行;Windows 标准入口已验证。
2026-07-26 完成 T-203:新增两条业务 migration、图片规范化存储、任务领域/用例/
SQLite 仓储、管理 API 和 SSR Web。创建/上传幂等,列表稳定分页,详情可读取同源
规范化参考图,只有 `PENDING` 可取消。T-204 前业务路由仅限 loopback,Web 写操作
使用双提交 CSRF;这不是正式鉴权。真实 HTTP/Playwright 和 migration CLI smoke、
99 个 Go 测试、全包 race/vet、Windows 构建与根 `init.ps1` 全部通过。
2026-07-26 完成 T-204:新增 users/devices/admin_sessions/access_tokens 与任务 actor
migration、bcrypt 密码、opaque 凭证、`authctl`、管理登录/退出和 App 联合认证。
ADMIN Cookie 与 BUYER 设备 Bearer token 完全隔离;非 loopback 监听必须配置内建
TLS。真实 SQLite/Gin smoke 验证 migration up/down/up、账号/设备预置、App token、
管理登录、任务创建 actor 和退出;Playwright 在 1440×900、390×844、360×800
验证无横向溢出,发现并修复退出路由漏装配及 T-203 旧 CSRF Cookie 路径兼容问题。
142 个 Go 测试、全包 race/vet、Windows 三入口构建与根 `init.ps1` 均通过。
2026-07-26 完成 T-205:新增设备 readiness、claim/execution/lifecycle migration,
实现 client-generated claim token 安全重放、跨连接原子领取、CLAIMED/运行租约、
start/heartbeat/release、管理取消请求、App cancel-ack 和当前 claim 参考图授权。
真实 TCP 并发测试验证同设备同时 claim 只有一个成功;迁移 CLI 完成
`status/up/up/down/up`。Playwright 连接真实服务验证管理任务详情在 1440×900、
390×844、360×800 无横向溢出、破图或取消弹窗重叠;执行中安全停止文案由 SSR
测试覆盖。192 个 Go 测试、全包 race/vet、Windows 三入口构建和根 `init.ps1`
全部通过。
## 维护规则
发生以下变化时覆盖更新本文:
- 初始化 Git 或接入上游代码。
- 获得首个可复现 Android 构建、安装或启动命令。
- 建立后端和真实测试命令。
- 设备、拼多多和 VLM 基线确定。
- 项目阶段、目录或 blocker 变化。
任务的详细状态、验证和决策写入 `docs/tasks/T-<编号>.md`,本文只保留快照。