1

T-004

ila edited this page 2026-08-07 16:36:23 +08:00

Table of Contents

• 问题 / 背景
• 关联需求与交互
• 方案
• 验收要点
• 边界
• 执行记录
• 2026-07-25：任务开始
• 2026-07-25：实现和验证完成

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.

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

---

id: T-004 title: 导入本机蝦皮订单验证样本 phase: 0 deps: [T-001] status: DONE created: 2026-07-25 context_ref: d57c4ae2d4 work_branch: main write_paths:

• docs/tasks/T-004.md
• android-buyer/build.gradle.kts
• android-buyer/settings.gradle.kts
• android-buyer/task-contract/**
• android-buyer/tools/**
• android-buyer/app/build.gradle.kts
• android-buyer/app/src/main/java/com/roubao/autopilot/workflow/**
• android-buyer/app/src/debug/**
• android-buyer/app/src/test/**
• .gitignore
• README.md
• 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/current-state.md
• progress.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. 正式私有目录约定为仓库根目录 private-fixtures/shopee/，工具仍要求显式 --input；当前根目录样例保持原位并继续通过本地 exclude 隔离。
2. 以已核实的 UTF-8 四行标签和 JPEG 内容为首版契约；允许 .jpg/.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 格式。

执行记录

2026-07-25：任务开始

• 基于 T-003 提交 d57c4ae 开始，依赖 T-001 已满足。
• 前置检查确认一组同名文本/JPEG 存在，文本字段结构和图片解码有效；未记录或提交 实际订单号、店铺名、商品内容及图片。
• 固定首版规则：推荐私有目录为 private-fixtures/shopee/；只接收实际内容为 JPEG 的 .jpg/.jpeg；一张订单只有一个 SKU 和一张参考图，多 SKU 必须先扩展契约。

2026-07-25：实现和验证完成

• 新增纯 Kotlin task-contract 模块，统一定义 ProbeTask、ProbeReferenceImage、 TaskSource 和版本化 JSON codec；Android 与开发机工具使用同一模型。
• 新增 tools:shopee-importer CLI。它要求显式输入/输出目录，严格解析 UTF-8 无 BOM 四行标签，只接受唯一且可解码的 JPEG，限制文本 64 KiB、图片 20 MiB，并为错误 返回稳定 code。
• 生成物使用匿名 probe_id 和匿名图片文件名，但私有 JSON 内保留权威 source_order_no、店铺名、标题、SKU、数量；参考图保存大小和 SHA-256。
• 输出目录必须为空或带工具 marker，避免清理任意目录；CLI 普通输出只有导入数量， 不打印完整订单号、店铺名或源路径。
• 新增 Debug FixtureTaskSource 和 ProbeWorkflowCoordinator。workflow 只依赖 TaskSource，不知道任务来自文件还是未来 HTTP。
• syncProbeFixtures 仅在显式传入 -PprobeFixturesDir 时把私有生成物放入 Debug 构建资产；不带属性的普通构建会清空先前生成资产。
• 脱敏测试覆盖 JSON round-trip、合法导入、缺图、多图、未知图片类型、非法 UTF-8、 缺字段、非法数量、损坏 JPEG、大小写重复订单号、敏感 CLI 输出和 Android TaskSource/workflow 边界。
• 真实本地样本运行成功并生成 1 个任务；自动比较确认订单号、店铺名、标题、SKU、 数量逐字段相等，参考图复制前后 SHA-256 相等。比较结果只记录布尔值，未输出内容。
• 带私有属性的 Debug APK 包含 1 个任务文档和 1 张匿名 JPEG；随后默认重建确认 APK 中 probe-fixtures 条目为 0，生成资产也已清除。
• 全量 lintDebug test assembleDebug 成功；三个模块共 38 次测试执行， 0 failure、0 error、0 skipped。