cmroubao/docs/02-requirements.md

需求

本文描述“要什么”和“怎么算达成”，不规定框架或代码实现。

一、业务现状

项	当前事实
任务来源	顺运宝 ERP 货运单/商品明细是主要来源；本项目 Admin 先保存并复核货运信息，再生成不可变采购任务。管理 Web 手工创建继续作为补充入口。
第一层样本来源	本机目录中的蝦皮订单文本和参考图；二者以蝦皮订单号作为同名文件名。
执行方式	采购人员使用 Android App 操作拼多多；需求提取、动态词搜索、最多 5 个候选证据采集、匹配建议和人工确认停止点已可运行。
核心痛点	人工把图片和描述转成搜索词、逐条比较商品并记录结果，耗时且不一致。
验证范围	一台设备、一个管理身份、一个采购执行人员、拼多多单平台。
资金边界	仅在 Admin 明确授权和一次性围栏后创建待付款订单；系统不自动付款。

二、用户角色

• 采购管理员：创建、查看、取消未执行任务，或请求执行中任务安全停止，并查看结果。
• 采购执行员：在 App 上检查设备状态、手动领取、执行和人工确认任务。
• 设备身份：代表一台获得授权的 Android 设备领取任务和上报状态。
• ERP Connector 身份：只读查询顺运宝并向后端提交最小化货运数据，不能领取任务、 创建下单授权或访问拼多多结果。
• 系统管理员/审核员：目标架构角色，MVP 不提供完整管理界面。
• 未登录用户：不能访问任务、图片、执行证据或设备接口。

三、MVP 功能

ID	功能	用户结果	优先级	用户故事
F-001	创建采购任务	管理员提交标题、SKU、描述、图片、数量和可选预算，获得任务编号。	P0	US-001
F-002	查看任务状态	管理员看到任务阶段、候选摘要、截图和失败原因。	P0	US-002
F-003	手动领取任务	空闲且就绪的 App 点击后只领取一条待处理任务。	P0	US-003
F-004	解析采购需求	系统从图片和文字提取搜索词、属性及约束，并保留原始输入。	P0	US-004
F-005	参考图搜索与规格候选判断	App 用参考图在拼多多召回商品，以 SKU 颜色/尺码硬约束检查最多 5 个结果，回传匹配候选或明确无匹配。	P0	US-004
F-006	Admin 人工选品	候选回传后自动化停止，Admin 查看证据并明确选择或拒绝候选。	P0	US-005、US-010
F-007	结果与异常回传	管理员和采购员看到成功、失败、取消及可恢复建议。	P0	US-002、US-006
F-009	手机独立执行与 VLM	App 本地完成模型判断和自动化，后端只控制任务并接收结果。	P0	US-009
F-010	授权创建待付款订单	Admin 选品后签发一次性授权，Roubao 选择已确认 SKU/数量并创建待付款订单；付款始终人工完成。	P0	US-010
F-011	导入 ERP 货运信息	管理员按完整单号或日期区间同步顺运宝货运头和全部商品明细，重复同步不重复。	P0	US-011
F-012	从货运明细生成采购任务	管理员复核商品标题、SKU、数量和参考图后，从一条商品明细生成一条不可变采购任务。	P0	US-012

F-009 手机独立执行与 VLM

1. 正式采购链路为：App 从管理后端领取完整任务，直接调用本机配置的 VLM、操作 拼多多和人工确认，再向管理后端提交结构化结果和证据。
2. 管理后端不保存、代理或下发 provider、Base URL、model、prompt 和 API Key； 后台任务也不能覆盖 App 的本地模型设置。
3. App 支持 MANUAL_FIRST 和 AI_ASSISTED。没有 VLM 时仍可直接搜索并由人员判断； 发生模式切换必须明确显示和记录，不能静默降级。
4. provider Key 使用 Android Keystore 包装的加密存储。每台设备使用独立、可撤销、 有限额度的 Key；普通日志、结果和崩溃报告不得包含秘密。
5. start 后默认获得 30 分钟有限离线执行授权，成功 heartbeat 可续期。后端短时不可用 不阻止授权内执行；授权到期必须安全停止，RUNNING 任务不得自动分给其他设备。
6. 回传结果包含模式、provider/model/prompt/schema、任务和证据哈希、候选、推荐、 人工理由及设备版本，但不包含 Key、Authorization、完整 endpoint 或供应商正文。

四、后续迭代

