chengma/cmpdd
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 初始化项目文档集与一致性补丁

Browse Source 
建立 harness coding 文档体系并完成一致性修正：

- 文档集：AGENTS.md/CLAUDE.md 入口，docs/00-05 规范文档，
  api.md/routes.md/current-state.md，根目录 tasks.md/progress.md。
- 一致性补丁：TaskStatus 中英映射、支付模式收敛为全局 PaymentConfig、
  执行器级 RunnerState 暂停语义、progress 与 current-state 职责边界。
- 工程地基：新增 .gitignore，忽略运行产物/敏感数据与 .claude 本地设置。
- 合规留痕：02 需求新增平台规则与合规风险条目。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
chengma
2026-06-24 16:15:46 +08:00
co-authored by Claude Opus 4.8
commit 541dfab967
15 changed files with 1487 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/02-requirements.md
+88
View File
@@ -0,0 +1,88 @@
# 需求
> 本文只描述**要什么**与**怎么算达成**，用产品 / 用户语言表达，**不涉及技术实现**。
> 技术方案、数据结构、字段定义见 [架构设计](04-architecture.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`](01-vision.md) 非目标与 [`05-coding-rules.md`](05-coding-rules.md) 安全纪律）。是否使用、使用范围与账号风险由业务方评估承担；此处仅作为已知风险留痕，不在 MVP 内提供任何规避平台限制的能力。