docs: define Shopee probe fixture input

2026-07-25 17:15:05 +08:00
parent 50a6d8ee5b
commit 285606639b
11 changed files with 164 additions and 10 deletions
@@ -9,6 +9,8 @@ Thumbs.db
 .env
 .env.*
 !.env.example
+.local/
+private-fixtures/
 local.properties
 google-services.json
 secrets.properties
@@ -56,7 +56,7 @@
 严格按以下顺序推进：

 1. 接入并构建 Roubao Android 基线。
-2. 用 App 内固定任务验证拼多多搜索和页面操作。
+2. 用本机蝦皮订单样本生成固定探针任务，验证拼多多搜索和页面操作。
 3. 接入 VLM，验证结构化需求提取和候选判断。
 4. 建立最小后端和管理页面。
 5. 接入手动领取、租约、状态和结果回传。
@@ -7,6 +7,7 @@
 | 项 | 当前事实 |
 | --- | --- |
 | 任务来源 | 其他管理后台或本项目管理 Web 采集商品标题、描述、图片、数量和预算。 |
+| 第一层样本来源 | 本机目录中的蝦皮订单文本和参考图；二者以蝦皮订单号作为同名文件名。 |
 | 执行方式 | 采购人员使用 Android App 操作拼多多；当前没有可运行实现。 |
 | 核心痛点 | 人工把图片和描述转成搜索词、逐条比较商品并记录结果，耗时且不一致。 |
 | 验证范围 | 一台设备、一个管理身份、一个采购执行人员、拼多多单平台。 |
@@ -58,7 +59,38 @@
   `order_submitted` 必须为 `false`。
 9. 取消和失败不得自动转成新任务；是否重试由人员显式决定。

-## 六、MVP 验收标准
+## 六、第一层本地样本约定
+
+第一层技术探针不依赖 Go-Gin。开发工具从用户明确指定的本机目录读取蝦皮订单样本，
+规范化为与未来 API 一致的采购任务，再提供给 Android/VLM 工作流。
+
+已经确认：
+
+- 一份文本文件和一份参考图使用相同的蝦皮订单号作为主文件名，例如
+  `240725001234.txt` 与 `240725001234.jpg`。
+- 文本包含自己的蝦皮店铺名、待采集商品标题、SKU 和数量。
+- 2026-07-25 提供的首份样例是可按 UTF-8 解码的无 BOM 文本，固定四行标签为
+  `店铺名：`、`商品标题：`、`SKU：`、`数量：`。
+- 首份同名参考图是可正常解码的 JPEG；具体像素尺寸只是样本事实，不作为固定限制。
+- 蝦皮订单号作为外部来源标识，只用于关联样本和追踪，不作为内部数据库主键。
+- 参考图和订单文本属于私有验证数据，不得提交 Git。
+
+导入后至少形成以下不可变原始字段：
+
+| 字段 | 来源 | 规则 |
+| --- | --- | --- |
+| `source_order_no` | 文件主名 | 必填；同一批样本内唯一。 |
+| `source_store_name` | 文本 | 必填；日志和截图默认脱敏。 |
+| `title` | 文本 | 必填。 |
+| `sku` | 文本 | 必填；不得由模型改写。 |
+| `quantity` | 文本 | 必须为正整数；不得由模型改写。 |
+| `reference_image` | 同名图片 | 必填；缺失或匹配到多张时拒绝导入。 |
+
+正式私有样本目录、是否允许 JPEG 以外的图片，以及一张订单包含多个 SKU 时的文本
+和图片命名规则仍待 `T-004` 固定。解析器不得根据模糊内容猜测字段，也不得静默选择
+重名图片；遇到不是上述四行格式的文件应明确失败，除非先通过新样例扩展契约。
+
+## 七、MVP 验收标准

 ### 单任务验收

@@ -89,7 +121,7 @@

 这些比例是进入下一阶段的验证门槛，不是正式生产 SLA。

