cmbuyer/docs/02-requirements.md

# 需求

> 本文只描述**要什么**与**怎么算达成**，用产品 / 用户语言表达。技术方案、数据结构与
> 字段定义见[架构设计](04-architecture.md)。

## 一、业务现状

| 项 | 状态 |
| --- | --- |
| 用户 | 采购人员为履约外部订单，逐条手工在拼多多找同款、选颜色尺码、下单、抄回订单号 |
| MVP 任务来源 | 管理员手工填写拼多多商品链接、规格、数量和金额上限 |
| 后续任务来源 | Excel 与第三方 ERP（顺运宝）货运明细 |
| 设备 | 一台 Windows 电脑 + 一台已登录拼多多的 Android 手机，USB 或 WiFi ADB 连接 |
| 约束 | 不绕过平台风控；系统只创建待付款订单；付款必须由人完成；手机保持亮屏解锁 |

## 二、用户角色

- **采购管理员**：在采购服务建单、查询、点击“开始采购”签发一次性采购授权、查看审计记录。
- **采购执行员**：在采购工具连接设备、启动轮询、处理待人工任务、在拼多多完成人工付款。
- **ERP 对接身份**：只读同步货运单与商品明细，不能建单、授权或访问采购结果。
- **设备身份**：一台已授权采购工具实例，用于领取已授权任务和回传结果，不能建单或授权。
- **未登录用户**：不能访问任何任务、图片、证据或设备接口。

## 三、功能清单

### 第一版 MVP（最小闭环）

MVP 只做**任务自带商品链接**的情形。管理员点击“开始采购”后，采购工具在同一次设备会话中
完成选规格、校验价格与数量、创建待付款订单；中间不再回到采购服务等待“机器选对了吗”。

| ID | 功能 | 用户能做什么 | 优先级 | 关联用户故事 |
| --- | --- | --- | --- | --- |
| F-001 | 手工建单 | 填写标题、拼多多链接、颜色分类、尺码、数量、最高总价，保存为待开始任务 | P0 | US-001 |
| F-004 | 任务查询 | 按标题关键词、状态、时间范围找到任务，双击行查看详情 | P0 | US-002 |
| F-005 | 桌面端定时领取 | 执行员启动会话后定时领取已获采购授权的任务 | P0 | US-003 |
| F-006 | 单趟采购执行 | 打开商品、精确选择规格、校验价格、设置数量、进入确认页并创建待付款订单 | P0 | US-003、US-005 |
| F-007 | 执行证据回传 | 管理员查看实际规格、三道闸门、原始页面截图和步骤记录 | P0 | US-002、US-008 |
| F-008 | 开始采购授权 | 管理员批量点击一次，原子锁定每条任务并签发一次性待付款订单授权 | P0 | US-005、US-010 |
| F-010 | 围栏前过期与重新授权 | 未建立提交围栏的失败或过期任务回到待开始，可由管理员重新点击开始采购 | P0 | US-005 |
| F-011 | 结果与失败分类回传 | 查看成功、失败、已取消、待人工及可诊断原因和证据 | P0 | US-002、US-008 |
| F-013 | 登录与身份隔离 | 管理员用账号登录；采购工具用设备凭据接入，权限不互通 | P0 | US-007 |
| F-017 | 提交围栏与调和 | 真机点击前服务端原子冻结授权；点击后只调和同一提交，绝不重试 | P0 | US-005、US-008 |
| F-018 | 批量开始采购 | 勾选一条或多条待开始任务，统一授权采购工具创建待付款订单 | P0 | US-010 |

> 原 F-009 的“两趟下单”并入 F-006；F-002、F-003、F-012 移出 MVP，编号不重用。

### 后续迭代

| 功能 | 描述 | 阶段 |
| --- | --- | --- |
| F-002 Excel 批量建单 | 上传固定表头表格批量生成任务 | V2，被表头契约待确认阻塞 |
| F-003 从 ERP 货运明细建单 | 同步顺运宝货运单后复核生成任务 | V2，被字段映射待确认阻塞 |
| F-012 批量编排与运行中接管 | 排序、暂停继续、运行中接管 | V2；MVP 只批量授权，设备逐条领取 |
| F-014 图片搜索路径 | 任务只有参考图时搜图产出 goods_id 候选 | V2 |
| F-015 候选对照台 | 多个候选并排对照挑选 | V2，随 F-014 |
| F-016 订单自动核对回读 | 付款后只读读取订单页做唯一匹配并回写 | V2；MVP 用截图 + 人眼核对 |
| F-101 AI 辅助候选判断 | 用模型看搜索结果页截图判断同款 | V2 之后 |
| F-102 AI 辅助页面理解 | 规则读不到规格或价格时用模型兜底 | V2 之后 |
| F-103 执行轨迹本地留档 | 记录模型输入输出与规则判断分歧 | V2 之后 |
| F-104 多设备并行 | 一个采购工具驱动多台手机 | V2 之后 |
| F-105 完整 RBAC | 管理员、执行员、审核员细粒度权限 | V2 之后 |
| F-106 多平台比价 | 淘宝、1688、京东 | V3 |
| 支付自动化 | **不在规划内** | 未规划 |

