cmbuyer/docs/02-requirements.md

# 需求

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

## 一、业务现状

| 项 | 状态 |
| --- | --- |
| 用户 | 采购人员为履约外部订单，逐条手工在拼多多找同款、选颜色尺码、下单、抄回订单号 |
| 任务来源 | 第三方 ERP（顺运宝）货运单与商品明细为主；Excel 批量导入和手工填链接为补充 |
| 数据 | ERP 提供商品标题、规格、数量、参考图；部分明细带拼多多链接，部分只有图 |
| 现有系统 | 两个前序原型（见 [愿景](01-vision.md) 第六节），代码不直接复用 |
| 设备 | 一台 Windows 电脑 + 一台已登录拼多多的 Android 手机，USB 或 WiFi ADB 连接 |
| 约束 | 不得绕过平台风控；付款必须人工；手机需保持亮屏解锁 |

## 二、用户角色

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

## 三、功能清单

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

MVP 只做**任务自带商品链接**的情形，分两趟执行：第一趟试选并回传，人确认后第二趟下单。
流程见[架构设计](04-architecture.md)第三节。

| ID | 功能 | 用户能做什么 | 优先级 | 关联用户故事 |
| --- | --- | --- | --- | --- |
| F-001 | 手工建单 | 管理员在任务列表内填写任务名称、拼多多链接、颜色分类、尺码、数量、价格上限，保存一条待开始任务 | P0 | US-001 |
| F-004 | 任务查询 | 管理员按关键词、状态、时间范围找到目标任务 | P0 | US-002 |
| F-005 | 桌面端定时领取 | 执行员启动会话后，桌面端定时轮询领取待试选和已授权两类任务 | P0 | US-003 |
| F-006 | 第一趟试选 | 系统打开商品、按维度精确勾选颜色分类和尺码、读单价、截图后退出 | P0 | US-003 |
| F-007 | 试选结果回传 | 管理员看到机器实际选中的规格、单价、合计和规格面板截图 | P0 | US-004 |
| F-008 | 人工确认与授权 | 管理员确认机器选对了，签发一次性授权并锁定价格；或退回不买 | P0 | US-004、US-005 |
| F-009 | 第二趟下单 | 系统重新选同一规格、过三道价格闸门后提交订单，回传订单截图 | P0 | US-005 |
| F-010 | 授权超时与放弃 | 管理员在授权卡住时能放弃并重新确认，任务不会被永久锁死 | P0 | US-005 |
| F-011 | 结果与失败分类回传 | 管理员看到成功、失败、已取消、待人工，以及可区分的失败原因和证据 | P0 | US-002、US-008 |
| F-013 | 登录与身份隔离 | 管理员用账号登录网页端；桌面端用设备凭据接入，两者权限不互通 | P0 | US-007 |
| F-017 | 下单 dry-run、提交围栏与调和 | 真机先只读演练到订单确认页；真实点击前由服务端原子冻结授权；点击后只调和结果、绝不重试 | P0 | US-005、US-008 |
| F-018 | 批量开始试选 | 管理员勾选一条或多条待开始任务，统一放入第一趟试选队列 | P0 | US-010 |

> F-002、F-003、F-012 已移出 MVP，编号保留不重用，见下表。

### 后续迭代

| 功能 | 描述 | 阶段 |
| --- | --- | --- |
| F-002 Excel 批量建单 | 上传固定表头表格批量生成任务 | V2，被表头契约待确认阻塞 |
| F-003 从 ERP 货运明细建单 | 同步顺运宝货运单后复核生成任务 | V2，被字段映射待确认阻塞 |
| F-012 批量顺序编排与人工接管 | 对已开始任务排序、暂停继续、运行中接管 | V2；MVP 仅支持批量开始试选，实际执行仍由定时轮询领取 |
| F-014 图片搜索路径（B 路径） | 任务只有参考图时搜图产出 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)为准；本文只维护功能、优先级与 US 编号的
索引，避免两处成为相互冲突的权威来源。

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

US-006（付款前核对）在 MVP 降级为：系统展示订单截图与授权信息，人在拼多多自行核对
后付款并手工标记完成。自动回读核对是 F-016（V2）。US-009（ERP 建单）随 F-003 移出 MVP。

## 五、验收标准（MVP）

### 建单

- **F-001**：在任务列表点击创建，填入任务名称、合法拼多多链接、颜色分类、尺码、数量、
  价格上限后保存，返回任务编号；弹窗关闭，任务按创建时间倒序出现在第一行且状态为待开始。
  链接格式非法或无法解析出 `goods_id` 时明确报错并保留已填内容。
