docs/00-ai-start-here.md

# 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` 的当前真实命令。

## 验证命令

项目骨架已初始化（T-001）。当前可运行的真实验证命令（Windows 运营机用 `python`，Linux/WSL 开发用 `python3`）：

```powershell
python -m compileall src
python -m unittest discover -s tests -t .
python -m src.main
```

说明：

- 改 GUI 后跑：启动桌面程序并手动验证主流程。
- 改 Excel 处理后跑：单元测试和样例 Excel 导入/回写测试。
- 改 Android 自动化后跑：真机连接测试和最小链路测试。
- 如果命令当前不可运行，必须在回复里如实说明原因。