## 四、核心用户故事（MVP）

详细故事以[用户故事清单](07-user-stories.md)为准。

| 功能 | 用户故事 | 优先级 |
| --- | --- | --- |
| F-001 | US-001 | P0 |
| F-004、F-007、F-011 | US-002 | P0 |
| F-005、F-006 | US-003 | P0 |
| F-008、F-010、F-017 | US-005 | P0 |
| F-013 | US-007 | P0 |
| F-007、F-011、F-017 | US-008 | P0 |
| F-008、F-018 | US-010 | P0 |

US-004 的试选后人工确认已从 MVP 删除。US-006 在 MVP 为：系统展示订单截图与授权信息，
人在拼多多核对、付款并手工标记完成；自动回读核对是 F-016（V2）。

## 五、验收标准（MVP）

### 建单与授权

- **F-001**：任务列表点击创建，填入标题、合法拼多多链接、颜色分类、尺码、数量和最高总价后
  保存，弹窗关闭；新任务按创建时间倒序出现在第一行，状态为 `DRAFT`。非法链接或无法解析
  `goods_id` 时明确报错并保留输入。
- 创建任务**不构成采购授权**，设备不能领取 `DRAFT`。
- **F-018**：只允许勾选当前筛选结果中的 `DRAFT`。点击“开始采购（只创建待付款订单）”前，
  界面显示已选数量和最高总额；点击本身即管理员明确授权，不再增加选品确认步骤。
- 服务端在一个事务中校验整批任务仍为预期版本，逐条锁定 `goods_id`、颜色、尺码、数量、最高
  总价、授权人和有效期，并把任务转 `PENDING`。任一条冲突时整批不变，刷新后重选。
- 相同 `start_key` 重放返回同一结果；不得产生第二份有效授权。成功后即时提示“已授权 N 条，
  采购工具只会创建待付款订单，不会付款”。

### 单趟采购执行

- **F-005**：采购工具只领取 `PENDING` 且授权有效的任务。并发领取同一条时只有一个成功；关闭
  会话即停止轮询，连续失败达到阈值自动停止并显示原因。
- **F-006 受控入口**：只点击与本项目真机证据及 App 版本绑定的精确唯一规格面板入口。当前仅确认
  拼多多 `8.17.0`、goods_id `937122477375` 的“快要抢光”；其他入口必须分别取证，不按购买语义泛化。
- **F-006 规格与数量**：颜色分类、尺码必须在各自维度内精确唯一匹配并读回；数量设置后必须读回
  等于任务值。缺失、重复、禁用、前缀碰撞、读回不一致都停止，不选相近项。
- **F-006 三道价格闸门**：价格只从规格面板和订单确认页读取，金额使用十进制字符串。
  1. 选中目标规格后读取当前 SKU 单价，计算 `单价 × 数量`，不得超过授权最高总价。
  2. 设置并复核数量后再次读取同一规格与单价；规格必须仍相同，单价必须与闸门一完全相等。
  3. 订单确认页核对规格、数量与应付总额；总额不得超过授权最高总价。
  任一道读不到、有歧义或不通过都停止并转人工，不从详情页、搜索页或按钮文字凑价格。
- 同一设备会话连续完成上述步骤；不退出商品再等采购服务确认，也不把旧截图或旧页面读数当作
  当前提交依据。

### 提交围栏与资金边界

- **F-017**：闸门二、闸门三和提交控件唯一均通过后，采购工具把当前验证摘要发给采购服务并申请
  提交围栏。服务端原子复核任务版本、一次性授权未消费、领取身份、规格、数量、闸门值和唯一性，
  创建或重放唯一 `order_submission`，才返回 `click_permitted=true`。
- 围栏申请失败、冲突、超时、断网或响应不明确时**不得点击**。围栏成功后只可精确点击一次
  “提交订单”；点击后无论结果、超时、外部支付交接或安全校验都禁止重试。
