cmpdd/docs/02-requirements.md

需求

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

一、业务现状

项	状态
用户	内部运营同事，需要根据已审核 Excel 中的拼多多商品链接和 SKU 信息批量下单、支付并记录订单号。
数据	输入数据来自运营确认和审核过的固定表头 Excel；输出仍以 Excel 结果文件为主。
现有系统	当前项目尚未实现代码；已确认优先做桌面 GUI + 单 Android 真机的 MVP。
约束	必须使用公司/个人有权限的拼多多账号和 Android 设备；自动支付必须受配置、金额上限和二次校验约束；验证码、风控、人脸、短信等安全校验必须人工接管。

二、用户角色

• 运营同事：导入已审核 Excel、选择任务、启动执行、配置支付模式、查看实时状态、人工接管、获取结果 Excel。
• 开发/维护人员：配置环境、维护页面识别和 SKU 选择规则、排查失败日志。
• 游客 / 未登录用户：不适用。MVP 是本地桌面工具，不提供公开访问。

三、功能清单

第一版 MVP（最小闭环）

功能	用户能做什么	优先级
导入 Excel	选择固定表头 Excel 文件，系统读取商品链接、SKU、数量等任务信息。	P0
任务列表展示	在 GUI 中查看任务列表、状态、订单号、失败原因，并勾选需要执行的任务。	P0
顺序执行任务	点击开始后，按 GUI 中选中任务的顺序逐条控制 Android 真机执行。	P0
商品链接跳转	系统打开商品链接并跳转到拼多多 App 商品详情页。	P0
SKU 选择	系统根据 Excel 中的 SKU 信息选择商品规格和数量。	P0
支付控制	默认到支付确认页暂停；开启受控自动支付后，在二次校验通过且未触发安全校验时继续支付。	P0
订单号记录	成功后在 GUI 展示订单号，并写入 Excel 结果文件。	P0
失败记录	失败时展示失败原因，写入 Excel，并保留截图/日志线索。	P0

后续迭代

功能	描述	阶段
多设备管理	同一电脑连接多台 Android 手机并调度任务。	V2
OCR 兜底	UI XML 无法识别时使用 OCR 辅助识别文本。	V2
任务数据库	将任务、日志和结果保存到 SQLite 或服务端数据库。	V2
Web 后台	多人、多设备、集中管理和远程查看。	V3
报表分析	按商品、SKU、失败原因、执行效率统计。	V3

四、核心用户故事（MVP）

1. 作为运营同事，我打开桌面程序后能导入一份固定表头 Excel。
2. 我可以在 GUI 表格中查看每条商品任务，勾选需要执行的任务，并按当前排序执行。
3. 我点击开始后，系统控制已连接的 Android 真机打开商品链接、进入拼多多 App、选择指定 SKU。
4. 当系统进入支付确认页时，默认暂停等待我确认；如果我已开启受控自动支付，系统会先校验商品、SKU、数量、地址和金额，再继续支付。
5. 当系统遇到验证码、风控、登录过期、人脸、短信等情况时，系统暂停并提示我人工接管。
6. 支付完成后，系统继续读取订单号，并在 GUI 和 Excel 结果文件中记录。
7. 当任务失败时，系统不会静默跳过，而是记录明确失败原因，保留截图或页面 XML 线索。

五、验收标准（MVP）

• 导入 Excel：选择符合固定表头的 Excel 后，GUI 表格应展示所有有效任务；缺少必填列时给出明确错误。
• 任务列表展示：每条任务至少显示序号、商品链接、SKU 信息、数量、状态、订单号、失败原因。
• 顺序执行任务：点击开始后，只执行勾选任务，并按 GUI 中的顺序逐条处理；当前任务执行完或失败后再进入下一条。
• 商品链接跳转：能在 Android 真机上打开输入商品链接，并进入拼多多 App 对应商品页或给出失败原因。
• SKU 选择：能根据 Excel 中的 SKU 文本匹配并选中对应规格；匹配失败时暂停或失败记录，不随意选择近似项。
• 支付控制：默认到支付确认页暂停；开启受控自动支付时，必须先通过商品标题、SKU、数量、地址、实付金额校验，并满足单笔/批次金额上限。
• 安全校验人工接管：验证码、风控、人脸、短信等节点必须暂停，不自动绕过。
• 订单号记录：成功下单后，GUI 中对应行展示订单号，Excel 结果文件中同一任务行写入订单号、状态、执行时间。
• 失败记录：失败任务写入失败原因，并保存至少一张失败时截图；批量执行是否继续由配置或按钮控制。
• 原始文件保护：默认不覆盖原始 Excel，生成带 _执行结果 后缀的结果文件。

六、范围边界与决策

问题	决策
第一版平台	Windows 桌面 GUI。
是否需要账号	工具本身不做账号系统；拼多多账号需提前在 Android 真机登录。
第一版设备	单 Android 真机，通过 USB/ADB 连接。
第一版范围	Excel 批量任务导入、GUI 展示、自动下单、默认人工确认支付、受控自动支付开关、订单号/失败原因回写。
暂不支持	多设备并发、Web 后台、数据库、自动绕过风控、无配置/无校验/无金额上限的自动支付。

七、待确认 / 风险点

• 真实 Excel 表头：需要用户提供最终固定表头样例；没有样例前只能按文档建议字段实现。
• 拼多多页面变化：App 页面、按钮文本、SKU 弹窗结构可能频繁变化；必须先做真机原型验证。
• SKU 匹配歧义：同名规格、套餐文案、缺货状态可能导致误选；MVP 要求匹配失败即暂停/失败，不盲点。
• 支付和安全校验：自动支付涉及真实资金，必须配置金额上限和二次校验；安全校验必须人工接管。
• 订单号读取位置：需要在真机上确认支付后订单详情页的可读取文本位置。
• 平台规则与合规风险：对第三方 App（拼多多）做 UI 自动化批量下单，本身可能触及平台用户协议对自动化/批量操作的限制，并存在账号风控的业务风险。本工具仅在合规运营场景下、使用公司或个人有权限的账号与设备运行，且严格不绕过验证码、风控、人脸、短信等安全校验（见 01-vision.md 非目标与 05-coding-rules.md 安全纪律）。是否使用、使用范围与账号风险由业务方评估承担；此处仅作为已知风险留痕，不在 MVP 内提供任何规避平台限制的能力。