butubb/auto_control
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0a1b4d61229f5f229a195cf62fe27af5b86a3518
auto_control/doc/DATA_MODEL.md
T
butubb 0a1b4d6122 feat: 设备身份改为「名称 + 指纹」——更换 IP 自动认领，分组/任务引用自动同步 
背景：设备池原先拿 serial（IP）当身份。设备一换 IP（DHCP 重新分配）旧记录就成了连不上的
僵尸条目（表现为"断联·自动重连中"但设备并没关机），分组与 serial 模式的任务还吊着死地址。
2026-09-11 实际发生：.70 变成 .71、.72 消失，平台两个条目永远连不上。

实现
- **设备名称必填且唯一**：加入设备必须填名称；库层面用部分唯一索引兜底
  （ux_device_name / ux_device_fingerprint，WHERE 非空 → 兼容历史空值），管理页可改名
- **设备指纹**（ro.serialno）：网络设备添加/确认/扫描/采集型号时自动读取；
  身份三层拆分——名称（人可读，稳定）、指纹（机器识别，稳定）、serial（当前地址，可变）
- **自动认领**：添加或确认设备时指纹命中池中已有记录 → 迁移原记录到新地址
  （名称/型号/备注/启用状态/添加时间全保留），不新增条目
- **人工认领** `POST /api/devices/pool/relocate`：旧地址已断联、指纹没采过时的兜底——
  人工指认"这条就是那台，现在在 X"，迁移并同步引用
- **引用同步**：认领/迁址时把 device_group.serials 与 task_job.target.serial 的旧地址
  换成新地址。⚠️ 必须同时改**内存**：分组/任务在 TaskManager 里另有内存副本且调度用内存对象，
  只改库不重启不生效 → device_pool 迁址后回调 TaskManager.sync_device_serial
  （装配层用 set_move_hook 注册；device_pool 不能反向 import task_manager，会循环依赖）
- **前端**：待连接池新增「识别」列（指纹命中时提示"≈ 名称（原 IP）"，按钮变「认领为 X」）；
  设备池新增「名称/指纹」列与「改名/换地址」操作；断联设备表也加「换地址」（用户看到断联就在这里）
- 添加设备接口改用 adb_connect_light（单次短超时），避免不可达 IP 让请求卡 30s+；重名校验提前到 adb 之前

文档：API.md §6 重写（设备身份/认领/新接口）、DATA_MODEL.md（新列 + v5/v6 迁移 + 唯一索引）、
ARCHITECTURE.md §4.0（身份三层与引用同步的内存坑）、DEPLOY.md 排查表加"断联但没关机"条目

自测（全通过）：名称必填/唯一/改名/重名拒绝（含库层面约束）；指纹采集（真实读到 .71 的
gy7lskwkkvj7c6b6）；自动认领（指纹命中→迁址+保留名称+带指纹+未命中不误判）；人工认领
（迁址+名称保留+分组与任务引用同步）；浏览器验证设备池/断联表/待连接池三个界面
2026-09-11 11:03:38 +08:00