功能	说明	阶段
F-008 候选决策数据闭环	保存每次搜索实际曝光的最多 5 个候选、模型评估、系统推荐和人工理由，为离线评估与优化提供可信样本。	P1，T-208 已实现
完整 RBAC	采购管理员、执行员、审核员和系统管理员的细粒度权限。	V2
多设备容量调度	在当前原子领取/租约基础上增加优先级、容量、运营监控和跨实例调度。	V2
后台通知	WebSocket/厂商推送只通知有任务，App 仍通过 claim 领取。	V2
订单提交审批	在金额、店铺和品类规则内，经人工审批后允许提交订单。	V2，需单独安全评审
多平台比价	淘宝、1688、京东等平台。	V3
支付自动化	不在当前规划内，除非另行完成资金和合规评审。	未规划

F-008 候选决策数据闭环

T-206/T-207 已跑通领取、执行、候选/证据和最小结果回传；T-208 已实现可用于优化 的完整数据闭环。20 条真实任务试验必须使用这条结构化链路，避免试验结束后才发现 缺少曝光和人工标签。

1. 每次 search run 保存需求快照、精确搜索词、App/拼多多版本、采集时间以及最多 5 个实际曝光候选的原始 ordinal。该集合只是特定账号、地区、时间和平台排序下的 可见结果，不得宣称为全平台 Top 5。
2. 每个候选保存可观测标题、价格、规格文本、可选平台商品 ID/规范化链接、截图资产 和采集完整性。平台链接和图片链接可能短期有效，只是辅助字段，不能替代受控截图。
3. 候选观测、模型预测、本地推荐规则和人工结论必须分开保存。模型理由不能自动复制 为人工理由，也不能把模型预测当作真实标签。
4. 人工接受、拒绝、改选和全部无匹配都必须提供理由。第一版允许简短人工说明； T-208 改为至少一个结构化理由码、一个主要理由和可选备注，选择 OTHER 时备注 必填。无预算任务不能使用预算匹配或超预算理由。
5. 拒绝推荐项并改选时，同时记录原推荐项的拒绝理由和替代项的选择理由；全部拒绝时 每个候选都要有拒绝理由。允许人员明确选择候选后批量应用同一理由，禁止静默预填 模型结论。
6. 人工修正使用追加版本和 supersedes 关系，不覆盖历史；理由 schema、模型、 prompt、阈值和推荐策略全部版本化。
7. 后端不得根据 Android 提交的任意 URL 抓取内容。候选截图由 App 有界上传，经真实 解码、大小/像素/哈希检查和脱敏后保存；外链只做不可执行文本并清除追踪参数。
8. 图片保留期限、平台条款、训练用途和人工备注隐私必须在 T-302 前固定。没有人工 结论的数据只能用于运行审计，不能计入模型准确率。

五、业务规则

