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/00-ai-start-here.md
+131
View File
@@ -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 自动化后跑：真机连接测试和最小链路测试。
- 如果命令当前不可运行，必须在回复里如实说明原因。
docs/01-vision.md
+48
View File
@@ -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)。
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 内提供任何规避平台限制的能力。
docs/03-tech-stack.md
+72
View File
@@ -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、抓包改包等依赖。
docs/04-architecture.md
+358
View File
@@ -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` 和相关任务验收。
- 支付逻辑必须受显式开关、二次校验和金额上限控制。
- 安全校验、验证码、风控逻辑只能进入人工接管分支。
docs/05-coding-rules.md
+97
View File
@@ -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. 拿不准就问
问题要具体，说明你卡在哪里、有哪些选项、倾向哪个选项以及原因。
docs/README.md
+33
View File
@@ -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` 进入。
docs/api.md
+198
View File
@@ -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 列。
- 导入时遇到部分行错误，是阻止全部导入还是只标记错误行。
- 自动读取订单号失败时的人工录入流程。
- 批量执行失败后默认继续下一条还是暂停批次。
- 受控自动支付的默认单笔金额上限、批次金额上限和允许价格偏差。
docs/current-state.md
+88
View File
@@ -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`。
- 新增可运行命令。
- 发现文档和代码现实不一致。
docs/routes.md
+96
View File
@@ -0,0 +1,96 @@
# 界面结构
> 本项目是桌面 GUI，不使用 Web 路由。本文约定主窗口区域、页面职责和组件归属。
## 主窗口布局
```text
┌──────────────────────────────────────────────────────────┐
│ 顶部工具栏：导入 Excel | 开始 | 暂停 | 继续 | 取消 | 人工接管 | 支付模式 │
├──────────────────────────────┬───────────────────────────┤
│ 任务表格 │ 当前设备 / 当前截图 │
│ - 勾选 │ - 设备状态 │
│ - 序号 │ - 当前步骤 │
│ - 商品链接 │ - 手机截图 │
│ - SKU 信息 │ │
│ - 数量 │ │
│ - 状态 │ │
│ - 订单号 │ │
│ - 失败原因 │ │
├──────────────────────────────┴───────────────────────────┤
│ 日志区域 │
└──────────────────────────────────────────────────────────┘
```
## 页面 / 区域职责
### 顶部工具栏
- 导入 Excel。
- 开始执行选中任务。
- 暂停当前批次。
- 继续人工处理后的任务。
- 取消后续任务。
- 进入人工接管状态。
- 配置支付模式：人工确认支付（默认）或受控自动支付。
按钮状态必须跟随任务执行状态变化，避免重复启动或误操作。
### 任务表格
- 展示导入的 Excel 任务。
- 支持勾选/取消勾选。
- 按当前展示顺序执行选中任务。
- 实时更新状态、订单号、失败原因。
- 行状态要清晰区分：待执行、执行中、待人工、成功、失败、已取消。
### 当前设备 / 当前截图
- 展示 Android 设备连接状态。
- 展示当前执行任务和步骤。
- 展示最近截图。
- 设备断开或截图失败时显示明确错误。
### 日志区域
- 展示任务级日志。
- 每条日志包含时间、任务 ID、步骤、结果。
- 不展示支付密码、短信验证码、账号密码等敏感信息。
### 人工接管交互
- 当系统进入 `待人工` 时，GUI 应明确展示原因。
- 用户可以在真机上手动处理。
- GUI 提供继续、标记成功、标记失败、取消批次等操作。
- 自动化不得在安全校验节点自行尝试绕过。
### 支付模式配置
- 默认模式为人工确认支付。
- 受控自动支付必须由用户显式开启。
- 开启时必须填写单笔金额上限；建议填写批次金额上限。
- GUI 应显示当前模式，执行中不得悄悄切换。
## 组件建议
| 组件 | 归属 | 说明 |
| --- | --- | --- |
| `MainWindow` | 全局 | 主窗口和整体布局。 |
| `Toolbar` | 全局 | 导入、开始、暂停、继续、取消、人工接管、支付模式。 |
| `TaskTable` | 主区域 | 渲染任务列表和状态。 |
| `DevicePanel` | 侧栏 | 展示设备状态、当前步骤、截图。 |
| `LogPanel` | 底部 | 展示运行日志。 |
| `ManualActionDialog` | 弹窗 | 人工接管原因和后续动作。 |
## 导航规则
- 启动程序后直接进入主窗口，不做登录页。
- 未导入 Excel 时，开始按钮不可用。
- 未连接 Android 设备时，开始执行前给出明确提示。
- 执行中允许查看表格和日志，但不允许重新导入覆盖当前任务。
- 批次执行结束后，显示结果文件路径。