132 lines
5.0 KiB
Markdown
132 lines
5.0 KiB
Markdown
|
# 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 自动化后跑：真机连接测试和最小链路测试。
|
|||
|
|
- 如果命令当前不可运行，必须在回复里如实说明原因。
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
|