Files

T

chengma d130e2675e docs: 初始化核心 Wiki 镜像 (#313 )

2026-08-26 16:45:54 +08:00

3.3 KiB

Raw Permalink Blame History

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

架构与代码地图

项目定位

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

3.3 KiB Raw Permalink Blame History Unescape Escape