chengmaandClaude Opus 4.8
c204fc205c
- 现象：Windows(Python 3.7) python -m src.main 报 No module named 'src'， 即便 cwd 在项目根、src/__init__.py 存在。 - 根因：该环境运行时不把当前目录加入 sys.path，python -m 找不到 cwd 下的 src 包。 - 修复： - src/main.py 启动时自注入项目根到 sys.path，不依赖运行环境配置； - 运行方式从 python -m src.main 改回脚本方式 python src/main.py； - dev.bat 恢复 CRLF 行尾并改用 python src\main.py； - 00/03/05/current-state 文档命令同步。 验证：WSL 下从不含 src 的目录脚本方式运行 exit=0；unittest 17 passed。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
131 lines
5.1 KiB
Markdown
131 lines
5.1 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` 的当前真实命令。
|
||
|
||
## 验证命令
|
||
|
||
项目骨架已初始化（T-001）。当前可运行的真实验证命令（Windows 运营机用 `python`，Linux/WSL 开发用 `python3`）：
|
||
|
||
```powershell
|
||
python -m compileall src
|
||
python -m unittest discover -s tests -t .
|
||
python src/main.py
|
||
```
|
||
|
||
说明：
|
||
|
||
- 改 GUI 后跑：启动桌面程序并手动验证主流程。
|
||
- 改 Excel 处理后跑：单元测试和样例 Excel 导入/回写测试。
|
||
- 改 Android 自动化后跑：真机连接测试和最小链路测试。
|
||
- 如果命令当前不可运行，必须在回复里如实说明原因。
|
||
|
||
|
||
|
||
|