-## 七、范围决策
+## 八、范围决策

 | 问题 | 当前决策 |
 | --- | --- |
@@ -99,10 +131,14 @@
 | 搜索结果 | 最多检查前 5 个可见候选，避免无界遍历。 |
 | 下单边界 | MVP 停在候选或订单确认页，不提交订单、不支付。 |
 | 账号边界 | 验证版为单管理身份 + 设备身份；完整人员 RBAC 后置。 |
+| 第一层任务输入 | 从本机私有蝦皮订单文件生成测试任务，不先建设 Go-Gin。 |

-## 八、待确认与风险
+## 九、待确认与风险

- Roubao 上游源码、许可证、可构建分支和 Android 版本支持仍需在 `T-001` 核实。
+- Roubao 上游仓库、许可证和远端构建版本已核实；源码导入、分支选择和本机构建仍由
+  `T-001` 完成。
+- 首份蝦皮样本格式已核实；正式私有目录、更多图片类型和一单多 SKU 规则仍需在
+  `T-004` 固定。
 - 拼多多版本、页面结构、账号登录状态和测试设备尚未形成可复现基线。
 - VLM 厂商、模型、成本上限、数据留存地区和图片隐私规则待确认。
 - 拼多多平台条款、自动化允许范围和账号风控需要业务方确认；项目不实现绕过措施。
@@ -12,6 +12,7 @@
 | Android SDK | compileSdk/targetSdk 34；minSdk 26；SDK Build Tools 34.0.0 | 上游已核实 | 支持 Android 8.0+；真机自动化优先 Android 11+。 |
 | Android UI | Jetpack Compose + Material 3；Compose Compiler 1.5.5 | 上游已核实 | Compose BOM 为 2023.10.01。 |
 | Android 自动化 | 项目目标以 `AccessibilityService` 为主，Shizuku 为兼容/增强路径 | 目标已定，待实现 | 上游 `main` 使用 Shizuku 13.1.5；无障碍实现位于独立开发分支，不能把它误认为主分支现状。 |
+| 第一层任务源 | UTF-8 四行蝦皮订单文本 + 同订单号 JPEG | 首份样例已核实，待实现 | 使用 Debug/测试专用 `TaskSource`；原始数据和生成物不得提交。 |
 | Android 长任务 | 前台服务 + 持续通知 | 计划采用 | 降低执行中被系统挂起的风险，仍需处理进程死亡恢复。 |
 | 后端语言 | Go 1.23.0 | MVP 已定 | 与现有本机工具链一致；构建测试必须设置 `GOTOOLCHAIN=local` 防止静默升级。 |
 | 后端骨架 | Go Blueprint v0.10.11 生成的最小 Gin + SQLite 工程 | MVP 已定 | 只作为一次性脚手架输入；生成后立即重写版本约束。 |
@@ -67,6 +67,7 @@ internal/platform/          # 配置、日志、文件存储和 VLM 适配器
 ```text
 ui/                  # 登录、任务列表、执行状态、设置
 taskclient/          # 后端 API、认证、幂等和重试
+tasksource/          # 统一任务源；本地探针与后端 API 实现
 workflow/            # ProcurementWorkflow 状态机
 automation/          # Accessibility 节点、截图、点击、输入、滑动
 ai/                  # 结构化 AI 请求/响应，不含供应商业务类型
@@ -108,7 +109,10 @@ evidence/            # 截图、步骤日志、脱敏和上传
 ### 3.1 技术探针

 ```text
-App 内固定任务
+本机私有蝦皮订单目录
+ -> Debug 导入工具按订单号配对文本和参考图
+ -> 规范化为 ProbeTask
+ -> Android FixtureTaskSource
 -> 校验设备就绪
 -> 解析为固定/模型搜索词
 -> 打开拼多多并搜索
@@ -119,6 +123,24 @@ App 内固定任务

 该阶段不依赖后台，用于尽早判断 Android 自动化是否可行。

