cmroubao/docs/current-state.md

# 当前实现状态

> 可覆盖的项目级快照。任务执行日志写入对应任务文件。

## 当前快照

- 日期：2026-07-29
- 阶段：T-230 待将本机 OCR 接入 ERP 自动登录并移除人工 `/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 后端以受锁内存 ERP 会话直连异步按完整单号或创建日期同步；v12 保存
  同步记录、货运头和全部明细，canonical hash 控制 revision，Admin 已有 `/freight`、
  `/freight/import`、`/freight/{id}` 与对应 JSON API。
- ERP Go 迁移：T-225 已用脱敏 fixture 固定 `internal/platform/shunyunbao` 的 header、
  单号/日期查询、分页、详情批量和字段 allowlist，并使货运用例依赖来源中立错误。T-226
  已增加受锁保护的 Go 内存 Cookie jar、验证码 ticket、登录和用户校验，以及 ADMIN 的
  `/erp` 页面/API；账号密码可由 `backend-api/.env` 的受控 `CMROUBAO_SHUNYUNBAO_*`
  回退提供，进程环境变量优先，重启后需人工重新登录。T-227 已将其作为 `FreightSource`，
  查询先校验会话、再执行有界分页/详情
  批量并返回 allowlist；T-228 已删除旧 Python Connector、loopback 端口和共享 API Key；
  未访问真实 ERP。
- ERP 增量同步：v14 支持 Asia/Shanghai 创建日期闭区间和“同步至现在”，source 单窗
  最多 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-226 至 T-229 已运行 `go test ./...`、`go test -race ./...`、`go vet ./...`
  和三个 Go 入口构建；T-227 增加 Go source 的伪 ERP 会话预检、完整单号、日期分页去重、
  详情 allowlist 和稳定错误码覆盖；根 `init.ps1` 的 Android 测试/Debug APK 与 Go 标准
  验证也通过，均未访问真实 ERP；
  覆盖 v14 上下迁移、7 天切窗、水位重叠、中途失败、空窗口、重复页、来源 revision、
  水位事务/不回退、Admin API/SSR 和 Go source 严格响应窗口；未访问真实 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-228 ERP 来源：字段契约已固定 stock/detail/item 外部身份、PII 最小化和
  缺图边界；Go API 以受锁内存会话完成受控验证码登录，并直接按完整单号或日期范围查询
  allowlist schema。T-229 仅允许 API 从当前目录 `.env` 回退读取三个 ERP 配置，且不会
  改写进程环境或加载其他配置。旧 Python Connector、8091 端口和共享服务密钥已删除；
  未访问线上 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/tasks/T-225.md` | DONE | 冻结 Go 直连 ERP 协议与安全边界 |
| `docs/tasks/T-226.md` | DONE | Go ERP 会话、验证码登录与 Admin 连接页 |
| `docs/tasks/T-227.md` | DONE | Go 直连顺运宝查询接入货运同步 |
| `docs/tasks/T-228.md` | DONE | 移除 Python Connector 并完成 Go 切换 |
| `docs/tasks/T-229.md` | DONE | 从受控 `.env` 加载 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 |
| `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-229 ERP 契约、货运存储、采购需求生成、日期增量同步、Go
  直连协议、人工验证码会话、直连 `FreightSource`、旧 Connector 清理和受控本地凭证加载。
- 进行中：无。
- 下一步：T-230 在按单号导入前受控调用本机 OCR 并建立 ERP 会话；完成后确认开放 API、
  OCR/ERP 数据使用权限，并以受控单号执行一次不记录订单内容的 smoke。

## 当前可运行内容

```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 = "至少 5 个 UTF-8 字节"
go run ./cmd/authctl create-user ADMIN admin
Remove-Item Env:CMROUBAO_AUTH_PASSWORD
$env:CMROUBAO_AUTH_PASSWORD = "账号新密码，至少 5 个 UTF-8 字节"
go run ./cmd/authctl reset-password 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`，本文只保留快照。