1. 标题、SKU 和图片必填，描述可为空。
2. 数量必须是正整数；最高商品总预算如填写，必须大于零。总预算表示当前任务全部 数量的商品金额上限，不包含尚无法可靠确认的运费、优惠或支付金额。
3. SKU、数量和最高商品总预算以管理员输入为准，模型不得更改。
4. 一台设备同一时间最多有一条未过期 CLAIMED 或任意 RUNNING/WAITING_CONFIRMATION 任务。
5. 一条任务同一时间只能被一台设备持有；重复点击不能产生重复领取。
6. App 未就绪时不能领取：无障碍未连接、拼多多未安装、设备 heartbeat 过期或已有 活跃任务都必须说明原因。
7. 遇到验证码、登录失效、风控提示、页面未知、预算不满足或模型低置信度时停止， 不猜测点击。
8. 候选采集阶段 order_submitted=false。只有 Admin 对当前 candidate key 签发的 一次性授权可进入订单创建；创建后必须停在待付款状态，禁止自动支付。
9. 取消和失败不得自动转成新任务；是否重试由人员显式决定。
10. 管理页面和管理 API 只允许有效 ADMIN 会话；App 执行接口只允许有效 BUYER 与 预授权设备联合身份，两种凭证不能互换。
11. 设备只能由本地管理命令预授权；首次 BUYER 登录可原子绑定空闲设备，客户端 不能自助登记、抢占或重新绑定他人设备。
12. 密码、设备 secret、管理 session 和 App access token 不得以明文持久化或进入 普通日志；禁用用户或设备后，已有凭证必须立即失效。
13. 管理登录和 App token 登录必须在高成本密码校验前按服务端观察到的来源地址限流； 超限返回通用错误和重试时间，不得泄露账号、角色或设备是否存在。
14. 管理员创建/取消和 App 状态迁移必须记录真实 user actor；设备操作还必须记录 device actor。heartbeat 不写高频事件；历史事件允许 actor 为空。
15. claim token 由 App 在请求前生成并安全保存，必须与幂等 key 独立；数据库只保存 SHA-256，API 和日志不得回显原值或 hash。
16. CLAIMED 租约过期后可以被原子回收；RUNNING/WAITING_CONFIRMATION 租约 过期后不得自动回到队列，避免失联设备与新设备重复执行。
17. 管理取消 PENDING/CLAIMED 可立即终态；执行中只设置取消请求，必须等 App 在 安全检查点确认停止后才能进入 CANCELED。
18. start 后默认运行授权为 30 分钟，App 每 30 秒 best-effort heartbeat；断网时可以 执行到服务端下发的截止时间，到期后必须安全停止。离线期间管理取消不能保证即时 生效，恢复连接后必须在继续动作前同步。
19. App 本地 VLM 配置不能来自任务 payload。后端不代理模型；端上 Key 必须加密存储， 模型不可用时允许显式切换 MANUAL_FIRST，不能阻塞人工完成任务。
20. 拼多多候选召回必须使用当前任务参考图；标题和 SKU 不能替代图片作为召回输入。 SKU 中可唯一识别的颜色、尺码是候选硬约束：任一不匹配或无法确认时不得进入自动 Top 5。回传可以少于 5 个，禁止用弱匹配凑数。
21. Admin 下单授权必须绑定 task、execution、task content hash、candidate key、 review version、原始 SKU 和数量；URL、列表 ordinal 或模型推荐均不能单独授权。
22. 一个授权最多创建一个拼多多订单。网络超时或页面不确定时必须先对账，不能重按 提交；系统不保存支付凭证，不点击付款。
23. 创建提交围栏前必须重新确认地址已配置且订单字段仍与 dry-run 一致；最终按钮必须 唯一且文本精确为“提交订单”。出现添加地址、立即支付、免密支付、先用后付或其他 自动扣款语义时必须停止。围栏创建后即使 App 在实际点击前退出，也只能查订单或 转人工，不能重新提交。
24. 顺运宝查询使用 stock.id 作为货运单外部身份，detail.details[].id 作为商品 明细外部身份；用户输入单号只是查询条件，不作为数据库主键。
25. ERP 同步先保存货运头和全部商品明细，再提取待采购需求；禁止 ERP 响应直接创建 或修改采购任务。
26. 一条商品明细最多对应一条同 revision 的采购任务；多商品货运单拆成多条采购需求， 不合并 SKU 或使用货运头总数量代替商品数量。
27. 采购任务生成前必须存在明确标题、原始 SKU/规格、正整数数量和已验证参考图。 productThumb 等未确认 ERP 引用不能当成可下载图片 URL。
28. ERP 来源更新不得覆盖已生成采购任务。系统保存新 revision/hash 并提示人工处理； 是否取消旧任务和生成新任务由管理员明确决定。
29. 收件人、电话、详细地址、ERP 账号、Cookie、JWT、验证码和完整响应不得进入采购 任务、Roubao、VLM、普通日志或 Git；货运模块也只保存采购所需最小字段。

六、第一层本地样本约定

第一层技术探针不依赖 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	同名图片	必填；缺失或匹配到多张时拒绝导入。

T-004 已固定首版规则：推荐私有目录为被 Git 忽略的 private-fixtures/shopee/， 导入命令仍要求显式目录；图片扩展名允许 .jpg/.jpeg，实际内容必须是唯一且可 解码的 JPEG；一张订单只允许一个 SKU 和一张参考图。多 SKU 或其他图片类型必须先 通过新样例扩展契约。解析器不得根据模糊内容猜测字段，也不得静默选择重名图片。

七、MVP 验收标准

单任务验收