+`TaskSource` 是工作流读取任务的唯一边界：
+
+- 第一层使用 `FixtureTaskSource`，消费 Debug 导入工具生成的本地私有样本。
+- 第二层替换为 `HttpTaskSource`，通过 Go-Gin 的 `claim-next` 和资产接口读取任务。
+- 两种实现必须产生相同的领域字段；workflow、AI 和 automation 不得判断任务来自
+  文件还是 HTTP。
+
+Debug 导入工具运行在开发机上，Android App 不能假定能直接访问 Windows 绝对路径。
+工具读取用户显式配置的目录，将数据写入被 Git 忽略的 `.local/` 生成目录，再由
+Debug 构建或测试装载。导入必须：
+
+- 用文件主名关联订单号，不能用文本模糊匹配图片。
+- 首版严格解析 UTF-8 四行标签 `店铺名：`、`商品标题：`、`SKU：`、`数量：`。
+- 校验店铺名、标题、SKU、正整数数量和唯一且可解码的 JPEG 参考图。
+- 对缺失、重复、编码无法识别和字段格式未知返回结构化错误。
+- 不把完整订单号、店铺名、原图路径写入普通日志。
+- 仅在用户明确配置 VLM 后发送必要的标题、SKU 和参考图；不发送订单号或店铺名。
+
 ### 3.2 MVP 业务闭环

 ```text
@@ -294,7 +316,7 @@ IDLE
 ## 九、开发顺序

 1. 接入 Android 基线并记录真实构建方式。
-2. 固定任务 + 固定搜索词跑通拼多多页面探针。
+2. 导入一条脱敏蝦皮样本，以固定搜索词跑通拼多多页面探针。
 3. 接入需求提取和候选判断，验证结构化输出。
 4. 建立后端数据模型、API 和简单管理 Web。
 5. 接入 App 领取、租约、进度和结果。
@@ -60,6 +60,9 @@
 ## 7. 安全与隐私

 - 密钥只来自环境变量或被忽略的本地配置。
+- 真实蝦皮订单文本、参考图及其规范化生成物只能位于仓库外或 `.local/`、
+  `private-fixtures/` 等被忽略目录；测试使用脱敏 fixture。
+- 普通日志不得输出完整蝦皮订单号、店铺名或本机原图绝对路径。
 - 日志默认脱敏，不记录 Authorization、Cookie、密码、设备令牌或完整地址。
 - 上传文件限制媒体类型、大小和解码结果，随机化服务端文件名。
 - 不绕过第三方平台限制、验证码、风控或系统权限。
@@ -73,6 +76,7 @@
 - 领域状态机、硬约束、错误码：单元测试。
 - API 权限、事务、幂等、文件校验：集成测试。
 - VLM adapter：固定 fixture/契约测试，不让普通测试依赖真实付费 API。
+- 蝦皮文件导入：覆盖同名配对、缺图、重复图片、未知格式、非法数量和敏感日志检查。
 - Android workflow：用 fake automation/AI client 测状态和安全停止。
 - 拼多多真实流程：指定版本测试机手工 smoke，保存脱敏截图和步骤证据。
 - UI：覆盖默认、加载、空、错误、权限和中断状态。
@@ -18,6 +18,7 @@
 | T-001 | 初始化 Git 并接入 Roubao Android 基线 | - | 记录上游 URL/commit/许可证；Debug APK 构建通过；真实命令同步文档；不含密钥 |
 | T-002 | 建立测试设备基线和就绪检查 | T-001 | 记录 Android/拼多多/App 版本；检测安装、无障碍、前台 App 和登录阻塞 |
 | T-003 | 建立 Android workflow 测试骨架 | T-001 | fake automation 下可测状态迁移、timeout、retry 和安全停止 |
+| T-004 | 导入本机蝦皮订单验证样本 | T-001 | 同订单号文本/图片可靠配对并生成 ProbeTask；异常明确失败；私有数据不进 Git |

 ## Phase 1：最高风险技术探针

@@ -25,7 +26,7 @@
 | --- | --- | --- | --- |
 | T-101 | 固定任务跑通拼多多关键词搜索 | T-002、T-003 | 用固定搜索词进入结果页；未知页、验证码和登录页安全停止 |
 | T-102 | 浏览并采集最多 5 个候选 | T-101 | 可进入候选详情、返回并记录证据；无界滑动被禁止 |
-| T-103 | 接入 VLM 需求提取 | T-101 | 图片+文字输出符合 schema；数量和预算保持原值；低置信度转人工 |
+| T-103 | 接入 VLM 需求提取 | T-101、T-004 | 蝦皮样本图片+文字输出符合 schema；SKU/数量保持原值；低置信度转人工 |
 | T-104 | 接入候选评估并停在人工确认点 | T-102、T-103 | 给出匹配/缺失理由；不得提交订单或支付 |

 ## Phase 2：最小后台闭环
@@ -13,12 +13,15 @@
 - 本机 Android 工具：JDK 17.0.13 和 ADB 已有；Android Studio、Android SDK 34
  未检测到，`ANDROID_HOME`/`ANDROID_SDK_ROOT` 未设置
 - 测试：无
- 数据：只有 `deepseek总结.txt` 背景摘要和本套项目文档
+- 版本控制内数据：只有 `deepseek总结.txt` 背景摘要和本套项目文档
+- 本地私有样本：仓库根目录存在一组未跟踪、已本地排除的同名蝦皮文本/JPEG；
+  已核实 UTF-8 四行字段格式和图片可解码，真实内容未纳入 Git
 - 标准启动路径：未配置；`init.ps1`/`init.sh` 会主动失败
 - 标准验证路径：文档结构和链接检查；无代码构建
 - 当前 blocker：Roubao 尚未导入，`main` 与无障碍开发分支尚未完成代码差异评估；
  Android Studio/SDK 34 未安装或未被检测到，测试设备状态未知；拼多多测试版本/账号
-  未建立基线；VLM 供应商和测试凭证未确认
+  未建立基线；蝦皮样本正式私有目录、更多图片类型和一单多 SKU 规则未确认；VLM
+  供应商和测试凭证未确认

 ## 当前目录

@@ -15,10 +15,14 @@ write_paths:
  - init.ps1
  - init.sh
  - docs/00-ai-start-here.md
+  - docs/02-requirements.md
  - docs/03-tech-stack.md
  - docs/04-architecture.md
  - docs/05-coding-rules.md
+  - docs/06-tasks.md
  - docs/current-state.md
+  - docs/tasks/T-004.md
+  - progress.md
 ---

 ## 问题 / 背景
@@ -101,5 +105,7 @@ Set-Location android-buyer
 - 新增根目录 `.gitignore`，忽略本地 SDK 配置、Firebase 配置、密钥、构建产物、
  运行数据和日志。
 - 已核实 Roubao 上游版本并更新技术栈、当前状态及本任务，但 Android 源码尚未导入。
+- 用户确认第一层使用本机蝦皮订单文本和同订单号参考图作为真实样本；已将输入契约
+  和后续 T-004 同步到需求、架构、编码规则及路线图。
 - 本次只建立文档与脚本提交；Gradle 构建、测试、APK 安装和设备 smoke 均未运行。
 - T-001 保持 `DOING`，剩余 blocker 见 `docs/current-state.md`。
@@ -0,0 +1,71 @@
+---
+id: T-004
+title: 导入本机蝦皮订单验证样本
+phase: 0
+deps: [T-001]
+status: TODO
+created: 2026-07-25
+context_ref: null
+work_branch: null
+write_paths:
+  - docs/tasks/T-004.md
+  - android-buyer/tools/**
+  - android-buyer/app/src/debug/**
+  - android-buyer/app/src/test/**
+  - .gitignore
+  - docs/03-tech-stack.md
+  - docs/04-architecture.md
+  - docs/05-coding-rules.md
+  - docs/current-state.md
+---
+
+## 问题 / 背景
+
+第一层技术探针需要使用用户已有的蝦皮订单资料，而不是在 Android 代码里硬编码虚构
+需求。本机目录中一份文本和一份参考图以蝦皮订单号同名；文本包含自己的店铺名、
+待采集商品标题、SKU 和数量。Android 设备不能直接读取 Windows 绝对路径，需要一个
+Debug/测试专用导入边界。
+
+首份同名样例已在 2026-07-25 完成非业务内容核实：文本是可按 UTF-8 解码的无 BOM
+四行格式，标签为 `店铺名：`、`商品标题：`、`SKU：`、`数量：`；参考图是可解码的
+JPEG。正式私有目录、额外图片类型和一单多 SKU 规则仍未固定。
+
+## 关联需求与交互
+
+- 功能：为 F-004 提供第一层原始输入，不改变正式 F-001 创建任务流程。
+- 用户故事：US-004。
+- 交互：无生产 UI；导入失败通过开发命令和测试报告返回。
+- 架构/API：`04-architecture.md` 3.1；不调用正式后台 API。
+
+## 方案
+
+1. 将当前根目录样例迁移或配置到明确的私有样本目录，保持 Git 忽略。
+2. 以已核实的 UTF-8 四行标签和 JPEG 为首版契约；一单多 SKU 不明确前拒绝导入。
+3. 实现开发机导入工具，按文件主名精确配对文本和唯一参考图。
+4. 校验订单号、店铺名、标题、SKU、正整数数量、图片存在且可解码。
+5. 生成与未来 HTTP `TaskSource` 同构的 `ProbeTask`，输出到被 Git 忽略的 `.local/`
+   目录，供 Debug 构建和测试装载。
+6. 为有效样本、缺图、多图、重复订单号、未知编码/格式、非法数量和敏感日志编写测试。
+
+## 验收要点
+
+- [ ] 一组合法脱敏文本和参考图能稳定生成一个 `ProbeTask`。
+- [ ] `source_order_no` 来自文件主名；标题、SKU 和数量与原文完全一致。
+- [ ] 缺失或匹配到多张参考图、必填字段缺失、数量非法时导入明确失败。
+- [ ] Android workflow 通过 `TaskSource` 消费结果，不依赖 Windows 路径或导入器类型。
+- [ ] 真实订单文件、图片、生成物和本机绝对路径均未进入 Git。
+- [ ] 日志不包含完整订单号、店铺名或原图绝对路径。
+- [ ] 普通自动化测试不调用真实付费 VLM。
+
+## 边界
+
+- 不实现 Go-Gin、SQLite、任务领取、鉴权或管理 Web。
+- 不实现拼多多自动化和 VLM 供应商调用。
+- 不把模糊文本解析结果当成成功，不静默选择重名图片。
+- 不处理未经确认的一单多 SKU 格式。
+
+## 执行记录
+
+尚未开始，等待 T-001 完成。前置检查已确认一组同名文本/JPEG 存在，文本字段结构和
+图片解码有效；未记录或提交实际订单号、店铺名、商品内容及图片。实现时仍需确定正式
+私有目录和一单多 SKU 规则。
@@ -30,3 +30,11 @@
  文档和占位初始化脚本纳入基线提交。
 - 影响：T-001 进入 `DOING`；下一步比较 `main` 与无障碍开发分支、导入固定 commit，
  安装 Android SDK 34 后取得首个可复现 APK 构建证据。
+
+## 2026-07-25 第一层验证数据来源
+
+- 类型：重大决策
+- 内容：第一层不先建设 Go-Gin；从用户指定的本机目录读取以蝦皮订单号同名的文本
+  和参考图，规范化为与未来 HTTP 接口一致的探针任务。
+- 影响：新增 T-004；私有订单资料和生成物不得进入 Git。首份样例已确认 UTF-8 四行
+  标签和同名 JPEG，Android workflow 只依赖统一 `TaskSource`。