264 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
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.
# 数据模型（DATA_MODEL）
> 适用读者：改后端 / 排数据问题的开发者与运维。
> 相关文档：[ARCHITECTURE.md](ARCHITECTURE.md)（运行时架构）、[DEPLOY.md](DEPLOY.md) §数据备份（备份覆盖红线）、[API.md](API.md)（消费这些数据的接口）。
> **表结构以 `core/models.py` 与各模块的建表 SQL 为准**，本文是它们的映射说明。
---
## 1. 总览
| 项 | 值 |
|----|----|
| 引擎 | SQLite（单文件 `data/users.db`） |
| driver | Flask-SQLAlchemy（SQLAlchemy 2.x） |
| 连接 PRAGMA | `journal_mode=WAL`、`busy_timeout=5000`、`synchronous=NORMAL` |
| 建表方式 | ① 模型表：`db.create_all()`；② 版本化迁移 `SCHEMA_MIGRATIONS`；③ 幂等原生 `CREATE TABLE IF NOT EXISTS` |
| 主库文件 | `data/users.db`（运行时另有 `-wal` / `-shm`） |
| 当前 schema 版本 | `app_meta.schema_version = 4` |
**表清单（12 张业务表 + 1 张 SQLite 内部表）**
| # | 表 | 来源 | 用途 |
|---|---|------|------|
| 1 | `user` | 模型 | 登录用户与权限 |
| 2 | `device_group` | 模型 | 设备分组（JSON 存 serial 列表） |
| 3 | `task_job` | 模型 | 任务计划 |
| 4 | `custom_action` | 模型 | 自定义动作（可复用步骤包） |
| 5 | `apk_file` | 模型 | APK 记录 |
| 6 | `device` | 模型 + 迁移 v2/v3 | 设备池 |
| 7 | `pending_device` | 模型 + 迁移 v4 | 待确认的发现设备 |
| 8 | `app_meta` | 原生（迁移前建） | KV 配置（schema 版本、AI 配置、发现配置） |
| 9 | `agent_conversation` | 原生（`web/agent_api.py`） | AI 控制台会话 |
| 10 | `agent_experience` | 原生（`web/agent_api.py`） | 经验库（任务级配方） |
| 11 | `experience_audit` | 原生（`web/agent_api.py`） | 经验巡检结论 |
| 12 | `agent_action` | 原生（`web/agent_api.py`） | 动作库（命名动作） |
| — | `sqlite_sequence` | SQLite 内部 | `AUTOINCREMENT` 的附带产物（备份自检时按 `sqlite_` 前缀排除） |
> **没有外键、没有关系（relationship）、没有索引**：全部靠应用层维护一致性。分组 ↔ 设备是多对多的 **JSON 列表**（`device_group.serials`），删除设备不会级联清理分组里的 serial。
---
## 2. 模型表（`core/models.py`）
### 2.1 `user` — 登录用户
| 列 | 类型 | 默认 | 说明 |
|----|------|------|------|
| `id` | Integer | — | 主键 |
| `username` | String(80) | — | **唯一**，非空 |
| `password_hash` | String(255) | — | werkzeug 加盐哈希；兼容旧裸 SHA-256（校验通过后自动升级） |
| `is_admin` | Boolean | `True` | 管理员不受权限位限制 |
| `perms` | Text | `"[]"` | JSON 数组：`tasks` / `devices` / `apks` / `logs` |
方法：`get_perms` / `set_perms` / `has_perm` / `set_password` / `check_password`。
### 2.2 `device_group` — 设备分组
| 列 | 类型 | 默认 | 说明 |
|----|------|------|------|
| `id` | Integer | — | 主键 |
| `name` | String(80) | — | **唯一**，非空 |
| `serials` | Text | `"[]"` | 组内设备 serial 的 JSON 数组 |
| `description` | Text | `""` | 备注 |
### 2.3 `task_job` — 任务计划
| 列 | 类型 | 默认 | 说明 |
|----|------|------|------|
| `id` | String(32) | — | 主键，uuid 前 8 位 |
| `name` | String(120) | — | 非空 |
| `task_type` | String(60) | `"generic_steps"` | 必须已注册 |
| `target` | Text | `'{"mode":"all"}'` | JSON |
| `params` | Text | `"{}"` | JSON（与任务类默认值合并后使用） |
| `schedule` | Text | `'{"mode":"once"}'` | JSON |
| `retry` | Text | `'{"max_attempts":1,"delay":60}'` | JSON |
| `enabled` | Boolean | `True` | 是否参与调度 |
### 2.4 `custom_action` — 自定义动作
| 列 | 类型 | 默认 | 说明 |
|----|------|------|------|
| `id` | String(32) | — | 主键 |
| `name` | String(120) | — | 非空 |
| `icon` | String(4) | `"📦"` | 展示图标 |
| `steps` | Text | `"[]"` | JSON，schema 与 `generic_steps` 的 `params.steps` 一致 |
| `created_at` | String(20) | `""` | 时间串 |
### 2.5 `apk_file` — APK 记录
| 列 | 类型 | 默认 | 说明 |
|----|------|------|------|
| `id` | String(32) | — | 主键；磁盘文件名为 `<id>.apk` |
| `filename` | String(255) | — | 原始文件名 |
| `display_name` / `package_name` / `version_name` | String | `""` | 解析结果 |
| `version_code` / `size` | Integer | `0` | |
| `upload_time` | String(20) | `""` | |
### 2.6 `device` — 设备池
| 列 | 类型 | 默认 | 说明 |
|----|------|------|------|
| `serial` | String(120) | — | 主键：`IP:5555` 或 USB 序列号 |
| `name` | String(80) | `""` | 备注名 |
| `model` | String(120) | `""` | 型号（迁移 v3 追加） |
| `enabled` | Boolean | `True` | 停用则不参与调度 |
| `note` | Text | `""` | |
| `created_at` | String(20) | `""` | |
| `fingerprint` | String(120) | `""` | **设备指纹**（`ro.serialno`，迁移 v5 追加）：同一台物理设备换 IP 后据此认领回原记录 |
### 2.7 `pending_device` — 待确认的发现设备
| 列 | 类型 | 默认 | 说明 |
|----|------|------|------|
| `serial` | String(120) | — | 主键 |
| `source` | String(20) | `""` | `lan` / `tailscale` |
| `first_seen` / `last_seen` | String(20) | `""` | 时间串 |
| `fingerprint` | String(120) | `""` | 扫描时读取的设备指纹（迁移 v6 追加），用于提示"这是已有设备换了地址" |
> ⚠️ SQLAlchemy 模型的 `default=` 是 **Python 侧默认值**，SQLite 建表语句里没有 `DEFAULT` 子句；只有原生建表的表才有真正的 SQL DEFAULT。
---
## 3. 非模型表
### 3.1 `app_meta` — KV 配置
| 列 | 类型 |
|----|------|
| `key` | TEXT PRIMARY KEY |
| `value` | TEXT |
由 `_migrate_schema()` 建表（启动必执行）。**所有键见 §5**。
### 3.2 AI 相关四张表（`web/agent_api.py`，原生建表）
| 表 | 列 |
|----|----|
| `agent_conversation` | `id`(PK) · `title` · `messages`(JSON) · `created_at` · `updated_at` |
| `agent_experience` | `id`(PK AUTOINCREMENT) · `task_prompt` · `recipe` · `tool_seq` · `hits` · `created_at` |
| `experience_audit` | `id`(PK) · `exp_id` · `verdict`(keep/delete) · `score`(REAL) · `reason` · `hits` · `action`(pending/kept/deleted) · `audited_at` |
| `agent_action` | `id`(PK) · `name` · `app` · `aliases`(JSON) · `params`(JSON) · `steps`(JSON) · `preconditions` · `hits` · `source_prompt` · `created_at` · `updated_at` |
> ⚠️ 这四张表**不走 `SCHEMA_MIGRATIONS`，无版本管理**，由各模块首次使用时 `CREATE TABLE IF NOT EXISTS` 幂等创建；建表失败会被 `except: pass` 吞掉（后续 SQL 才会报错）。新增此类表时，务必同时登记进备份覆盖清单（§6）。
---
## 4. 迁移机制
### 4.1 版本化迁移 `SCHEMA_MIGRATIONS`
| 版本 | 内容 | SQL 幂等性 |
|------|------|-----------|
| 1 | `user` 增加 `perms` | `ALTER TABLE`（非幂等，靠 duplicate column 兜底） |
| 2 | 建 `device` 表（**无 `model` 列**） | 幂等（`IF NOT EXISTS`） |
| 3 | `device` 增加 `model` | `ALTER TABLE`（同上兜底） |
| 4 | 建 `pending_device` 表 | 幂等 |
| 5 | `device` 增加 `fingerprint`（设备指纹） | `ALTER TABLE`（靠 duplicate column 兜底） |
| 6 | `pending_device` 增加 `fingerprint` | 同上 |
执行器 `_migrate_schema()`：
1. 先 `CREATE TABLE IF NOT EXISTS app_meta(...)`（幂等）
2. 读 `app_meta.schema_version`（缺省 0）
3. 只执行 `version > current` 的迁移；**SQL 报 `duplicate column name` 时回滚该语句但仍记版本号**（自愈：`create_all` 已建列而版本未记录时不再卡住），其它异常才抛出
4. 每条迁移后 `INSERT OR REPLACE app_meta('schema_version', v)` 并提交
5. 整体包 try：失败只记 error 日志，**不阻塞启动**
### 4.2 唯一索引（设备身份）
`_migrate_schema()` 末尾会补建两个**部分唯一索引**（幂等，与版本号无关，老库升级时也会补）：
| 索引 | 作用 |
|------|------|
| `ux_device_name` | 设备**名称唯一**（`WHERE name <> ''`，兼容历史空名） |
| `ux_device_fingerprint` | **一台物理设备在池中只有一条记录**（`WHERE fingerprint <> ''`） |
> 用**部分索引**而不是表级约束：历史数据可能有空名称/空指纹，`<> ''` 让它们不参与唯一性判断。
> 若历史数据里已有重复（建索引失败），只告警不回滚、不阻塞启动——约束从此刻起对新数据生效，
> 老的重复行由管理页「改名」处理。
### 4.3 旧 JSON 迁移（一次性）
启动时若存在 `data/groups.json` / `data/jobs.json`：对应表为空则导入，随后把文件重命名为 `<name>.json.migrated` 归档。**库非空但 JSON 仍在 → 直接归档**，防止"用户删空数据后重启又复原"。
`init_db(app)` 顺序：`db.init_app` → `create_all()` → `_migrate_schema()` → `_ensure_default_admin()`（首次创建 `admin/admin123`）→ `_migrate_old_json()`。
---
## 5. `app_meta` 键清单
| key | 用途 | 写入方 |
|-----|------|--------|
| `schema_version` | 迁移版本游标 | `core/models.py` |
| `agent_api_base` | AI 接口地址 | AI 控制台配置页 |
| `agent_model` | 模型名 | 同上 |
| `agent_api_key` | API Key（**明文存库**） | 同上 |
| `agent_default_serial` | 默认目标设备 | 同上 |
| `agent_max_steps` | 最大步数（钳制 1-200，默认 40） | 同上 |
| `discovery_enabled` | 自动发现开关（`"1"`/`"0"`） | 工具页「设备池管理」 |
| `discovery_subnets` | 扫描网段 JSON 数组 | 同上 |
| `discovery_interval` | 扫描周期秒（10-3600） | 同上 |
| `discovery_port` | adb 探测端口（1-65535） | 同上 |
> ⚠️ `agent_api_key` 是**明文存储**，导出备份的 zip 里也含它——备份预览会固定给出"含敏感信息"告警。
---
## 6. 备份覆盖清单（红线）
`core/system_backup.py` 的 `SUMMARY_TABLES`（12 张，与库中实际业务表一一对应）：
| 表 | 中文标签 |
|----|---------|
| `app_meta` | 系统配置(app_meta) |
| `user` | 用户 |
| `device_group` | 设备分组 |
| `task_job` | 任务计划 |
| `custom_action` | 自定义动作 |
| `apk_file` | APK 记录 |
| `device` | 设备池 |
| `pending_device` | 待连接设备 |
| `agent_conversation` | AI 会话 |
| `agent_experience` | 经验库 |
| `experience_audit` | 经验巡检 |
| `agent_action` | 动作库 |
**双向自检**：
- **导出侧**：登记在 `SUMMARY_TABLES` 但快照里缺失 → 写入 `manifest.coverage_missing` + 日志告警
- **导入侧**：备份里出现未登记的表（排除 `sqlite_` 前缀）→ 预览告警"请登记进 `core/system_backup.py` 的覆盖清单"（字段 `extra_tables`）
- `REQUIRED_TABLES = (app_meta, user, task_job, device_group)`：缺任一直接拒绝导入
> **红线**：**新增任何持久化表（含原生建表的 agent 类表），必须同时登记进 `SUMMARY_TABLES` 与 `TABLE_LABELS`**，并更新 [DEPLOY.md](DEPLOY.md) §数据备份。历史教训：`agent_action` 曾漏登记，导致"动作库看起来没备份"（数据其实在快照里，只是清单没列）。
---
## 7. 数据目录
| 路径 | 内容 | 进 git |
|------|------|--------|
| `data/users.db`(+`-wal`/`-shm`) | SQLite 主库 | 否 |
| `data/apks/*.apk` | 上传的 APK | 否 |
| `data/backups/` | 导出临时 zip、`pre_restore_*.db`（导入前安全网）、`restore_failed_*` | 否 |
| `data/restore_staging/<token>/` | 导入暂存（TTL 1800s 自动清理） | 否 |
| `data/restore_pending/` | 待生效恢复任务（重启时消费） | 否 |
| `data/mcp_audit.log` | MCP 调用审计（路径由 `MCP_AUDIT_FILE` 指定） | 否 |
| `data/uiauto.pid` | uiautodev 子进程 PID | 否 |
| `data/*.json.migrated` | 旧 JSON 迁移归档 | 否 |
| `logs/*.log` | 运行日志 | 否 |
> `data/` 与 `logs/` 全部是运行时产物，**任何文件都不入 git**。生产机上的库由「系统 → 数据备份导出/导入」或整目录手工备份。
---
## 8. 约定与注意事项
1. **主键用 uuid 前 8 位字符串**（`task_job` / `custom_action` / `apk_file` / `agent_conversation`）：可读性好，理论上有碰撞概率（8 位 hex = 32 bit）。
2. **JSON 字段一律 Text 存储**，读写通过 `get_*/set_*` 方法；解析失败回退默认值。
3. **时间统一为字符串**（`"YYYY-MM-DD HH:MM"` 或 `"YYYY-MM-DD HH:MM:SS"`），排序依赖字符串序。
4. **删除必须显式删行**（`delete_job` / `delete_group`）：只 upsert 会导致重启后数据"复活"。
5. **跨线程访问 DB 必须自推 app context**（后台线程里用 `with app.app_context()`）。
6. **不要手工改库结构**：走 `SCHEMA_MIGRATIONS`（模型表）或幂等建表（原生表），否则 `create_all` 与版本号会不一致。
7. **改表结构后记得**：① 更新本文；② 若是新表，登记备份覆盖清单（§6 红线）。
Reference in New Issue View Git Blame Copy Permalink