- **F-018**：列表只允许勾选待开始任务；全选只覆盖当前筛选结果中可开始的任务。点击
  「开始试选」后，被选任务原子转为待领取，并明确提示这只是进入第一趟试选队列，
  **不签发下单授权、不创建订单、不付款**。任一任务状态已变化时整批不提交，刷新后重选。

### 第一趟：试选

- **F-005**：执行员启动会话后桌面端定时轮询，同时领取待试选与已授权两类任务。
  两个实例并发领取同一条时只有一个成功，另一个得到明确的「无可领任务」而不是报错。
  **关闭会话即停止轮询；连续失败达到阈值自动停止并提示原因。**
- **F-006**：手机打开对应商品详情页，只点击与当前拼多多版本及本项目真机证据绑定的精确唯一
  **受控规格面板入口**，打开规格面板后按维度精确匹配颜色分类和尺码。当前只确认拼多多
  `8.17.0`、goods_id `937122477375` 上的“快要抢光”；其他入口文案必须分别取证，不能按购买
  语义泛化。
  **任一维度找不到精确值即停止并转人工，不选相近选项。** 勾选后读取该 SKU 单价
  （闸门一），读不到即转人工，**不用商品详情页正文或搜索页的数字凑合**。
- **F-006 释放要求**：试选完成后**必须退出商品页释放手机**，不得停在规格面板等待人工。
- **F-006 硬边界**：第一趟只把上述精确入口点击视为可逆的“打开规格面板”能力；进入面板后
  不得调整数量、进入订单确认页、点击“提交订单”或任何支付/资金控件，也不得暴露通用任意点击能力。
  必须有静态调用链和测试证明上述下单语义动作不可达。入口缺失、重复、版本失配或打开后不是已取证
  面板时立即停止，不尝试“免拼购买 / 单独购买 / 直接拼成”等相似文案。
- **F-007**：回传商品标题、实际勾选到的颜色分类与尺码、单价、合计（单价 × 数量）和
  **自动脱敏后的**规格面板截图；任务转「等你确认」。原始 screenshot/XML 只能留在采购工具本机
  隔离目录，不能上传、写日志或提交 Git。

### 决策与资金

- **F-008**：管理员在确认页看到需求与机器所选的对照、单价、合计和截图，点击确认后
  签发一次性授权，**授权锁定当次试选的单价**。授权重复提交幂等，不产生第二笔订单。
  管理员也可选择「退回，不买」，任务终止。
- **F-009 三道闸门**：第二趟重新打开商品并重新勾选同一规格后，
  ① 重读单价必须与授权锁定价一致；
  ② 数量设置后读回必须精确等于要求值；
  ③ 订单确认页「实付款」不得超过授权总额上限。
  **任一道不通过即停止并转人工。**
- **F-009 提交条件**：授权存在且未消费、闸门全过、「提交订单」控件文本精确相等且可
  点击祖先唯一——四者同时满足，且服务端已原子建立提交围栏，才允许**点击一次**。点击后
  无论超时、跳外部支付还是遇到安全校验，**一律进入结果调和或人工核查且禁止重试**。
- **F-010**：授权带过期时间。建立提交围栏前，超时或主动放弃都会作废授权并让任务进入
  「待重新试选」，不得直接复用旧试选再次确认；建立提交围栏后，授权不得过期或放弃，
  只能调和结果或转人工核查。**任何状态都必须给出安全且可执行的下一步。**
- **F-017 dry-run**：首次真实下单前必须先完成一次只读演练：到订单确认页读取规格、数量、
  「实付款」，验证提交控件唯一，然后停止并退出；**不点击「提交订单」**。演练结果与证据
  必须回传，真实提交不得把旧演练当成当前页面事实。
- **F-017 提交围栏**：desk 端在真实点击前向 web 端申请提交围栏；web 端必须在一个原子
  事务中复核任务版本、授权未消费、命令与演练关联正确，然后冻结授权并生成唯一
  `order_submission`。申请失败或响应不明确时不得点击。围栏成功后只能点击一次；点击结果
  不明确时保留金额额度并进入调和，不能重新申请或重新点击。
- **资金硬边界**：系统在任何路径下都不点击支付、免密支付、先用后付或任何扣款控件。
  必须有测试证明提交订单之后不调用任何支付动作。

### 结果与异常

- **F-011**：失败必须可区分至少这些原因：设备未连接、商品页打不开、规格面板打不开、
  规格不匹配、单价读不到、单价与授权价不符、数量设置失败、金额超上限、提交控件不唯一、
  页面识别失败、安全校验、外部支付交接、超时。原始截图/页面快照只留采购工具本机隔离目录；
  脱敏成功时保留派生物，任何上传、远程审阅或服务端展示都只能使用自动复检通过的派生证据。
