# 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 项目骨架
```

开始。