Table of Contents

架构与代码地图

项目定位
代码地图
两条主要执行路径

商品采集
真实采购（不支付）

不可破坏的边界

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

架构与代码地图

项目定位

cmautobuy 把采购员在 Admin 上的商品、规格和任务管理，与 Client 在 Android PDD App 上的采集和真实下单（不支付）串成一个可追溯闭环。Admin 是调度器和业务数据主库，Client 是设备执行器。

代码地图

位置	作用	修改前先读
`admin/main.go`、`admin/internal/app/`	Admin 启动和依赖装配	`admin/AGENTS.md`
`admin/internal/handler/`	Web/API 请求解析与响应	Admin 接口、界面文档
`admin/internal/service/`	导入、同步、匹配、任务等业务逻辑	对应需求和数据模型
`admin/internal/repository/`	MySQL/迁移数据访问	Admin 数据模型
`admin/templates/`、`admin/static/`	服务端页面和静态资源	Admin UI 规范
`client/src/ui_main.py`、`_ui.py`、`_ui_event.py`	Client 窗口、页面和事件装配	`client/AGENTS.md`
`client/src/gateway.py`	Admin HTTP 边界	Client API 契约
`client/src/repository.py`	Client SQLite 和 Outbox	Client 数据模型
`client/src/pdd_*adapter.py`、`select_color_size.py`	Android 页面识别、规格选择和采购执行	Client 质量与安全
`dev_scripts/`	Wiki/Harness 与发布辅助	开发工作流
`docs/task/`	2026-08-26 前历史归档及按需快照	默认只读

查代码符号时优先使用项目代码知识图谱；不足时再使用 rg 搜索字面量、配置和非代码文件。

两条主要执行路径

商品采集

Admin 创建采集任务
→ Client 登记并领取
→ Android 打开 PDD 商品页并采集标题/店铺/颜色/尺码/价格
→ Client 先写 SQLite 与 Outbox
→ Client 提交 Admin
→ Admin 幂等落库并更新任务与关联商品

真实采购（不支付）

Admin 创建采购任务并指定可见 Client
→ Client 只有在身份、设备、live 执行器就绪时领取
→ 复核商品、颜色、尺码、数量、总价上限
→ 不可逆前写 task_runs 标记
→ PDD 创建未付款订单
→ 只读核对订单编号和下单时间
→ 提交 Admin，等待人工审核和付款

规格无法确定时允许 Client 向 Admin 提交当前页面候选，Admin 用确定性规则或 AI 返回建议；Client 仍必须在页面上复核后才能继续。

不可破坏的边界

根 AGENTS.md 的五条红线不能被文档迁移或重构削弱。
Admin 只调度，Client 只执行；Client 不在任务中途查询 Admin 状态。
Client API 契约以 Client 侧文档为唯一事实来源。
Handler 不写业务逻辑和 SQL；Repository 才能写业务 SQL。
Qt 主线程不执行 HTTP、ADB、uiautomator2、休眠或大文件操作。
任务进入 irreversible_action_at 后只准核单，绝不重新下单。
金额用整数分，时间用带时区 ISO 8601，结果提交必须幂等。
Wiki 是长期文档主源，本地 docs/ 只是带 revision 的版本镜像。