148 lines
8.8 KiB
Markdown
148 lines
8.8 KiB
Markdown
# 需求
|
||
|
||
> 本文描述“要什么”和“怎么算达成”，不规定框架或代码实现。
|
||
|
||
## 一、业务现状
|
||
|
||
| 项 | 当前事实 |
|
||
| --- | --- |
|
||
| 任务来源 | 其他管理后台或本项目管理 Web 采集商品标题、描述、图片、数量和预算。 |
|
||
| 第一层样本来源 | 本机目录中的蝦皮订单文本和参考图；二者以蝦皮订单号作为同名文件名。 |
|
||
| 执行方式 | 采购人员使用 Android App 操作拼多多；当前没有可运行实现。 |
|
||
| 核心痛点 | 人工把图片和描述转成搜索词、逐条比较商品并记录结果，耗时且不一致。 |
|
||
| 验证范围 | 一台设备、一个管理身份、一个采购执行人员、拼多多单平台。 |
|
||
| 资金边界 | MVP 不提交订单、不支付，只验证到人工确认位置。 |
|
||
|
||
## 二、用户角色
|
||
|
||
- **采购管理员**：创建、查看、取消尚未执行的任务并查看执行结果。
|
||
- **采购执行员**：在 App 上检查设备状态、手动领取、执行和人工确认任务。
|
||
- **设备身份**：代表一台获得授权的 Android 设备领取任务和上报状态。
|
||
- **系统管理员/审核员**：目标架构角色，MVP 不提供完整管理界面。
|
||
- **未登录用户**：不能访问任务、图片、执行证据或设备接口。
|
||
|
||
## 三、MVP 功能
|
||
|
||
| ID | 功能 | 用户结果 | 优先级 | 用户故事 |
|
||
| --- | --- | --- | --- | --- |
|
||
| F-001 | 创建采购任务 | 管理员提交标题、描述、图片、数量和可选预算，获得任务编号。 | P0 | US-001 |
|
||
| F-002 | 查看任务状态 | 管理员看到任务阶段、候选摘要、截图和失败原因。 | P0 | US-002 |
|
||
| F-003 | 手动领取任务 | 空闲且就绪的 App 点击后只领取一条待处理任务。 | P0 | US-003 |
|
||
| F-004 | 解析采购需求 | 系统从图片和文字提取搜索词、属性及约束，并保留原始输入。 | P0 | US-004 |
|
||
| F-005 | 拼多多搜索与候选判断 | App 搜索并检查少量结果，得到一个候选或明确无匹配。 | P0 | US-004 |
|
||
| F-006 | 人工确认停止点 | 自动化停在候选/订单确认位置，采购员确认结果或拒绝候选。 | P0 | US-005 |
|
||
| F-007 | 结果与异常回传 | 管理员和采购员看到成功、失败、取消及可恢复建议。 | P0 | US-002、US-006 |
|
||
|
||
## 四、后续迭代
|
||
|
||
| 功能 | 说明 | 阶段 |
|
||
| --- | --- | --- |
|
||
| 完整 RBAC | 采购管理员、执行员、审核员和系统管理员的细粒度权限。 | V2 |
|
||
| 多设备调度 | 设备心跳、任务队列、租约回收和容量调度。 | V2 |
|
||
| 后台通知 | WebSocket/厂商推送只通知有任务，App 仍通过 claim 领取。 | V2 |
|
||
| 订单提交审批 | 在金额、店铺和品类规则内，经人工审批后允许提交订单。 | V2，需单独安全评审 |
|
||
| 多平台比价 | 淘宝、1688、京东等平台。 | V3 |
|
||
| 支付自动化 | 不在当前规划内，除非另行完成资金和合规评审。 | 未规划 |
|
||
|
||
## 五、业务规则
|
||
|
||
1. 标题、描述和图片至少满足“标题或描述不为空，且图片存在”。
|
||
2. 数量必须是正整数；最高预算如填写，必须大于零。
|
||
3. 数量和最高预算以管理员输入为准，模型不得更改。
|
||
4. 一台设备同一时间最多有一条 `CLAIMED` 或 `RUNNING` 任务。
|
||
5. 一条任务同一时间只能被一台设备持有；重复点击不能产生重复领取。
|
||
6. App 未就绪时不能开始：无障碍未授权、拼多多未安装、设备离线或已有运行任务都
|
||
必须说明原因。
|
||
7. 遇到验证码、登录失效、风控提示、页面未知、预算不满足或模型低置信度时停止，
|
||
不猜测点击。
|
||
8. MVP 的“成功”表示完成验证闭环并得到人工确认的候选结果，
|
||
`order_submitted` 必须为 `false`。
|
||
9. 取消和失败不得自动转成新任务；是否重试由人员显式决定。
|
||
|
||
## 六、第一层本地样本约定
|
||
|
||
第一层技术探针不依赖 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 验收标准
|
||
|
||
### 单任务验收
|
||
|
||
- F-001/US-001/IX-001：合法输入创建后出现唯一任务编号和 `PENDING` 状态；非法
|
||
数量、预算或缺失图片时在原表单显示可修复错误。
|
||
- F-002/US-002/IX-002：状态变化后管理页面能看到最新阶段、时间、设备、候选摘要
|
||
或结构化错误；无权限用户不可访问。
|
||
- F-003/US-003/IX-004：App 点击“获取任务”后原子领取一条任务；重复点击或多请求
|
||
不得领取第二条或把同一任务分配两次。
|
||
- F-004/US-004/IX-006：解析结果包含搜索词、识别属性、预算、数量、置信度和警告；
|
||
原始输入保留，硬约束与输入一致。
|
||
- F-005/US-004/IX-006：在已验证的拼多多版本上，App 能从任务进入搜索结果并检查
|
||
最多 5 个候选；无合理候选时明确结束而不是随意选择。
|
||
- F-006/US-005/IX-007：流程到达人工确认点后停止；MVP 任意路径都不能触发最终
|
||
提交订单或支付。
|
||
- F-007/US-006/IX-008：失败包含稳定错误码、失败步骤、可读说明和必要截图；重新
|
||
打开任务后证据仍可查看。
|
||
|
||
### 试验验收
|
||
|
||
使用至少 20 条经采购人员确认的代表性任务：
|
||
|
||
- 至少 80% 能自动到达合理候选商品页或给出正确的“无匹配/需人工”结论。
|
||
- 至少 70% 的首选候选被采购人员判定可接受。
|
||
- 不发生重复领取、重复执行导致的不可逆操作或订单提交。
|
||
- 每条失败任务都能定位到具体步骤和错误类别。
|
||
- 记录每条任务的耗时、人工介入点和候选接受结果，用于决定是否进入 V2。
|
||
|
||
这些比例是进入下一阶段的验证门槛，不是正式生产 SLA。
|
||
|
||
## 八、范围决策
|
||
|
||
| 问题 | 当前决策 |
|
||
| --- | --- |
|
||
| 客户端形态 | 管理人员用 Web，采购人员用 Android App，共享统一后端。 |
|
||
| 任务到达 | MVP 由 App 手动领取；后续通知只作唤醒/提示。 |
|
||
| 搜索方式 | 先验证关键词搜索；拼多多原生以图搜图作为后续可选路径。 |
|
||
| 搜索结果 | 最多检查前 5 个可见候选，避免无界遍历。 |
|
||
| 下单边界 | MVP 停在候选或订单确认页，不提交订单、不支付。 |
|
||
| 账号边界 | 验证版为单管理身份 + 设备身份；完整人员 RBAC 后置。 |
|
||
| 第一层任务输入 | 从本机私有蝦皮订单文件生成测试任务，不先建设 Go-Gin。 |
|
||
|
||
## 九、待确认与风险
|
||
|
||
- Roubao 上游仓库、许可证和远端构建版本已核实；源码导入、分支选择和本机构建仍由
|
||
`T-001` 完成。
|
||
- 首份蝦皮样本格式已核实；正式私有目录、更多图片类型和一单多 SKU 规则仍需在
|
||
`T-004` 固定。
|
||
- 拼多多版本、页面结构、账号登录状态和测试设备尚未形成可复现基线。
|
||
- VLM 厂商、模型、成本上限、数据留存地区和图片隐私规则待确认。
|
||
- 拼多多平台条款、自动化允许范围和账号风控需要业务方确认；项目不实现绕过措施。
|
||
- 后续若允许提交订单，必须先明确 SKU、收货地址、运费、优惠、发票、金额审批、
|
||
幂等和人工确认规则，并单独更新需求。
|
||
- “最终产品是否自动支付”没有定案，当前明确排除。
|