80 lines
4.6 KiB
Markdown
80 lines
4.6 KiB
Markdown
# 架构与代码地图
|
||
|
||
## MVP 架构
|
||
|
||
```text
|
||
go-admin-ui
|
||
│ REST：PDD商品、规则、任务、任务详情
|
||
▼
|
||
go-admin Server ───────── 数据库
|
||
│ ├─ pdd_product
|
||
│ REST：注册/心跳/任务 ├─ collection_rule
|
||
│ ├─ collection_task（任务+结果）
|
||
▼ └─ dimension/value/color_price/sku 子表
|
||
Android Portal/Agent
|
||
├─ 注册、心跳与设备串行锁
|
||
├─ 领取指定任务或空闲领取未指定任务
|
||
├─ 执行任务内的 URL 与规则快照
|
||
└─ 提交结构化结果或明确错误
|
||
```
|
||
|
||
## 最小闭环
|
||
|
||
1. 管理员添加 PDD URL，服务端规范化 URL 并提取唯一 `goods_id`。
|
||
2. 管理员创建规则；规则创建后立即可用于创建任务。
|
||
3. 管理员从一个 PDD 商品创建任务，可指定设备，也可留空等待空闲设备领取。
|
||
4. 任务固化 URL、goods_id 和完整规则快照。
|
||
5. Android 串行执行并把结果写回同一条任务；规格与 SKU 写入任务结果子表。
|
||
6. 管理员只在任务详情查看结果，并可对终态任务执行重置。
|
||
|
||
## 关键设计
|
||
|
||
- `pdd_product.goods_id` 唯一；重复时提示商品已存在，不重复新增。
|
||
- 规则没有草稿、发布和版本流程；软删除只阻止创建新任务。
|
||
- 已有任务不依赖规则当前状态，始终执行自身 `rule_snapshot`。
|
||
- `collection_task` 同时保存任务生命周期和结果摘要，不建立 `collection_result` 主表。
|
||
- 同一 PDD 商品最多存在一个 `pending` 或 `running` 任务。
|
||
- 指定设备只能由该设备领取；未指定任务由在线空闲设备原子领取。
|
||
- 重置在事务中清空原结果，保留 URL、goods_id、规则和设备快照，状态恢复为 `pending`。
|
||
- Android 本地互斥与服务端原子领取共同保证单设备串行。
|
||
- 原始控件树和截图不持久化；第一期不使用 OCR/VLM。
|
||
|
||
## 最小业务数据
|
||
|
||
| 表 | 必要内容 |
|
||
|---|---|
|
||
| `agent_device` | 唯一 `install_id`、设备信息、状态、Token 摘要、版本化能力、最后心跳 |
|
||
| `pdd_product` | `id`、唯一 `goods_id`、当前 `url`、创建/更新时间 |
|
||
| `collection_rule` | `id`、`name`、`content_json`、创建/更新时间、`deleted_at` |
|
||
| `collection_task` | 商品/设备外键、五态状态、URL/goods_id/规则快照、租约、结果摘要、错误和时间 |
|
||
| `collection_dimension` | 任务、维度键、名称、排序 |
|
||
| `collection_dimension_value` | 维度、值、排序 |
|
||
| `collection_color_price` | 任务、颜色、该颜色统一使用的整数分价格 |
|
||
| `collection_sku` | 任务、整数分价格、可用性、完整性 |
|
||
| `collection_sku_value` | SKU 与规格值的多对多关联 |
|
||
|
||
`collection_task` 的状态仅为 `pending`、`running`、`completed`、`completed_partial`、`failed`。设备身份和心跳表属于 Agent 领取任务的必要基础，不承载 PDD 业务数据。
|
||
|
||
设备以 JSON 数组保存最后一次注册或心跳上报的版本化能力。v1 任务兼容未上报能力的旧 Agent；v2 任务在创建指定设备任务、获取下一任务、领取和开始四个边界重复校验能力，避免旧 APK 执行未知规则。
|
||
|
||
数据库使用两个可空 guard 列表达跨数据库唯一约束：活动任务的 `active_slot=1`，运行中设备的 `device_run_slot=1`；终态记录对应列为 `NULL`。复合唯一索引据此保证同商品最多一个活动任务、同设备最多一个运行中任务，同时允许保留任意数量的终态历史任务。状态与 guard 列还有数据库检查约束，必须在同一条状态变更语句中更新。
|
||
|
||
## 已建立的工程入口
|
||
|
||
| 功能 | 当前目录 |
|
||
|---|---|
|
||
| 服务端基线 | `server/`（go-admin v2.3.0） |
|
||
| 最小闭环数据模型 | `server/app/goauto/models/` |
|
||
| 数据迁移与约束测试 | `server/app/goauto/migrations/` |
|
||
| go-admin 迁移注册 | `server/cmd/migrate/migration/version-local/1786700000000_goauto_schema.go` |
|
||
| 设备注册、认证、停用与吊销 | `server/app/goauto/device/` |
|
||
| PDD 商品与规则 | `server/app/goauto/product/`、`server/app/goauto/rule/` |
|
||
| 任务领取、结果、重置与删除 | `server/app/goauto/task/` |
|
||
| 管理端基线 | `web/`（go-admin-ui v3.0.0） |
|
||
| 管理端闭环页面 | `web/src/views/goauto/` |
|
||
| Android Agent 基线 | `android/app/src/main/java/cn/ilapage/goauto/agent/` |
|
||
| Android 无障碍规则执行 | `android/app/src/main/java/cn/ilapage/goauto/agent/automation/` |
|
||
| 三端统一验证 | `scripts/verify.ps1` |
|
||
|
||
以上入口均已落地；新增 API、表或执行动作时必须同步更新本代码地图与共享契约。
|