- 明确创建订单后任务转 `WAITING_PAYMENT`；结果不明确转 `RECONCILIATION_REQUIRED`，授权和围栏
  保持占用，只能调和同一提交记录。
- 围栏建立前，授权过期、设备失败或人工放弃可使任务回到 `DRAFT`；必须由管理员重新点击“开始采购”
  产生新授权。围栏建立后不得释放、重新授权、重新领取或再次点击。
- 系统任何路径都不点击支付、免密支付、先用后付或扣款控件；提交订单后的代码路径不含支付动作。
- 发布真实下单能力前必须用独立真机任务完成只读 dry-run：到订单确认页验证规格、数量、金额和提交
  控件唯一但不点击。dry-run 是版本发布门禁，不是每笔订单的第一趟，也不能代替实时三道闸门。

### 结果、证据与异常

- **F-007**：按步骤回传实际规格、两次规格面板价格、数量读回、确认页总额、判定、时间和截图。
  截图是内部审计证据，不是提交前审批前置。
- 内部系统允许上传规格面板与订单确认页的原始截图，截图中可保留页面已显示的地址和手机号；只允许
  已认证设备显式上传、已登录管理员查看。完整 XML 只留采购工具本机，不上传；地址/手机号不解析为
  业务字段或日志；外部支付页、支付凭据永不上传。
- **F-011**：至少区分设备未连接、版本失配、商品打不开、面板打不开、规格不匹配、价格不可读、
  两次价格不一致、数量复核失败、金额超上限、确认页不一致、提交控件不唯一、围栏失败、页面识别
  失败、安全校验、外部支付交接和超时。
- 运行时拼多多 App 版本与已取证版本不一致时停止领取真机任务，提示重新取证。
- 订单明确创建后展示截图、商品、规格、数量和授权金额；人在拼多多付款后手工标记完成。
  **待付款不等于采购完成。**

### 通用

- 每条 P0 判据关联至少一个 US；有用户界面的判据同时关联 IX。
- 状态流转与提交记录原子落盘，不产生“界面在跑但服务端无记录”的悬空事实。
- 失败页面给出可执行下一步；不会把“重试”显示在已建立围栏的提交上。

## 六、范围边界与决策

| 问题 | 决策 |
| --- | --- |
| 第一版平台 | 采购服务（网页端）+ 采购工具（Windows 桌面端）+ 一台 Android 手机 |
| 身份 | 管理员账号 + 设备凭据，两套身份分离 |
| 第一版流程 | 手工建单 → 批量开始采购并授权 → 定时领取 → 单趟选规格 / 三闸门 / 围栏 / 提交一次 → 待付款 |
| 人工授权点 | 管理员点击“开始采购（只创建待付款订单）”；不再有试选后确认 |
| 任务来源 | 仅手工填链接；Excel 与 ERP 移出 MVP |
| 找货方式 | 仅按链接；图片搜索移出 MVP |
| 采购平台 | 仅拼多多 |
| 领取方式 | 定时轮询，只在执行员启动的会话内运行 |
| 设备连接 | ADB over USB 或 WiFi；同一手机不得以两种方式同时在线 |
| 付款收口 | 系统展示待付款订单证据，人核对、付款并手工标记完成 |
| 暂不支持 | 自动付款、图搜、Excel、ERP、多设备并行、多平台、退款、审批链、AI 辅助 |

## 七、待确认 / 风险点

- **第三方平台风险**：拼多多更新会改变页面结构。页面判据必须来自本项目真机证据，并绑定 App
  版本；不能从前序项目或旧版本推断。
- **资金风险**：管理员点击开始采购会授权创建真实待付款订单。按钮必须明确影响范围与最高总额，
  服务端一次性授权、提交围栏和点击一次共同防止重复订单；付款始终人工。
- **单趟时效风险**：授权到实际执行之间价格可能变化。任务不锁定旧观察价，而是在同一趟内两次读取
  规格面板价格并在确认页校验总额；任何变化或歧义都停止。
- **账号与风控风险**：固定机器节奏可能触发平台风控。轮询和动作间隔需可配置，检测到验证码、短信、
  人脸或风险校验立即停止，不绕过。
- **隐私风险**：内部原始截图可能含地址和手机号。只允许受控内部链路；不提取结构化隐私字段，完整
  XML 不上传，支付凭据与外部支付页截图禁止进入系统。
- **首次真实提交风险**：生产提交能力启用前需独立 dry-run 和明确真机授权；点击后结果不明时只能调和。
- **待确认（移出 MVP）**：Excel 表头、ERP 字段映射、AI 模型与预算。