• F-001/US-001/IX-002：合法输入创建后出现唯一任务编号和 PENDING 状态；非法 标题、SKU、数量、预算或缺失图片时在原表单显示可修复错误。
• F-002/US-002/IX-003：状态变化后管理页面能看到最新阶段、时间、设备、候选摘要 或结构化错误；无权限用户不可访问。
• F-003/US-003/IX-005：App 点击“获取任务”后原子领取一条任务；重复点击或多请求 不得领取第二条或把同一任务分配两次。T-205 已完成后端 heartbeat、原子 claim、 client-generated token 安全重放、参考图授权和租约；T-206 已完成 Android 手动 领取、安全存储、预览、start/release、前台 heartbeat 和恢复。
• F-004/US-004/IX-006：解析结果包含搜索词、识别属性、预算、数量、置信度和警告； 原始输入保留，硬约束与输入一致。T-103 已实现版本化 schema、0.75 置信阈值、 冲突转人工以及 SKU/数量的本地确定性回填；当前样本未提供预算，因此预算保持空。
• F-005/US-004/IX-006：在已验证的拼多多版本上，App 能把当前任务参考图作为图片 搜索输入，进入结果并检查最多 5 个候选；候选只有在原始 SKU 的颜色、尺码硬约束 均确认匹配时才能进入回传列表。匹配项按评估结果排序且最多 5 个，不足时不得凑数； 无合理候选时明确结束而不是随意选择。
• F-006/US-005/US-010/IX-011：候选回传后进入 WAITING_CONFIRMATION；Admin 必须 按 candidate key 查看证据并为接受项及所有拒绝项选择结构化理由。
• F-007/US-006/IX-008：失败包含稳定错误码、失败步骤、可读说明和必要截图；重新 打开任务后证据仍可查看。
• US-007/IX-001/IX-004：管理员可登录和退出，采购员可用预授权设备取得 1 小时 Bearer token；匿名、角色错误、禁用、过期、篡改和跨端凭证替代均被拒绝。
• F-009/US-009/IX-010：后台任务不能覆盖手机 VLM 配置；断开管理后端超过 90 秒后， App 仍可在服务端下发的有限授权内执行，授权到期安全停止且任务不被重复分配。
• F-010/US-010/IX-011：只有当前 Admin 一次性授权可驱动 Roubao 创建一笔待付款 订单；SKU、数量和价格重新核验，订单号/下单时间回传后提醒人员去拼多多付款。

试验验收

使用至少 20 条经采购人员确认的代表性任务：

• 至少 80% 能自动到达合理候选商品页或给出正确的“无匹配/需人工”结论。
• 至少 70% 的首选候选被采购人员判定可接受。
• 不发生重复领取、未授权订单、重复订单或自动付款。
• 每条失败任务都能定位到具体步骤和错误类别。
• 记录每条任务的耗时、人工介入点和候选接受结果，用于决定是否进入 V2。
• 同时记录实际曝光候选、模型预测、系统推荐和人工结构化理由；准确率以人工结论为 标签，不能用模型自己的判断验证模型。

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

八、范围决策

问题	当前决策
客户端形态	管理人员用 Web，采购人员用 Android App，共享统一后端。
任务到达	MVP 由 App 手动领取；后续通知只作唤醒/提示。
搜索方式	正式候选召回使用当前任务参考图进入拼多多原生以图搜图；关键词只保留为开发诊断能力，不作为该业务链路的召回输入。
搜索结果	最多检查图片搜索返回的前 5 个可见候选，以 SKU 颜色/尺码硬约束过滤后回传 0..5 个，避免无界遍历和凑数。
下单边界	Admin 明确选品后只允许创建一笔待付款订单；订单号回传后由人员在拼多多确认并付款，系统不自动支付。
账号边界	验证版为 ADMIN 会话 + BUYER/预授权设备联合身份；完整人员 RBAC 后置。
第一层任务输入	从本机私有蝦皮订单文件生成测试任务，不先建设 Go-Gin。
执行边界	手机本地完成 VLM、拼多多自动化和人工确认；后端负责身份、任务控制和结果审计。
离线边界	start 默认授权 30 分钟；后端断线可继续到截止时间，过期安全停止且不自动重分配。

九、待确认与风险

• Roubao 上游仓库、许可证和远端构建版本已核实；源码导入、分支选择和本机构建仍由 T-001 完成。
• 首份蝦皮样本已由 T-004 真实导入验证；当前只支持单 SKU 和 JPEG，扩展格式需新 样例和独立任务。
• OnePlus PKG110、Android 16/API 36、拼多多 8.17.0 的首页、搜索输入、结果页、 候选卡和详情返回已形成可复现基线；不同账号、类目和页面实验的差异仍是风险。
• 拼多多 8.17.0 的图片搜索入口、相册选择页和图片结果页仍需在 T-211 建立真机结构 基线；UI 无法唯一确认当前任务图片时必须停止，不能选择“最近图片”后盲目继续。
• VLM 需求提取的 provider-neutral 合约和 OpenAI 兼容适配器已实现；真实供应商、 模型、测试凭证、成本上限、数据留存地区和图片隐私规则仍待确认。候选评估契约和 本机 mock 集成已实现，但尚无真实模型质量证据。
• 拼多多平台条款、自动化允许范围和账号风控需要业务方确认；项目不实现绕过措施。
• 创建待付款订单前必须在 T-215 至 T-218 固定 SKU、数量、价格、地址可见性、运费/ 优惠不确定性、一次性提交和订单列表对账规则；不满足时安全停止。
• 自动支付明确排除；人员必须在拼多多订单列表复核后付款。
• Admin 只有在唯一订单对账成功后才显示订单号、下单时间和“待人工确认付款”；对账 中或人工核对状态不得冒充成功，也不得提供重试提交或付款入口。