cmpdd/docs/00-ai-start-here.md

AI 开发入口

给 AI coding agent 的项目入口。这里负责导航和流程，硬性编码规则见 05-coding-rules.md。

一句话定位

拼多多批量下单执行器是一个内部运营桌面 GUI 工具，通过 Excel 批量导入已审核任务，控制 Android 真机在拼多多 App 中选择 SKU、下单，并把订单号和执行结果回写到 Excel。

第一版 MVP 只做：单机、单 Android 真机、固定表头 Excel、自动选择 SKU 和提交订单、默认支付前人工确认、预留受控自动支付开关、异常人工接管、结果回写。

必读顺序

每次开始写代码前，按这个顺序建立上下文：

1. 01-vision.md：为什么做、为谁做、什么不做。
2. 02-requirements.md：MVP 要什么、怎么算达成。
3. 03-tech-stack.md：既定技术选型。
4. 04-architecture.md：系统结构、职责划分、数据模型和关键难点。
5. 05-coding-rules.md：写代码前必须遵守的规则。
6. ../tasks.md：领取本轮唯一任务。
7. current-state.md：当前代码现实、可运行命令、下一步入口。
8. ../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 领取任务时：

• 只领取第一个状态为 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 的当前真实命令。

验证命令

当前项目尚未初始化代码。初始化后应在这里补充真实命令：

# 计划命令，待项目初始化后确认
python -m pytest
python -m compileall src
python src/main.py

说明：

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