cmbuyer/docs/02-requirements.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）

详细故事以用户故事清单为准。

功能	用户故事	优先级
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 三道价格闸门：价格只从拼多多 8.17.0 已取证的合并式最终提交面板两个独立角色读取， 金额使用十进制字符串。
  1. 选中目标规格后读取当前 SKU 单价，计算 单价 × 数量，不得超过授权最高总价。
  2. 设置并复核数量后再次核对同一规格，并唯一读取规格面板的目标数量总额；总额不得超过授权 最高总价。多件优惠可能非线性，不用闸门一金额乘数量猜总额，也不要求目标数量总额等于闸门一。
  3. 保持同一稳定面板，再次核对规格和数量，并从唯一结构化精确文本 提交订单 ¥{金额} 读取最终 控件显示金额；它必须与闸门二顶部总额严格相等，且再次不超过授权最高总价。 任一道读不到、有歧义或不通过都停止并转人工，不从详情页、搜索页或其他按钮文字凑价格。Gate3 最终控件金额只承担 Gate3，不得用于 Gate1/Gate2。
• 同一设备会话连续完成上述步骤；不退出商品再等采购服务确认，也不把旧截图或旧页面读数当作 当前提交依据。

提交围栏与资金边界

• F-017：闸门二、闸门三和提交控件唯一均通过后，采购工具把当前验证摘要发给采购服务并申请 提交围栏。服务端原子复核任务版本、一次性授权未消费、领取身份、规格、数量、闸门值和唯一性， 创建或重放唯一 order_submission，才返回 click_permitted=true。
• 围栏申请失败、冲突、超时、断网或响应不明确时不得点击。围栏成功后只可精确点击一次 “提交订单”；点击后无论结果、超时、外部支付交接或安全校验都禁止重试。
• 明确创建订单后任务转 WAITING_PAYMENT；结果不明确转 RECONCILIATION_REQUIRED，授权和围栏 保持占用，只能调和同一提交记录。
• 围栏建立前，授权过期、设备失败或人工放弃可使任务回到 DRAFT；必须由管理员重新点击“开始采购” 产生新授权。围栏建立后不得释放、重新授权、重新领取或再次点击。
• 系统任何路径都不点击支付、免密支付、先用后付或扣款控件；提交订单后的代码路径不含支付动作。
• 发布真实下单能力前必须用独立真机任务完成只读 dry-run：在合并式最终提交面板验证规格、数量、 Gate2 顶部总额、Gate3 最终控件金额和最近可点击祖先唯一但不点击。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 版本；不能从前序项目或旧版本推断。
• 资金风险：管理员点击开始采购会授权创建真实待付款订单。按钮必须明确影响范围与最高总额， 服务端一次性授权、提交围栏和点击一次共同防止重复订单；付款始终人工。
• 单趟时效风险：授权到实际执行之间价格可能变化。任务不锁定旧观察价，而是在同一趟内读取 Gate1 单价、Gate2 顶部总额和 Gate3 最终控件金额；后两者不一致或任一歧义都停止。
• 账号与风控风险：固定机器节奏可能触发平台风控。轮询和动作间隔需可配置，检测到验证码、短信、 人脸或风险校验立即停止，不绕过。
• 隐私风险：内部原始截图可能含地址和手机号。只允许受控内部链路；不提取结构化隐私字段，完整 XML 不上传，支付凭据与外部支付页截图禁止进入系统。
• 首次真实提交风险：生产提交能力启用前需独立 dry-run 和明确真机授权；点击后结果不明时只能调和。
• 待确认（移出 MVP）：Excel 表头、ERP 字段映射、AI 模型与预算。