From 541dfab9676fea650ab188103fc4153fc577fa6a Mon Sep 17 00:00:00 2001 From: chengma Date: Wed, 24 Jun 2026 16:15:46 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=88=9D=E5=A7=8B=E5=8C=96=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E6=96=87=E6=A1=A3=E9=9B=86=E4=B8=8E=E4=B8=80=E8=87=B4?= =?UTF-8?q?=E6=80=A7=E8=A1=A5=E4=B8=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 建立 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 --- .gitignore | 26 +++ AGENTS.md | 99 +++++++++++ CLAUDE.md | 6 + docs/00-ai-start-here.md | 131 ++++++++++++++ docs/01-vision.md | 48 ++++++ docs/02-requirements.md | 88 ++++++++++ docs/03-tech-stack.md | 72 ++++++++ docs/04-architecture.md | 358 +++++++++++++++++++++++++++++++++++++++ docs/05-coding-rules.md | 97 +++++++++++ docs/README.md | 33 ++++ docs/api.md | 198 ++++++++++++++++++++++ docs/current-state.md | 88 ++++++++++ docs/routes.md | 96 +++++++++++ progress.md | 61 +++++++ tasks.md | 86 ++++++++++ 15 files changed, 1487 insertions(+) create mode 100644 .gitignore create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 docs/00-ai-start-here.md create mode 100644 docs/01-vision.md create mode 100644 docs/02-requirements.md create mode 100644 docs/03-tech-stack.md create mode 100644 docs/04-architecture.md create mode 100644 docs/05-coding-rules.md create mode 100644 docs/README.md create mode 100644 docs/api.md create mode 100644 docs/current-state.md create mode 100644 docs/routes.md create mode 100644 progress.md create mode 100644 tasks.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..f4c3981 --- /dev/null +++ b/.gitignore @@ -0,0 +1,26 @@ +# Python +__pycache__/ +*.py[cod] +.venv/ +venv/ +*.egg-info/ +.pytest_cache/ +build/ +dist/ + +# 运行产物与敏感数据（含截图、UI XML、订单信息，禁止提交真实数据） +logs/ +artifacts/ + +# Excel 样例与结果文件（默认不提交真实数据；脱敏样例需显式 git add -f） +samples/*.xlsx +*_执行结果.xlsx + +# IDE / OS +.idea/ +.vscode/ +.DS_Store +Thumbs.db + +# Claude Code 本地设置（不提交本地/敏感配置） +.claude/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3ecb6a3 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,99 @@ +# AGENTS.md + +> 本文件是 Codex / AI coding agent 进入本项目时的仓库级入口。开始任何编码、改文档或执行任务前，先读本文件。 + +## 项目定位 + +本项目是一个内部运营使用的拼多多批量下单执行器。 + +第一版目标： + +- 从固定表头 Excel 导入已审核的商品下单任务。 +- 在 Windows 桌面 GUI 中展示、勾选并按顺序执行任务。 +- 通过 `uiautomator2 + ADB` 控制一台 Android 真机操作拼多多 App。 +- 自动选择商品 SKU、数量并进入下单流程。 +- 默认支付前人工确认；预留受控自动支付开关。 +- 成功后读取订单号，失败时记录原因，并回写 Excel 结果文件。 + +## 必读顺序 + +每次开始工作前按顺序读取： + +1. [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md)：项目入口、MVP 边界、任务规则。 +2. [`docs/01-vision.md`](docs/01-vision.md)：项目愿景、目标用户、非目标。 +3. [`docs/02-requirements.md`](docs/02-requirements.md)：需求与验收标准。 +4. [`docs/03-tech-stack.md`](docs/03-tech-stack.md)：技术选型和运行方式。 +5. [`docs/04-architecture.md`](docs/04-architecture.md)：架构、模块职责、数据模型。 +6. [`docs/05-coding-rules.md`](docs/05-coding-rules.md)：编码规则和安全边界。 +7. [`tasks.md`](tasks.md)：任务定义、依赖、验收标准。 +8. [`progress.md`](progress.md)：历史执行记录、验证结果、阻塞点。 +9. [`docs/current-state.md`](docs/current-state.md)：当前仓库现实、运行命令、下一步入口。 + +涉及界面时再读 [`docs/routes.md`](docs/routes.md)。 +涉及本地模块接口时再读 [`docs/api.md`](docs/api.md)。 + +## 任务规则 + +- 每轮只领取 `tasks.md` 中第一个状态为 `TODO` 且依赖均为 `DONE` 的任务。 +- 开始前把该任务状态改为 `DOING`。 +- 本轮只完成这一个任务，不顺手做后续任务。 +- 验收通过后把任务状态改为 `DONE`。 +- 完成后更新： + - `progress.md`：记录做了什么、验证命令、结果、阻塞点。 + - `docs/current-state.md`：同步当前代码结构、可运行命令、下一步入口。 +- 如果任务、代码现实、需求文档冲突，先说明冲突，不要擅自跳步或重排任务。 + +## 技术边界 + +既定 MVP 技术路线： + +- Python 3.x +- PySide6 桌面 GUI +- `openpyxl` 读取和回写 Excel +- `uiautomator2 + ADB` 控制 Android 真机 +- 本地文件日志、截图、UI XML 归档 +- 暂不引入 Web 后台、数据库、多设备调度 + +新增依赖前必须说明用途、替代方案和维护成本，并同步更新 `docs/03-tech-stack.md`。 + +## 安全与合规边界 + +允许做： + +- 控制公司/用户有权限使用的 Android 真机。 +- 操作已登录的拼多多 App。 +- 根据运营审核过的 Excel 自动选择 SKU、数量并下单。 +- 在显式开启、金额上限和二次校验通过时执行受控自动支付。 +- 出现异常时截图、保存 UI XML、记录失败原因。 + +禁止做： + +- 绕过验证码、风控、人脸、短信、安全校验或平台限制。 +- 无配置、无金额上限、无二次校验的自动支付。 +- 保存支付密码、短信验证码、账号密码等敏感信息。 +- 调用、逆向或改造拼多多非公开接口。 +- 在页面识别失败时盲目点击不确定区域继续下单。 + +遇到验证码、风控、人脸、短信、安全验证时，必须进入 `待人工` 或失败分支。 + +## 文档维护 + +- 需求变化先改 `docs/02-requirements.md`，再改代码。 +- 技术选型变化先改 `docs/03-tech-stack.md`。 +- 模块职责、数据模型、任务状态变化先改 `docs/04-architecture.md` 和 `docs/api.md`。 +- GUI 区域或交互变化同步 `docs/routes.md`。 +- 任务状态变化同步 `tasks.md` 和 `progress.md`。 +- 代码现实变化同步 `docs/current-state.md`。 + +## 当前下一步 + +当前项目处于 MVP 起步 / 原型验证前。 + +下一个任务以 `tasks.md` 为准，当前应从： + +```text +T-001 初始化 Python 项目骨架 +``` + +开始。 + diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..1234c85 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,6 @@ +# CLAUDE.md + +> 本仓库的 agent 规则统一维护在 [`AGENTS.md`](AGENTS.md)，避免两份规则漂移。 +> Claude Code 与 Codex 共用同一套规则：**先读 [`AGENTS.md`](AGENTS.md)，再按其中的必读顺序进入项目文档。** + +不要在本文件单独维护编码规则或任务流程。需要修改 agent 行为约束时，改 `AGENTS.md`（仓库级规则）或 `docs/05-coding-rules.md`（编码硬约束），本文件保持为指向 `AGENTS.md` 的入口。 diff --git a/docs/00-ai-start-here.md b/docs/00-ai-start-here.md new file mode 100644 index 0000000..18313a3 --- /dev/null +++ b/docs/00-ai-start-here.md @@ -0,0 +1,131 @@ +# AI 开发入口 + +> 给 AI coding agent 的项目入口。这里负责导航和流程，硬性编码规则见 [`05-coding-rules.md`](05-coding-rules.md)。 + +## 一句话定位 + +拼多多批量下单执行器是一个内部运营桌面 GUI 工具，通过 Excel 批量导入已审核任务，控制 Android 真机在拼多多 App 中选择 SKU、下单，并把订单号和执行结果回写到 Excel。 + +第一版 MVP 只做：单机、单 Android 真机、固定表头 Excel、自动选择 SKU 和提交订单、默认支付前人工确认、预留受控自动支付开关、异常人工接管、结果回写。 + +## 必读顺序 + +每次开始写代码前，按这个顺序建立上下文： + +1. [`01-vision.md`](01-vision.md)：为什么做、为谁做、什么不做。 +2. [`02-requirements.md`](02-requirements.md)：MVP 要什么、怎么算达成。 +3. [`03-tech-stack.md`](03-tech-stack.md)：既定技术选型。 +4. [`04-architecture.md`](04-architecture.md)：系统结构、职责划分、数据模型和关键难点。 +5. [`05-coding-rules.md`](05-coding-rules.md)：写代码前必须遵守的规则。 +6. [`../tasks.md`](../tasks.md)：领取本轮唯一任务。 +7. [current-state.md](current-state.md)：当前代码现实、可运行命令、下一步入口。 +8. [../progress.md](../progress.md)：历史执行进度、验证结果和阻塞点。 + +如果仓库根目录有 `AGENTS.md`、`CLAUDE.md` 或其他 agent 规则文件，也必须先读。仓库级规则优先于项目局部建议。 + +## 当前阶段 + +当前项目处于：MVP 起步 / 原型验证前。 + +优先路径： + +1. Phase 0：建立 Python 桌面项目地基。 +2. Phase 1：验证 `uiautomator2 + ADB + 真机 + 拼多多 App` 的最高风险链路。 +3. Phase 2：实现 Excel 导入、GUI 展示、任务顺序执行和结果回写。 +4. Phase 3：完善异常处理、截图日志、人工接管和受控自动支付开关。 +5. Phase 4：打包为运营可运行的 Windows 桌面程序。 + +## 领取任务规则 + +从 [`../tasks.md`](../tasks.md) 领取任务时： + +- 只领取第一个状态为 `TODO` 且依赖均为 `DONE` 的任务。 +- 开始前把该任务状态改为 `DOING`。 +- 本轮只完成这一个任务。 +- 验收通过后把状态改为 `DONE`。 +- 做完即停，更新 `../progress.md` 和 `current-state.md`，汇报验证结果，等待下一步指令。 + +如果代码实际状态和任务看板冲突，先说明冲突，不要擅自跳步或重排。 + +## MVP 边界 + +MVP 只做： + +- 导入固定表头 Excel，并在 GUI 表格中展示任务。 +- 运营勾选任务并按当前排序顺序执行。 +- 通过 `uiautomator2 + ADB` 控制一台已登录拼多多账号的 Android 真机。 +- 打开商品链接，跳转拼多多 App，识别页面状态，选择指定 SKU 和数量。 +- 默认到支付确认或需要人工输入的位置暂停，支持人工接管后继续。 +- 预留受控自动支付能力：仅在开启配置、金额/SKU/数量/地址二次校验通过、未触发安全校验时继续支付。 +- 成功后展示订单号，并写入 Excel 结果文件。 +- 失败时展示失败原因、保留截图和页面 XML 以便排查。 + +MVP 不做： + +- 多人协作后台、账号权限系统、Web 管理后台。 +- 多设备并发调度。 +- 绕过验证码、风控、人脸、短信、安全校验或平台限制。 +- 在未开启配置、未通过二次校验或超出金额上限时自动支付。 +- 直接调用或逆向拼多多非公开接口。 +- 把 Excel 历史数据迁移到数据库。 + +## 事实来源 + +项目事实只信： + +- 本目录下的项目文档。 +- 真实 Excel 表头样例，后续应放入 `samples/` 或由用户明确提供。 +- 当前代码中的模型、状态枚举和模块合约。 +- 真机上通过截图、UI XML、日志实际验证得到的拼多多页面行为。 + +不要把以下内容当事实来源： + +- 旧的临时脚本。 +- 未被文档引用的测试截图。 +- 运营个人修改过且未确认的 Excel 派生格式。 +- 对拼多多页面结构的未验证猜测。 + +## 常见任务该看哪里 + +做 GUI： + +- 先看 `02-requirements.md` 的 P0 验收标准。 +- 再看 `routes.md` 的界面区域职责。 +- 最后看 `04-architecture.md` 的模块边界。 + +做 Excel 处理： + +- 先看 `04-architecture.md` 的 Excel 字段模型。 +- 再看 `api.md` 的本地模块合约。 + +做 Android 自动化： + +- 先看 `04-architecture.md` 的状态机和风险点。 +- 再看 `../tasks.md` 的 Phase 1 原型任务。 + +做打包 / 运行： + +- 先看 `03-tech-stack.md` 的运行命令。 +- 再看 `current-state.md` 的当前真实命令。 + +## 验证命令 + +当前项目尚未初始化代码。初始化后应在这里补充真实命令： + +```powershell +# 计划命令，待项目初始化后确认 +python -m pytest +python -m compileall src +python src/main.py +``` + +说明： + +- 改 GUI 后跑：启动桌面程序并手动验证主流程。 +- 改 Excel 处理后跑：单元测试和样例 Excel 导入/回写测试。 +- 改 Android 自动化后跑：真机连接测试和最小链路测试。 +- 如果命令当前不可运行，必须在回复里如实说明原因。 + + + + diff --git a/docs/01-vision.md b/docs/01-vision.md new file mode 100644 index 0000000..92efb53 --- /dev/null +++ b/docs/01-vision.md @@ -0,0 +1,48 @@ +# 项目愿景 + +## 一、核心目标 + +拼多多批量下单执行器要解决：内部运营同事需要根据 Excel 中的商品链接和 SKU 信息，重复在拼多多 App 中手动选择规格、下单、记录订单号，流程耗时且容易漏记的问题。 + +> 让运营同事能够从 Excel 批量导入已审核下单任务，使用桌面 GUI 控制 Android 真机执行下单，并把订单号、状态和失败原因回写到结果表。 + +它不是电商平台后台，也不是自动抢购工具，而是一个为内部合规运营流程服务的批量下单执行工具。 + +## 二、目标用户 + +- 运营同事：导入已审核 Excel、勾选任务、启动执行、配置支付模式、查看订单号和失败原因。 +- 开发/维护人员：维护 SKU 选择规则、页面状态识别、异常处理和设备连接能力。 +- 管理人员：通过运营整理后的 Excel 历史文档查看下单结果和异常情况。 + +## 三、产品原则 + +遇到取舍时，以这些原则为准： + +- **受控自动化优先**：Excel 数据已由运营审核时，可以自动下单；支付默认人工确认，也可在金额、SKU、数量、地址二次校验通过后按配置自动支付。 +- **安全校验转人工**：验证码、风控、人脸、短信等安全校验环节必须人工接管，不做绕过。 +- **核心流程优先**：先跑通单机、单设备、单账号、固定 Excel 表头的最小闭环。 +- **真实设备优先**：基于真实 Android 真机和拼多多 App 行为验证，不用模拟假流程冒充成功。 +- **可排查优先**：每条任务必须有状态、失败原因、截图或页面 XML 线索。 +- **Excel 兼容运营习惯**：MVP 不强行引入数据库，结果回写到 Excel 便于后续整理。 +- **小步交付**：先验证最高风险链路，再接入 GUI 和批量任务。 + +## 四、核心价值主张 + +| 价值点 | 说明 | +| --- | --- | +| 降低重复劳动 | 运营只需维护已审核 Excel 和处理异常节点，减少反复打开链接、选择 SKU、支付、复制订单号。 | +| 减少漏记错记 | 成功订单号、失败原因、执行时间统一写回结果文件。 | +| 易于落地 | 桌面 GUI 直接运行在连接手机的 Windows 电脑上，不需要部署后端服务。 | +| 可审计排查 | 保存任务日志、截图、页面 XML，便于定位 SKU 不匹配、页面变化或风控问题。 | + +## 五、不做什么（非目标） + +- 不做绕过验证码、风控、人脸、短信、安全校验或平台限制的能力。 +- 不做无配置、无金额上限、无二次校验的自动支付。 +- 不做拼多多非公开接口调用、逆向协议或账号风控规避。 +- 不做 Web 后台、多用户权限、多设备调度，除非后续版本明确升级。 +- 不做 Excel 历史数据分析系统，运营后期可基于结果 Excel 自行整理。 + +> MVP 的具体功能范围与验收标准，见 [需求](02-requirements.md)。 + + diff --git a/docs/02-requirements.md b/docs/02-requirements.md new file mode 100644 index 0000000..1d35461 --- /dev/null +++ b/docs/02-requirements.md @@ -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 内提供任何规避平台限制的能力。 + + diff --git a/docs/03-tech-stack.md b/docs/03-tech-stack.md new file mode 100644 index 0000000..01fca42 --- /dev/null +++ b/docs/03-tech-stack.md @@ -0,0 +1,72 @@ +# 技术栈（Tech Stack） + +> “用什么”的统一速查表。选型与理由在此集中维护；“怎么把它们搭起来”见 [架构设计](04-architecture.md)。 +> 未定项必须标为待定，不要让 agent 在代码里自行决定。 + +## 一、技术栈一览 + +| 维度 | 选型 | 状态 | 理由 / 说明 | +| --- | --- | --- | --- | +| 主语言 | Python 3.x | 已定 | 与 `uiautomator2`、Excel 处理、桌面 GUI 衔接快。具体版本待项目初始化确认。 | +| 桌面 GUI | PySide6 | 已定 | 适合 Windows 桌面程序，用户不需要部署 Web 服务。 | +| Android 控制 | ADB + `uiautomator2` | 已定 | MVP 只控制 Android 真机，开发成本低于 Appium。 | +| Excel 处理 | `openpyxl` | 已定 | 读取/写入 `.xlsx`，适合固定表头和结果回写。 | +| 图像/截图 | `uiautomator2` 截图能力；Pillow 待定 | 部分待定 | MVP 先保存截图；如需图片处理再引入 Pillow。 | +| OCR | 待定 | 待定 | MVP 不优先引入；UI XML 识别不足时再评估。 | +| 数据库 | 无数据库 | 已定 | MVP 以 Excel 文件作为输入输出，避免过早引入数据库。 | +| 鉴权方式 | 无工具账号 | 已定 | 本地内部工具；拼多多账号由真机 App 登录态承担。 | +| 后端服务 | 无独立后端 | 已定 | 单机 GUI 内直接调用本地模块。 | +| 日志 | Python `logging` | 已定 | 保存执行日志，便于排查。 | +| 测试 | `pytest` | 待定 | 建议用于 Excel 解析、状态机、SKU 匹配等纯逻辑测试。 | +| 打包 | PyInstaller | 待定 | MVP 稳定后打包为 Windows 可执行程序。 | + +## 二、决策记录与演进 + +- 当前选择 **桌面 GUI**，因为功能少、给运营内部使用、运行环境就是连接手机的 Windows 电脑，落地快。 +- 当前选择 **`uiautomator2 + ADB`**，因为只做 Android 真机控制，不需要 Appium 的跨平台和服务端复杂度。 +- 当前选择 **Excel 输入输出**，因为运营后期可直接整理历史文档，MVP 不需要数据库。 +- 当前不引入 **Web 后台 / 多设备调度 / 数据库**，避免第一版复杂度过高。 +- OCR、图像识别、Appium、SQLite 作为后续选项，仅在真实页面验证需要时引入。 + +## 三、构建与运行命令 + +当前代码尚未初始化。以下为计划命令，初始化后必须改成真实命令。 + +| 用途 | 命令 | +| --- | --- | +| 创建虚拟环境 | `python -m venv .venv` | +| 激活虚拟环境 | `.venv\Scripts\Activate.ps1` | +| 安装依赖 | `pip install -r requirements.txt` | +| 本地运行 | `python src/main.py` | +| 测试 | `python -m pytest` | +| 语法检查 | `python -m compileall src` | +| 打包 | `pyinstaller app.spec` | + +Windows PowerShell： + +```powershell +python -m venv .venv +.venv\Scripts\Activate.ps1 +pip install -r requirements.txt +python src/main.py +python -m pytest +``` + +## 四、设备与环境要求 + +- Windows 电脑。 +- Android 真机，已开启开发者选项和 USB 调试。 +- ADB 可用，电脑能看到设备。 +- 真机已安装拼多多 App，并已登录可下单账号。 +- 真机网络稳定，屏幕常亮或执行期间不锁屏。 +- 支付默认由运营人工确认；开启受控自动支付时，必须由配置、金额上限和二次校验控制。 +- 验证码、风控、人脸、短信等安全校验节点由运营人工处理。 + +## 五、依赖纪律 + +- 新增第三方依赖前，先说明用途、替代方案和维护成本。 +- 不确定的技术选型先更新本文，再进入代码。 +- 不允许同一职责并存两套框架或两套状态管理方案。 +- 不允许为了绕过平台安全校验而引入逆向、Hook、抓包改包等依赖。 + + diff --git a/docs/04-architecture.md b/docs/04-architecture.md new file mode 100644 index 0000000..8b31c49 --- /dev/null +++ b/docs/04-architecture.md @@ -0,0 +1,358 @@ +# 架构设计 + +> 本文讲“怎么把技术栈搭起来”：系统结构、职责划分、数据模型、技术难点、开发顺序。 +> 具体用了哪些框架 / 库 / 数据库 / 部署方式，见 [技术栈](03-tech-stack.md)。 + +## 一、系统结构 + +```text +运营同事 + | + v +Windows 桌面 GUI（PySide6） + | + +--> Excel 导入/回写模块（openpyxl） + | + +--> 任务执行器 / 状态机 + | + +--> Android 控制模块（uiautomator2 + ADB） + | | + | v + | Android 真机 + 拼多多 App + | + +--> 截图 / UI XML / 日志归档 +``` + +MVP 没有独立后端服务，也没有数据库。Excel 是任务输入和结果输出，日志和截图是排查辅助文件。 + +## 二、职责划分 + +**桌面 GUI** + +- 导入 Excel 文件。 +- 展示任务表格、状态、订单号、失败原因。 +- 支持勾选任务、开始、暂停、继续、取消、人工接管和支付模式配置。 +- 展示当前手机截图、当前步骤和实时日志。 +- 防止执行中重复启动同一批任务。 + +**Excel 模块** + +- 校验固定表头。 +- 读取任务行并转换为内部任务模型。 +- 生成默认结果文件路径，不默认覆盖原始 Excel。 +- 将状态、订单号、失败原因、执行时间、截图路径写回结果文件。 + +**任务执行器 / 状态机** + +- 接收 GUI 选中的任务列表。 +- 按顺序逐条执行。 +- 管理任务状态流转。 +- 根据支付模式决定支付前暂停或受控继续支付。 +- 遇到需要人工处理的节点时暂停并通知 GUI。 +- 捕获异常并记录失败原因。 + +**Android 控制模块** + +- 连接和检查 Android 真机。 +- 打开拼多多商品链接。 +- 等待并识别当前页面状态。 +- 点击购买按钮、打开 SKU 面板、选择 SKU、设置数量。 +- 到支付确认节点时执行二次校验，并根据支付模式暂停或继续。 +- 到安全校验节点时停止自动动作并转人工。 +- 保存截图和 UI XML。 + +**拼多多流程模块** + +- 封装与拼多多 App 页面相关的选择器、文本匹配和步骤判断。 +- 不直接散落在 GUI 或 Excel 模块中。 +- 页面变化时优先修改这里。 + +**日志与归档** + +- 每条任务记录开始时间、结束时间、状态、关键步骤。 +- 失败时保存截图和 UI XML。 +- 日志不记录支付密码、短信验证码、账号密码等敏感信息。 + +## 三、数据模型 + +### 3.1 Excel 输入字段 + +最终字段以用户提供的真实样例为准。MVP 建议固定表头： + +| 字段 | 必填 | 说明 | +| --- | --- | --- | +| `任务ID` | 否 | 运营侧任务编号；为空时系统可用行号作为内部编号。 | +| `商品链接` | 是 | 拼多多商品链接。 | +| `商品名称` | 否 | 便于运营识别，不作为自动化唯一依据。 | +| `SKU信息` | 是 | 建议格式：`颜色=黑色;尺码=XL;套餐=单件`。 | +| `数量` | 是 | 下单数量，默认应为正整数。 | +| `收货人` | 否 | MVP 可先使用拼多多账号默认地址；如需要校验地址再启用。 | +| `手机号` | 否 | 同上。 | +| `地址` | 否 | 同上。 | +| `备注` | 否 | 运营备注，不影响自动化。 | +| `预期金额` | 否 | 开启受控自动支付时建议填写，用于支付前比对。 | +| `最高可支付金额` | 否 | 开启受控自动支付时建议填写，作为单笔金额上限。 | + +如果业务需要拆分 SKU，可后续支持 `SKU1`、`SKU2`、`SKU3`，但 MVP 优先统一用 `SKU信息`。 + +### 3.2 Excel 输出字段 + +结果文件应在原始字段基础上追加或更新： + +| 字段 | 说明 | +| --- | --- | +| `状态` | `待执行`、`执行中`、`待人工`、`成功`、`失败`、`已取消`。 | +| `订单号` | 成功后读取到的拼多多订单号。 | +| `失败原因` | 失败或暂停原因。 | +| `执行时间` | 最近一次完成或失败时间。 | +| `截图路径` | 失败或关键节点截图保存路径。 | +| `结果备注` | 可选，记录人工接管说明。 | + +### 3.3 内部任务模型 + +```text +OrderTask + task_id: str + row_index: int + product_url: str + product_name: str | None + sku_text: str + sku_items: dict[str, str] + quantity: int + receiver: str | None + phone: str | None + address: str | None + note: str | None + expected_amount: Decimal | None + max_pay_amount: Decimal | None + status: TaskStatus + order_no: str | None + fail_reason: str | None + screenshot_path: str | None + started_at: datetime | None + finished_at: datetime | None +``` + +支付模式不挂在单条任务上：是否启用受控自动支付由**全局** `PaymentConfig` 决定（见 §4.4），`OrderTask` 只持有支付前二次校验需要的 `expected_amount` / `max_pay_amount` 等输入数据。 + +### 3.4 任务状态 + +```text +待执行 -> 执行中 -> 待人工 -> 执行中 -> 成功 +待执行 -> 执行中 -> 失败 +待执行 -> 已取消 +执行中 -> 已取消 +待人工 -> 已取消 +``` + +状态含义： + +- `待执行`：已导入但未开始。 +- `执行中`：自动化正在处理。 +- `待人工`：需要运营在手机或 GUI 中确认/接管。 +- `成功`：已获得订单号并写入结果。 +- `失败`：无法继续执行，已记录原因。 +- `已取消`：用户取消执行。 + +#### 枚举命名与中英映射 + +代码标识符使用英文（见 [`05-coding-rules.md`](05-coding-rules.md) §6），中文仅用于 GUI 展示和 Excel 回写。`TaskStatus` 枚举以英文成员名定义，中文为其显示值，映射如下： + +| 枚举成员（代码） | 显示值（GUI / Excel） | +| --- | --- | +| `TaskStatus.PENDING` | `待执行` | +| `TaskStatus.RUNNING` | `执行中` | +| `TaskStatus.MANUAL` | `待人工` | +| `TaskStatus.SUCCESS` | `成功` | +| `TaskStatus.FAILED` | `失败` | +| `TaskStatus.CANCELLED` | `已取消` | + +约定： + +- 中↔英映射只在写入 Excel 或渲染 GUI 的边界处发生（建议由 `TaskStatus` 提供 `display_name` 属性集中维护），核心逻辑只比较英文枚举成员。 +- `OrderTask.status` 字段类型为 `TaskStatus`，不直接存中文字符串。 +- 注意区分「任务状态」与「执行器状态」：上表是单条任务的 `status`；批次级的「暂停」属于执行器状态，不进入本枚举（见 §4.5）。 + +## 四、核心流程 + +### 4.1 批量执行流程 + +```text +导入 Excel + -> 校验表头 + -> GUI 展示任务 + -> 用户勾选任务 + -> 点击开始 + -> 检查 Android 设备 + -> 按顺序执行每条任务 + -> 更新 GUI 状态 + -> 写入结果 Excel +``` + +### 4.2 单条任务流程 + +```text +打开商品链接 + -> 跳转拼多多 App + -> 识别商品详情页 + -> 点击购买入口 + -> 打开 SKU 面板 + -> 按 SKU 信息选择规格 + -> 设置数量 + -> 进入订单确认页 + -> 校验商品标题 / SKU / 数量 / 地址 / 实付金额 + -> 默认支付前暂停 / 开启受控自动支付时继续支付 + -> 如需人工处理则等待人工完成后继续 + -> 读取订单号 + -> 写回结果 +``` + +### 4.3 异常处理原则 + +- 找不到按钮、SKU、数量控件：暂停或失败，不使用不确定坐标硬点。 +- 出现验证码、风控、人脸、短信、安全验证：进入 `待人工`。 +- 价格变化、超过最高可支付金额、库存不足、商品下架：记录明确失败原因。 +- 设备断开、App 崩溃、网络异常：失败并保留截图/日志。 +- 未读取到订单号：允许人工录入或标记为待核查，MVP 具体交互待实现时确认。 + +### 4.4 支付模式 + +支付模式是**全局批次级配置**，不是按行任务字段。整个批次共用一个 `PaymentConfig`，由 GUI 显式设置（默认人工确认），执行中不得悄悄切换。 + +```text +PaymentConfig + mode: PaymentMode # MANUAL（默认）/ AUTO（受控自动支付） + per_order_limit: Decimal # 单笔金额上限，开启 AUTO 时必填 + batch_limit: Decimal | None # 批次金额上限，建议填写 + price_tolerance: Decimal # 实付与预期金额的允许偏差，默认 0 +``` + +```text +PaymentMode（枚举，代码用英文名，显示用中文） + MANUAL -> 人工确认支付 + AUTO -> 受控自动支付 +``` + +单条任务的支付决策 = 全局 `PaymentConfig` + 该任务行的 `expected_amount` / `max_pay_amount`。MVP 不支持按行覆盖支付模式；如未来需要，再在本文和 `api.md` 中显式扩展，不得在代码里临时加按行开关。 + +MVP 支持两种支付模式： + +```text +人工确认支付（默认） + -> 到支付确认页 + -> 校验商品 / SKU / 数量 / 地址 / 金额 + -> 进入待人工 + -> 运营确认后继续读取订单号 + +受控自动支付（显式开启） + -> 到支付确认页 + -> 校验商品 / SKU / 数量 / 地址 / 金额 + -> 检查单笔金额上限和批次金额上限 + -> 未触发安全校验时继续支付 + -> 触发验证码 / 风控 / 人脸 / 短信时进入待人工 +``` + +受控自动支付约束： + +- 必须由 GUI 配置显式开启，不能默认开启。 +- 必须配置单笔金额上限；建议配置批次金额上限。 +- 如果 Excel 提供 `预期金额`，支付页实付金额必须与预期一致或在允许偏差内。 +- 如果 Excel 提供 `最高可支付金额`，支付页实付金额不得超过该值。 +- 支付前必须保存截图和 UI XML。 +- 不保存支付密码、短信验证码、人脸信息等敏感数据。 +- 出现安全校验时只允许转人工，不做绕过。 + +### 4.5 执行器状态与暂停语义 + +「暂停」是**执行器（批次）层**的状态，不是单条任务的 `status`。任务级状态只有 §3.4 的六种；GUI 工具栏的「暂停 / 继续」控制的是执行器是否继续领取下一条任务，不会把任何任务改成「已暂停」。 + +执行器状态（`RunnerState`，与 `TaskStatus` 分离）： + +```text +IDLE 空闲（未开始或批次已结束） +RUNNING 正在按顺序执行 +PAUSED 已暂停；当前任务执行完后不再领取下一条 +STOPPING 取消中；正在安全收尾当前任务 +``` + +约定： + +- 点「暂停」时，正在执行的任务跑完当前安全步骤后停在边界，执行器进入 `PAUSED`；已进入 `待人工` 的任务不受影响。 +- 点「继续」时执行器回到 `RUNNING`，从下一条勾选任务继续。 +- 「取消」使执行器进入 `STOPPING`；无法安全中断的当前任务按 §3.4 转 `待人工` 或 `已取消`，不会硬杀。 +- `RunnerState` 不写入 Excel；Excel 只记录任务级 `status`。 + +## 五、关键技术难点 + +| 难点 | 说明 | 应对 | +| --- | --- | --- | +| 拼多多页面可识别性 | 第三方 App 控件文本和结构可能变化，部分区域可能无法通过 UI XML 获取。 | Phase 1 先做真机原型；必要时保存截图并后续引入 OCR。 | +| SKU 精确匹配 | SKU 文案可能存在同义、缺货、套餐组合、层级顺序问题。 | MVP 用明确文本匹配；匹配失败即暂停/失败，不猜测。 | +| 支付和安全节点 | 涉及真实资金和账号安全。 | 默认人工确认；受控自动支付必须经过二次校验、金额上限和显式开关；安全校验转人工。 | +| 批量执行稳定性 | App 卡顿、网络波动、设备锁屏会导致流程中断。 | 增加超时、重试、截图、状态恢复；先单设备验证。 | +| 结果回写可靠性 | 执行中断可能导致结果丢失。 | 每条任务结束后立即保存结果文件。 | + +## 六、推荐开发顺序 + +1. 初始化 Python 项目骨架和文档约定。 +2. 实现 Excel 读取、表头校验、内部任务模型。 +3. 实现最小 PySide6 GUI：导入、表格展示、日志区域。 +4. 验证 ADB 和 `uiautomator2` 真机连接。 +5. 做单条商品链接跳转和截图/UI XML 保存原型。 +6. 做 SKU 面板打开和 SKU 文本选择原型。 +7. 接入任务执行器，跑通单条任务到支付前校验和默认暂停。 +8. 接入批量顺序执行、状态更新和结果 Excel 回写。 +9. 完善异常处理、人工接管、受控自动支付开关和打包。 + +## 七、项目结构建议 + +```text +cmpdd/ +├── docs/ +├── src/ +│ ├── main.py +│ ├── app/ +│ │ ├── main_window.py +│ │ └── widgets/ +│ ├── core/ +│ │ ├── models.py +│ │ ├── task_runner.py +│ │ └── status.py +│ ├── excel/ +│ │ ├── reader.py +│ │ └── writer.py +│ ├── android/ +│ │ ├── device.py +│ │ └── pdd_flow.py +│ └── logging_config.py +├── tests/ +├── samples/ +├── logs/ +├── artifacts/ +├── requirements.txt +└── README.md +``` + +- `src/app/`：PySide6 GUI。 +- `src/core/`：任务模型、状态机、执行编排。 +- `src/excel/`：Excel 导入、校验、回写。 +- `src/android/`：设备连接、拼多多 App 自动化流程。 +- `logs/`：本地运行日志，默认不提交真实敏感日志。 +- `artifacts/`：截图、UI XML、结果文件等运行产物，默认不提交真实数据。 +- `samples/`：脱敏样例 Excel。 + +## 八、架构纪律 + +- GUI 不直接写 Android 点击细节，必须通过任务执行器和 Android 模块。 +- Android 模块不直接读写 Excel。 +- Excel 模块不关心拼多多页面状态。 +- 状态枚举和字段变化必须同步更新本文、`api.md` 和相关任务验收。 +- 支付逻辑必须受显式开关、二次校验和金额上限控制。 +- 安全校验、验证码、风控逻辑只能进入人工接管分支。 + + + + + + + diff --git a/docs/05-coding-rules.md b/docs/05-coding-rules.md new file mode 100644 index 0000000..f7e964f --- /dev/null +++ b/docs/05-coding-rules.md @@ -0,0 +1,97 @@ +# 编码规则（Coding Rules） + +> 每次写代码前先读完本文件。这是让 AI 不跑偏、代码质量稳定的硬约束。 +> 与技术细节冲突时，以 [技术栈](03-tech-stack.md) / [架构设计](04-architecture.md) 的事实为准；与“该不该做”冲突时，以 [需求](02-requirements.md) 为准。 + +## 0. 黄金法则 + +1. **不臆造**：Excel 字段、页面选择器、接口、依赖，不确定就查证或询问。 +2. **守范围**：只做当前任务要求的事，不顺手加 Web 后台、多设备、数据库等后续能力。 +3. **照架构**：使用既定技术栈和模块边界，不擅自引入新框架。 +4. **小步改**：一次只解决一个问题，不夹带无关重构。 +5. **可验证**：改完必须能运行、能测试、对得上验收标准。 + +## 1. 动手前 + +- 按链路确认：`vision` -> `requirements` -> `tech-stack` -> `architecture` -> `tasks`。 +- 找到本任务对应的验收标准，写之前就知道“怎么算做对”。 +- 先找现有函数、组件、工具和测试，复用优先。 +- 涉及真机自动化时，先确认设备连接和当前 App 状态。 +- 如果需求含糊，或改动会偏离原则 / 架构，先问。 + +## 2. 事实来源纪律 + +- Excel 表头以用户提供的真实样例或 `04-architecture.md` 当前约定为准。 +- 拼多多页面状态以真机截图、UI XML 和实际运行日志为准。 +- 不从旧截图、临时脚本、未确认样例里推断当前事实。 +- 不虚构字段、按钮文本、订单号位置、状态码、配置项。 +- 数据结构变化必须同步更新 `04-architecture.md`、`api.md` 和相关任务。 + +## 3. 范围纪律 + +- MVP 只做 `02-requirements.md` 中列为 P0 的功能。 +- V2 / V3 功能只记录，不实现。 +- 需求明确排除的非目标不得实现。 +- 不为“将来可能用到”提前抽象。 +- 不默认覆盖原始 Excel，除非用户明确要求。 + +## 4. 安全与合规纪律 + +- 绝不实现绕过验证码、风控、人脸、短信、安全校验或平台限制的逻辑。 +- 绝不实现无配置、无二次校验、无金额上限的自动支付。 +- 绝不记录支付密码、短信验证码、账号密码等敏感信息。 +- 绝不调用、逆向或改造拼多多非公开接口。 +- 自动支付必须显式开启，并在商品、SKU、数量、地址、金额校验通过后才能继续。 +- 遇到安全校验时进入 `待人工`，由运营在真机上处理。 + +## 5. 架构纪律 + +- 技术栈以 `03-tech-stack.md` 为准。 +- 新增依赖前先说明理由；未经确认不要引入重量级依赖。 +- GUI、Excel、任务执行器、Android 控制模块职责必须分离。 +- API/本地模块合约以 `api.md` 为准，界面结构以 `routes.md` 为准。 +- 页面选择器集中在拼多多流程模块，不散落在 GUI 代码里。 + +## 6. 代码规范 + +- 标识符使用英文。 +- UI 文案、注释、文档语言使用中文，除非引用库 API 或错误码。 +- 错误必须处理，不吞错。 +- 注释解释“为什么”，不复述“做了什么”。 +- 日志要包含任务 ID 和当前步骤，但不能包含敏感信息。 +- 遵守项目已有格式化工具，不手工制造风格分裂。 + +## 7. 测试与验证 + +完成前至少检查： + +- [ ] 构建或语法检查通过。 +- [ ] 相关测试通过。 +- [ ] 对得上需求验收标准。 +- [ ] 没有夹带无关改动。 +- [ ] 涉及文档事实变化时，文档已同步。 +- [ ] 涉及 Android 自动化时，说明是否已用真机验证。 +- [ ] 回复里如实说明跑了什么命令、结果如何。 + +计划命令，初始化后必须改成真实命令： + +```powershell +python -m pytest +python -m compileall src +python src/main.py +``` + +## 8. 绝不 + +- 绝不把密钥、token、密码、支付密码、短信验证码写进代码或文档样例。 +- 绝不为了让测试通过而删除断言、降低验收标准。 +- 绝不擅自删除用户已有文件或重置工作区。 +- 绝不在没说明的情况下改公共接口、迁移数据结构或升级依赖。 +- 绝不在自动化失败时盲目点击不确定区域继续下单。 + +## 9. 拿不准就问 + +问题要具体，说明你卡在哪里、有哪些选项、倾向哪个选项以及原因。 + + + diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..87eda06 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,33 @@ +# 项目文档导航 + +## 一句话定位 + +拼多多批量下单执行器是一个给内部运营同事使用的 Windows 桌面工具，用于从固定表头 Excel 导入已审核的商品下单任务，按选中顺序控制一台 Android 真机在拼多多 App 中下单，并把执行状态、订单号和失败原因回写到 Excel 结果文件。 + +第一版先完成「导入 Excel -> GUI 展示任务 -> 控制真机下单 -> 默认支付前人工确认，可配置受控自动支付 -> 记录订单号或失败原因 -> 回写 Excel」闭环。 + +## 文档导航 + +- [AI 开发入口](00-ai-start-here.md)：agent 每次开始工作的入口、阅读顺序和任务领取规则。 +- [项目愿景](01-vision.md)：为什么做、为谁做、产品原则、非目标。 +- [需求](02-requirements.md)：MVP 要什么、用户故事、验收标准，不写技术实现。 +- [技术栈](03-tech-stack.md)：确定使用哪些框架、库、设备依赖和运行方式。 +- [架构设计](04-architecture.md)：系统结构、模块职责、数据模型、关键风险和开发顺序。 +- [编码规则](05-coding-rules.md)：AI 写代码前必须遵守的硬约束。 +- [任务看板](../tasks.md)：按依赖拆分的小任务，agent 每轮只做一个。 +- [执行进度](../progress.md)：任务完成记录、验证结果、阻塞点和下一步。 +- [本地模块合约](api.md)：无后端 API 时的本地模块接口约定。 +- [界面结构](routes.md)：桌面 GUI 页面/区域职责。 +- [当前实现状态](current-state.md)：仓库现实状态、代码结构、真实运行命令。 + +## 维护原则 + +- 需求变化先改文档，再改代码。 +- 代码现实变化后同步 `current-state.md`；任务执行记录写入 [`../progress.md`](../progress.md)。 +- Excel 字段、任务状态、模块接口一旦在文档中定稿，代码不得另起一套。 +- agent 开始新任务前，必须从 `00-ai-start-here.md` 进入。 + + + + + diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..b5febc9 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,198 @@ +# 本地模块合约 + +> 本项目 MVP 没有后端 API。本文定义本地模块之间的目标接口形状，避免 GUI、Excel、Android 自动化逻辑互相耦合。 + +## 通用约定 + +- 模块间传递结构化对象，不传裸字典到处拼字段。 +- 错误使用明确异常或结果对象，不能静默返回 `None`。 +- 时间统一使用本地时间并在写入 Excel 时格式化为可读字符串。 +- 所有自动化步骤必须携带 `task_id`，方便日志关联。 + +通用错误对象建议： + +```text +TaskError + code: str + message: str + step: str + screenshot_path: str | None +``` + +## Excel 模块 + +### `load_tasks(file_path) -> list[OrderTask]` + +职责： + +- 打开 `.xlsx` 文件。 +- 校验固定表头。 +- 跳过完全空行。 +- 将每一行转换为 `OrderTask`。 + +失败： + +- 缺少必填列时抛出表头错误。 +- 必填字段为空、数量非法时返回行级错误或阻止导入，具体交互实现时确认。 + +### `create_result_path(source_path) -> result_path` + +职责： + +- 根据原文件路径生成默认结果文件名。 +- 默认格式：`原文件名_执行结果.xlsx`。 +- 不覆盖原始 Excel。 + +### `save_task_result(result_path, task) -> None` + +职责： + +- 写入指定任务行的状态、订单号、失败原因、执行时间、截图路径。 +- 每条任务完成、失败或进入人工节点后尽快保存。 + +## GUI 模块 + +### `MainWindow.import_excel()` + +职责： + +- 让用户选择 Excel 文件。 +- 调用 Excel 模块读取任务。 +- 在表格中展示任务。 + +### `MainWindow.start_selected_tasks()` + +职责： + +- 获取当前勾选任务。 +- 按表格顺序交给任务执行器。 +- 执行中禁用重复启动。 + +### `MainWindow.update_task_status(task)` + +职责： + +- 更新表格中的状态、订单号、失败原因。 +- 刷新日志和截图区域。 + +## 任务执行器 + +### `TaskRunner.run(tasks) -> None` + +职责： + +- 按顺序执行任务。 +- 对每条任务调用拼多多流程模块。 +- 发出状态变化事件给 GUI。 +- 每条任务结束后触发 Excel 回写。 + +### `TaskRunner.pause() -> None` / `TaskRunner.resume() -> None` + +职责： + +- `pause()`：把**执行器**状态置为 `PAUSED`，当前任务跑完安全边界后不再领取下一条（执行器级，见 [`04-architecture.md`](04-architecture.md) §4.5）。 +- `resume()`：执行器回到 `RUNNING`，从下一条勾选任务继续。 +- 二者只改 `RunnerState`，不改任何单条任务的 `status`。 + +### `TaskRunner.pause_for_manual(task, reason) -> None` + +职责： + +- 将单条任务标记为 `待人工`（任务级，区别于上面的执行器 `pause()`）。 +- 通知 GUI 和运营。 +- 等待用户点击继续、失败或取消。 + +### `TaskRunner.set_payment_config(config: PaymentConfig) -> None` + +职责： + +- 接收 GUI 设置的**全局批次级**支付配置（`PaymentConfig`，定义见 [`04-architecture.md`](04-architecture.md) §4.4）。 +- `mode=AUTO` 时配置必须包含单笔金额上限；建议包含批次金额上限和价格允许偏差。 +- 不允许在未配置金额上限时把 `mode` 设为 `AUTO`。 +- 支付模式是全局的，不在单条 `OrderTask` 上保存按行开关。 + +### `TaskRunner.cancel() -> None` + +职责： + +- 尽快停止后续任务。 +- 当前任务如果不能安全中断，应标记为 `待人工` 或 `已取消`。 + +## Android 设备模块 + +### `DeviceManager.connect() -> DeviceInfo` + +职责： + +- 检查 ADB 设备。 +- 建立 `uiautomator2` 连接。 +- 返回设备型号、序列号、在线状态。 + +### `DeviceManager.screenshot(task_id, step) -> path` + +职责： + +- 保存当前手机截图。 +- 返回截图路径。 + +### `DeviceManager.dump_ui(task_id, step) -> path` + +职责： + +- 保存当前 UI XML。 +- 返回 XML 路径。 + +## 拼多多流程模块 + +### `PddFlow.open_product(product_url) -> PageState` + +职责： + +- 打开商品链接。 +- 等待跳转到拼多多 App。 +- 判断是否进入商品详情页。 + +### `PddFlow.select_sku(sku_items, quantity) -> StepResult` + +职责： + +- 打开购买/SKU 面板。 +- 按 `sku_items` 精确匹配规格。 +- 设置数量。 + +### `PddFlow.go_to_order_confirm() -> StepResult` + +职责： + +- 进入订单确认页。 +- 读取商品标题、SKU、数量、地址、实付金额等确认信息。 + +### `PddFlow.pay_if_allowed(payment_config, confirm_info) -> StepResult` + +职责： + +- 根据支付配置和确认页信息判断是否允许继续支付。 +- 人工确认模式下返回需要人工处理。 +- 受控自动支付模式下，只有商品、SKU、数量、地址、金额、单笔/批次上限全部通过时才继续。 +- 遇到验证码、风控、人脸、短信等安全校验时返回 `待人工`。 + +### `PddFlow.read_order_no() -> str | None` + +职责： + +- 在支付完成后尝试读取订单号。 +- 读取失败时返回空，由 GUI 提供人工录入兜底。 + +## 待实现时确认 + +- 真实 Excel 表头是否使用 `SKU信息` 统一字段，还是拆分为多个 SKU 列。 +- 导入时遇到部分行错误，是阻止全部导入还是只标记错误行。 +- 自动读取订单号失败时的人工录入流程。 +- 批量执行失败后默认继续下一条还是暂停批次。 +- 受控自动支付的默认单笔金额上限、批次金额上限和允许价格偏差。 + + + + + + diff --git a/docs/current-state.md b/docs/current-state.md new file mode 100644 index 0000000..009c5a4 --- /dev/null +++ b/docs/current-state.md @@ -0,0 +1,88 @@ +# 当前实现状态 + +> 本文记录代码与任务看板的现实状态，帮助 AI coding agent 避免只看计划而忽略仓库现状。 +> +> **职责边界**：本文是**可覆盖的当前快照**——只描述"现在仓库长什么样"（目录、可运行命令、下一个可领取任务），变化时直接改写为最新状态。历史执行流水、每轮验证结果和阻塞记录写入 [`../progress.md`](../progress.md)，本文不保留历史条目。 + +## 当前快照 + +- 日期：2026-06-24 +- 阶段：MVP 起步 / 原型验证前 +- 技术栈：计划使用 Python + PySide6 + `uiautomator2` + ADB + `openpyxl` +- 生产代码：尚未初始化 +- 测试：尚未初始化 +- 数据：尚未提供真实 Excel 样例 + +## 当前目录要点 + +| 路径 | 状态 | 说明 | +| --- | --- | --- | +| `docs/` | 已有 | 项目规范化文档，已按 harness coding 文档风格建立。 | +| `src/` | 待建 | 桌面 GUI、任务执行器、Excel、Android 自动化代码。 | +| `tests/` | 待建 | Excel 解析、状态机、SKU 匹配等测试。 | +| `samples/` | 待建 | 脱敏 Excel 样例。 | +| `logs/` | 待建 | 本地运行日志。 | +| `artifacts/` | 待建 | 截图、UI XML、结果文件等运行产物。 | + +## 任务与进度状态 + +任务定义以 [`../tasks.md`](../tasks.md) 为准，执行记录以 [`../progress.md`](../progress.md) 为准。 + +- 已完成：项目文档初始化。 +- 正在进行：无。 +- 下一个可领取任务：`T-001 初始化 Python 项目骨架`。 + +## 当前可运行内容 + +当前没有可运行代码。初始化后应补充真实命令： + +```powershell +# 本地开发 +python src/main.py + +# 测试 +python -m pytest + +# 语法检查 +python -m compileall src +``` + +## 已确认产品决策 + +- 第一版使用桌面 GUI，不做 Web 后台。 +- 第一版通过固定表头 Excel 导入任务，并回写结果 Excel。 +- 第一版控制单台 Android 真机，使用 `uiautomator2 + ADB` 做最小可行性验证。 +- 第一版默认人工确认支付，并预留受控自动支付：必须显式开启，且通过金额上限、商品/SKU/数量/地址二次校验；安全校验、验证码、风控、人脸、短信等节点必须人工接管。 +- 默认不覆盖原始 Excel，生成 `_执行结果.xlsx`。 + +## 待用户提供 / 待验证 + +- 真实 Excel 表头样例。 +- 一台可连接的 Android 真机。 +- ADB 可用环境。 +- 已登录拼多多账号的真机状态。 +- 至少一个用于测试的拼多多商品链接和 SKU 信息。 + +## 开始编码前检查 + +开始任意任务前： + +1. 读仓库级 agent 规则文件（如有）。 +2. 读 `docs/00-ai-start-here.md`。 +3. 读 `docs/05-coding-rules.md`。 +4. 在 `../tasks.md` 取第一个 `TODO` 且依赖均 `DONE` 的任务。 +5. 将该任务状态改为 `DOING`。 + +## 维护规则 + +当实际代码状态发生变化时，同步更新本文件： + +- 新增或移动入口文件。 +- 初始化框架或模块。 +- 任务从 `TODO` 进入 `DOING` 或 `DONE` 时，同步 `../tasks.md` 和 `../progress.md`。 +- 新增可运行命令。 +- 发现文档和代码现实不一致。 + + + + diff --git a/docs/routes.md b/docs/routes.md new file mode 100644 index 0000000..3c87f3f --- /dev/null +++ b/docs/routes.md @@ -0,0 +1,96 @@ +# 界面结构 + +> 本项目是桌面 GUI，不使用 Web 路由。本文约定主窗口区域、页面职责和组件归属。 + +## 主窗口布局 + +```text +┌──────────────────────────────────────────────────────────┐ +│ 顶部工具栏：导入 Excel | 开始 | 暂停 | 继续 | 取消 | 人工接管 | 支付模式 │ +├──────────────────────────────┬───────────────────────────┤ +│ 任务表格 │ 当前设备 / 当前截图 │ +│ - 勾选 │ - 设备状态 │ +│ - 序号 │ - 当前步骤 │ +│ - 商品链接 │ - 手机截图 │ +│ - SKU 信息 │ │ +│ - 数量 │ │ +│ - 状态 │ │ +│ - 订单号 │ │ +│ - 失败原因 │ │ +├──────────────────────────────┴───────────────────────────┤ +│ 日志区域 │ +└──────────────────────────────────────────────────────────┘ +``` + +## 页面 / 区域职责 + +### 顶部工具栏 + +- 导入 Excel。 +- 开始执行选中任务。 +- 暂停当前批次。 +- 继续人工处理后的任务。 +- 取消后续任务。 +- 进入人工接管状态。 +- 配置支付模式：人工确认支付（默认）或受控自动支付。 + +按钮状态必须跟随任务执行状态变化，避免重复启动或误操作。 + +### 任务表格 + +- 展示导入的 Excel 任务。 +- 支持勾选/取消勾选。 +- 按当前展示顺序执行选中任务。 +- 实时更新状态、订单号、失败原因。 +- 行状态要清晰区分：待执行、执行中、待人工、成功、失败、已取消。 + +### 当前设备 / 当前截图 + +- 展示 Android 设备连接状态。 +- 展示当前执行任务和步骤。 +- 展示最近截图。 +- 设备断开或截图失败时显示明确错误。 + +### 日志区域 + +- 展示任务级日志。 +- 每条日志包含时间、任务 ID、步骤、结果。 +- 不展示支付密码、短信验证码、账号密码等敏感信息。 + +### 人工接管交互 + +- 当系统进入 `待人工` 时，GUI 应明确展示原因。 +- 用户可以在真机上手动处理。 +- GUI 提供继续、标记成功、标记失败、取消批次等操作。 +- 自动化不得在安全校验节点自行尝试绕过。 + +### 支付模式配置 + +- 默认模式为人工确认支付。 +- 受控自动支付必须由用户显式开启。 +- 开启时必须填写单笔金额上限；建议填写批次金额上限。 +- GUI 应显示当前模式，执行中不得悄悄切换。 + +## 组件建议 + +| 组件 | 归属 | 说明 | +| --- | --- | --- | +| `MainWindow` | 全局 | 主窗口和整体布局。 | +| `Toolbar` | 全局 | 导入、开始、暂停、继续、取消、人工接管、支付模式。 | +| `TaskTable` | 主区域 | 渲染任务列表和状态。 | +| `DevicePanel` | 侧栏 | 展示设备状态、当前步骤、截图。 | +| `LogPanel` | 底部 | 展示运行日志。 | +| `ManualActionDialog` | 弹窗 | 人工接管原因和后续动作。 | + +## 导航规则 + +- 启动程序后直接进入主窗口，不做登录页。 +- 未导入 Excel 时，开始按钮不可用。 +- 未连接 Android 设备时，开始执行前给出明确提示。 +- 执行中允许查看表格和日志，但不允许重新导入覆盖当前任务。 +- 批次执行结束后，显示结果文件路径。 + + + + + diff --git a/progress.md b/progress.md new file mode 100644 index 0000000..e9bb103 --- /dev/null +++ b/progress.md @@ -0,0 +1,61 @@ +# 执行进度（Progress） + +> 本文记录任务执行进度、验证结果、阻塞点和关键决策。任务定义和依赖见 [`tasks.md`](tasks.md)，当前代码现实见 [`docs/current-state.md`](docs/current-state.md)。 +> +> **职责边界**：本文是**只追加的历史流水**——每次执行后追加一条带日期的记录，不回头改写或删除旧记录。需要"当前是什么样"的可覆盖快照（目录结构、可运行命令、下一个任务），看 [`docs/current-state.md`](docs/current-state.md)，不要在本文重复维护。 + +## 使用规则 + +- 每完成一个任务，追加一条进度记录。 +- 记录实际验证命令、真机验证情况和结果文件位置。 +- 遇到阻塞时记录阻塞原因、已尝试方案和下一步建议。 +- 不在本文重新定义任务范围；任务范围以 `tasks.md` 为准。 + +## 当前摘要 + +- 日期：2026-06-24 +- 阶段：MVP 起步 / 原型验证前 +- 当前任务：尚未开始编码 +- 下一个任务：`T-001 初始化 Python 项目骨架` +- 当前阻塞：尚未提供真实 Excel 样例、Android 真机和测试商品链接 + +## 进度记录 + +### 2026-06-24 · 文档初始化 + +- 完成：按 harness coding 文档风格建立项目文档集。 +- 完成：确认 MVP 形态为 Windows 桌面 GUI + Excel 导入/回写 + Android 真机自动化。 +- 完成：支付策略更新为默认人工确认，预留受控自动支付开关。 +- 完成：将任务定义移到根目录 `tasks.md`，新增根目录 `progress.md`。 +- 验证：文档结构和引用已通过文本搜索检查。 + +### 2026-06-24 · 文档一致性补丁 + +- 新增根目录 `.gitignore`：忽略 `logs/`、`artifacts/`、`samples/*.xlsx`、结果文件和虚拟环境，防止提交含 PII 的运行产物。 +- 统一 `TaskStatus` 中英映射：`04-architecture.md` §3.4 新增英文枚举成员 ↔ 中文显示值表，明确中文只在 GUI/Excel 边界出现。 +- 消解自动支付口径冲突：支付模式收敛为全局 `PaymentConfig`，从 `OrderTask` 移除 `auto_pay_enabled`；`api.md` 的 `enable_auto_pay` 改为 `set_payment_config`。 +- 明确暂停语义：`04-architecture.md` §4.5 新增 `RunnerState`（执行器级 `PAUSED`），与任务级 `status` 分离；`api.md` 补 `TaskRunner.pause()/resume()`。 +- 验证：全文搜索确认无 `auto_pay_enabled` / `enable_auto_pay` 残留引用。 + +### 2026-06-24 · 文档可维护性补丁（中优先级） + +- 新增 `CLAUDE.md`：薄入口指向 `AGENTS.md`，Claude Code 与 Codex 共用一套规则，避免双份漂移。 +- 钉死 `progress.md` 与 `current-state.md` 职责边界：前者为只追加历史流水，后者为可覆盖当前快照，二者顶部各加边界声明。 +- T-001 受理条件补充：要求用真实可运行命令替换各文档中的占位符验证命令。 + +### 2026-06-24 · 合规风险留痕（低优先级 item 9） + +- `02-requirements.md` §七 新增「平台规则与合规风险」一条：中立记录对第三方 App 做批量自动化下单可能触及平台协议/账号风控的已知风险，交叉引用 `01-vision.md` 非目标与 `05-coding-rules.md` 安全纪律；明确 MVP 不提供任何规避平台限制能力，使用范围与账号风险由业务方评估承担。 + +## 阻塞与风险 + +- 真实 Excel 表头待提供。 +- ADB 和 Android 真机连接待验证。 +- 拼多多商品详情页、SKU 面板、订单确认页结构待真机验证。 +- 订单号读取位置待支付后真机验证。 + +## 下一步 + +1. 按 `tasks.md` 领取 `T-001 初始化 Python 项目骨架`。 +2. 初始化项目后同步更新 `docs/current-state.md`。 +3. 完成任务后在本文追加验证结果。 diff --git a/tasks.md b/tasks.md new file mode 100644 index 0000000..a543a6e --- /dev/null +++ b/tasks.md @@ -0,0 +1,86 @@ +# 任务看板（Tasks） + +> 把 MVP 拆成小步、可独立交付的任务，让 AI 一步一步开发，避免一次生成整个项目。 + +## 使用规则 + +1. **一次只做一个任务**：每轮只领取一个状态为 `TODO`、且依赖均已 `DONE` 的任务，取最靠前的那个。 +2. **做完即停**：完成该任务、自测通过、把状态改成 `DONE` 后，停下来汇报。 +3. **不跳步**：依赖未完成的任务不能开工。 +4. **完成定义**：以 [编码规则](docs/05-coding-rules.md) 的验证清单为准。 +5. **动手前**先读 `docs/00-ai-start-here.md`、`docs/05-coding-rules.md`、`docs/current-state.md` 和 `progress.md`。 + +## 状态图例 + +`TODO` 待开始 · `DOING` 进行中（同一时间最多 1 个）· `DONE` 已完成并验收 · `BLOCKED` 受阻（注明原因） + +--- + +## Phase 0 · 地基 + +| ID | 任务 | 依赖 | 验收要点 | 状态 | +| --- | --- | --- | --- | --- | +| T-001 | 初始化 Python 项目骨架 | - | 建立 `src/`、`tests/`、`requirements.txt`；可运行最小入口；不引入无关依赖；用**真实可运行命令**替换 `00-ai-start-here.md`、`03-tech-stack.md`、`05-coding-rules.md`、`current-state.md` 中的占位符验证命令 | TODO | +| T-002 | 建立核心数据模型和状态枚举 | T-001 | `OrderTask`、`TaskStatus` 与 `04-architecture.md` 一致；有基础单元测试 | TODO | +| T-003 | 建立日志和运行产物目录策略 | T-001 | 日志、截图、UI XML 输出路径清晰；不记录敏感信息 | TODO | + +## Phase 1 · 最高风险验证 + +| ID | 任务 | 依赖 | 验收要点 | 状态 | +| --- | --- | --- | --- | --- | +| T-101 | 验证 ADB 和 `uiautomator2` 真机连接 | T-001 | 能列出设备、截图、dump UI XML；失败时有明确错误 | TODO | +| T-102 | 验证打开商品链接并跳转拼多多 App | T-101 | 输入一个商品链接后，真机进入对应商品详情页或记录失败原因 | TODO | +| T-103 | 验证购买入口和 SKU 面板识别 | T-102 | 能识别并打开 SKU 面板，保存截图和 UI XML 证据 | TODO | +| T-104 | 验证单条 SKU 文本选择 | T-103 | 能按明确 SKU 文本选择规格；匹配失败不盲点 | TODO | +| T-105 | 验证执行到支付前校验和默认暂停 | T-104 | 能进入订单确认/支付前节点，读取关键确认信息，并默认进入 `待人工` 状态 | TODO | + +## Phase 2 · Excel 与 GUI 核心流程 + +| ID | 任务 | 依赖 | 验收要点 | 状态 | +| --- | --- | --- | --- | --- | +| T-201 | 实现 Excel 表头校验和任务导入 | T-002 | 固定表头可读；缺列报错；空行/非法数量有明确提示 | TODO | +| T-202 | 实现最小 PySide6 主窗口 | T-001 | 有导入按钮、任务表格、日志区域、当前截图区域 | TODO | +| T-203 | 将 Excel 导入接入 GUI 表格 | T-201, T-202 | 导入后展示任务；可勾选；状态列可更新 | TODO | +| T-204 | 实现任务执行器骨架 | T-002, T-203 | 按选中顺序执行模拟任务；支持开始、暂停、取消状态 | TODO | +| T-205 | 接入 Android 单条真实执行流程 | T-105, T-204 | 单条任务可从 GUI 触发并执行到支付前校验和默认暂停 | TODO | +| T-206 | 实现结果 Excel 回写 | T-201, T-204 | 默认生成 `_执行结果.xlsx`；写入状态、订单号、失败原因、时间、截图路径 | TODO | + +## Phase 3 · 批量执行与异常处理 + +| ID | 任务 | 依赖 | 验收要点 | 状态 | +| --- | --- | --- | --- | --- | +| T-301 | 实现批量顺序执行 | T-205, T-206 | 只执行勾选任务；逐条更新 GUI 和结果 Excel | TODO | +| T-302 | 实现人工接管与继续 | T-301 | 遇到 `待人工` 可暂停；用户处理后可继续或标记失败 | TODO | +| T-303 | 完善失败分类和截图/UI XML 归档 | T-301 | SKU 失败、设备断开、页面识别失败、安全校验等有明确失败原因 | TODO | +| T-304 | 支持订单号读取或人工录入兜底 | T-302 | 成功后能记录订单号；自动读取失败时可人工录入并回写 | TODO | +| T-305 | 实现受控自动支付开关 | T-304 | 显式开启后仅在二次校验和金额上限通过时继续支付；安全校验转人工 | TODO | + +## Phase 4 · 收尾与交付 + +| ID | 任务 | 依赖 | 验收要点 | 状态 | +| --- | --- | --- | --- | --- | +| T-401 | 完整验收 MVP | T-305 | `02-requirements.md` 的 P0 验收全部通过；真机验证记录写入 `progress.md` 和 `docs/current-state.md` | TODO | +| T-402 | 打包 Windows 可执行程序 | T-401 | 运营电脑可运行；依赖和 ADB 环境说明清楚 | TODO | +| T-403 | 编写运营使用说明 | T-402 | 说明 Excel 格式、连接手机、执行、人工接管、结果文件位置 | TODO | + +## 里程碑 + +- M1：Python 桌面项目地基完成。 +- M2：真机控制拼多多核心链路已验证。 +- M3：Excel 导入、GUI 展示、单条任务执行和回写完成。 +- M4：批量执行、异常处理、人工接管和受控自动支付完成。 +- M5：可交付运营试用。 + +## 待办池（Backlog） + +- 多 Android 设备管理和任务调度。 +- OCR 兜底识别。 +- SQLite 任务库。 +- Web 管理后台。 +- 结果统计和报表。 +- 自动更新程序。 + + + + +