<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Architecture-and-Code-Map
wiki_url: https://git.ilapage.cn/OPC/cmautobuy/wiki/Architecture-and-Code-Map.-
wiki_revision: 85497cc74dcd6f45d81d2a2806c5425b625f9c2d
synchronized_at: 2026-08-26T08:42:40Z
<!-- gitea-wiki-mirror:end -->

# 架构与代码地图

## 项目定位

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` 搜索字面量、配置和非代码文件。

## 两条主要执行路径

### 商品采集

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

### 真实采购（不支付）

```text
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 的版本镜像。