- **版本失配**：运行时读取到的拼多多 App 版本与当前已取证版本不一致时，桌面端必须停止
  领取真机任务并提示重新取证；不得继续使用旧页面判据。
- **付款收口（MVP 简化版）**：订单创建后任务转「待付款」，页面展示订单截图、商品、
  规格、数量和授权金额供人核对。**人在拼多多付款后手工标记完成。** 自动回读核对是
  F-016（V2）。

### 通用

- 每条 P0 判据关联至少一个 US 编号；有用户界面的判据同时关联相关 IX 编号。
- 任务终态一次原子回写，中间态不落盘产生「看起来在跑其实已死」的记录。

## 六、范围边界与决策

| 问题 | 决策 |
| --- | --- |
| 第一版平台 | 网页端（管理）+ Windows 桌面端（执行），驱动一台 Android 手机 |
| 是否需要账号 | 是。管理员账号 + 桌面端设备凭据，两套身份分离 |
| 第一版范围 | 手工建单 → 批量开始试选 → 定时领取 → **第一趟试选** → 人工确认 → dry-run / 提交围栏 → **第二趟下单** → 待付款 |
| 任务来源 | **仅手工填链接。** Excel 与 ERP 移出 MVP |
| 找货方式 | **仅按链接。** 图片搜索移出 MVP |
| 采购平台 | 仅拼多多 |
| 领取方式 | 定时轮询，只在执行员启动的会话内运行 |
| 任务启动 | 创建后为待开始；管理员在列表勾选一条或多条并统一开始第一趟试选 |
| 设备连接 | ADB over USB 或 WiFi 均支持；同一台手机不得同时以两种方式在线 |
| 付款收口 | 系统展示订单截图，人核对后付款并手工标记完成 |
| 暂不支持 | 自动付款、图搜、Excel、ERP、多设备并行、多平台、退款、审批链、AI 辅助 |

## 七、待确认 / 风险点

- **第三方平台风险**：拼多多 App 版本更新会改变页面结构。前序项目已观察到详情页
  没有独立规格入口、价格文本被拆成多个节点等变化。**每次页面结构判据都必须有真机
  证据，不得从旧版本推断。**
- **资金风险**：涉及创建真实待付款订单。授权、金额上限、一次性围栏的规则由采购管理员
  确认；付款始终人工。**下单动作在真机上第一次验证前，必须先取得授权。**
- **账号风险**：手机上是真实拼多多账号。频繁自动化操作有被风控或封号的可能，需要
  可配置的动作节奏，并在检测到安全校验时立即停止。
- **自动化边界风险**：会自动点击并创建订单，属不可逆操作。必须支持 dry-run（跑到
  订单确认页停止）、服务端提交围栏和点击后调和；任一环节状态不明都不得继续点击。
- **隐私风险**：规格面板和订单确认页都会显示收货地址和掩码手机号。允许原始 screenshot/XML
  仅在采购工具本机隔离目录短链路落盘供确定性脱敏器消费；业务逻辑、日志、agent、fixture 与采购
  服务**不得提取或接收地址原文、手机号或支付凭据**。只有脱敏成功且自动复检通过的派生证据才能
  上传或进入开发材料，无法确认脱敏完整即 fail closed。
- **受控规格入口风险**：T-103 已证明当前衣服商品只有购买语义按钮能打开规格面板。项目所有者批准
  仅把经真机取证的精确唯一入口作为第一趟可逆导航；该批准不覆盖其他文案，不授权调整数量、提交订单、
  进入确认页或付款。T-103 必须用 capability 隔离和不可达测试证明边界没有扩散。
- **规格面板上的单价位置未取证（阻塞 F-006 闸门一）**：选中 SKU 后价格显示在哪个节点、
  是否带「券后」前缀、是否与原价并列，尚无本项目的真机证据。**T-103 必须一并取证。**
  若规格面板上无法可靠读到单价，闸门一要改为「只截图不判价」，确认页设计随之调整。
- **两趟之间的状态漂移**：第二趟重新进入时价格可能已变、规格选项可能已改、商品可能
  下架。闸门二负责拦截，一律转人工——但这意味着价格波动频繁的类目会产生大量待人工。
  需真机观察实际发生率。
- **定时轮询的节奏**：固定间隔的机器节奏比人工节奏更容易被风控识别。间隔需可配置，
  并在检测到安全校验时立即停止轮询。具体间隔待真机观察后确定。
- **待确认（阻塞 F-002，已移出 MVP）**：Excel 表头契约的最终字段集与列名。
- **待确认（阻塞 F-003，已移出 MVP）**：ERP 货运明细到任务颜色 / 尺码的字段映射。
- **待确认（V2 之后）**：AI 辅助的模型供应商、调用预算与失败降级策略。