docs: 同步 P1/P2——DATA_MODEL 重写引擎/建表/迁移/唯一索引/覆盖清单章节，ARCHITECTURE 更新装配顺序与数据库决策

- DATA_MODEL §1: 引擎改为「MySQL（正式）/SQLite（回退）」+ 连接参数 + 环境与库名绑定表；
  表清单注明 12 张全部是 ORM 模型（原 5 张裸表已并入）
- §4 重写: 建表/补列以模型为准（create_all + _sync_columns），补 §4.2.1 说明
  排序规则为何必须 utf8mb4_bin；唯一索引补 MySQL 的「生成列 + 唯一索引」方案
- §5 补 deployment_env/deployment_id/deployment_claimed_at 三个键
- §6 覆盖清单改为「由 metadata 派生」，红线只剩补 TABLE_LABELS
- ARCHITECTURE: 装配阶段 B/C/D 更新（db_config 装配 + 环境校验横幅）、
  §3.2 并发描述按方言改写、§7 数据库决策表改写

doc/DATA_MODEL.md

@@ -2,7 +2,7 @@
 
 > 适用读者：改后端 / 排数据问题的开发者与运维。
 > 相关文档：[ARCHITECTURE.md](ARCHITECTURE.md)（运行时架构）、[DEPLOY.md](DEPLOY.md) §数据备份（备份覆盖红线）、[API.md](API.md)（消费这些数据的接口）。
-> **表结构以 `core/models.py` 与各模块的建表 SQL 为准**，本文是它们的映射说明。
+> **表结构以 `core/models.py` 的 ORM 模型为唯一准**（2026-09-13 起各模块的裸建表 SQL 已全部并入模型），本文是它们的映射说明。
 
 ---
 
@@ -10,32 +10,49 @@
 
 | 项 | 值 |
 |----|----|
-| 引擎 | 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` |
+| 引擎 | MySQL（正式用法；目标由 `.env` 的 `DEPLOY_ENV` + `DB_*` 决定）／SQLite（回退模式，`DB_HOST` 为空时） |
+| driver | Flask-SQLAlchemy（SQLAlchemy 2.x）+ PyMySQL |
+| 连接参数 | 见 `core/db_config.py`：utf8mb4、排序规则 `utf8mb4_bin`、`pool_pre_ping`、`pool_recycle=1800`、隔离级别 READ COMMITTED、`sql_mode=STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION` |
+| SQLite 回退时的 PRAGMA | `journal_mode=WAL`、`busy_timeout=5000`、`synchronous=NORMAL`（监听器按连接类型守卫，MySQL 连接不会执行） |
+| 建表方式 | **唯一真相是模型**：`db.create_all()`（建缺表）+ `_sync_columns()`（补缺列）；`SCHEMA_MIGRATIONS` 只作版本账本与数据回填 |
+| 库位置 | MySQL：由 `DB_HOST/DB_NAME` 指定；SQLite：`data/users.db` |
+| 当前 schema 版本 | `app_meta.schema_version = 6` |
 
-**表清单（12 张业务表 + 1 张 SQLite 内部表）**
+**环境与库的绑定**（防混库，见 [DEPLOY.md](DEPLOY.md) §2.2）
 
-| # | 表 | 来源 | 用途 |
-|---|---|------|------|
-| 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_` 前缀排除） |
+| `DEPLOY_ENV` | 期望库名 | 用途 |
+|---|---|---|
+| `dev` | `auto_control_dev` | 本地开发 |
+| `prod` | `auto_control` | 正式环境（220 容器） |
 
-> **没有外键、没有关系（relationship）、没有索引**：全部靠应用层维护一致性。分组 ↔ 设备是多对多的 **JSON 列表**（`device_group.serials`），删除设备不会级联清理分组里的 serial。
+启动时校验「`.env` 声明」与「库名」「库中登记的 `app_meta.deployment_env`」三方一致，不符**拒绝启动**。
+
+**表清单（12 张，全部是 `core/models.py` 里的 ORM 模型）**
+
+| # | 表 | 用途 |
+|---|---|------|
+| 1 | `user` | 登录用户与权限 |
+| 2 | `device_group` | 设备分组（JSON 存 serial 列表） |
+| 3 | `task_job` | 任务计划 |
+| 4 | `custom_action` | 自定义动作（可复用步骤包） |
+| 5 | `apk_file` | APK 记录 |
+| 6 | `device` | 设备池 |
+| 7 | `pending_device` | 待确认的发现设备 |
+| 8 | `app_meta` | KV 配置（schema 版本、AI 配置、发现配置、库环境标签） |
+| 9 | `agent_conversation` | AI 控制台会话 |
+| 10 | `agent_experience` | 经验库（任务级配方） |
+| 11 | `experience_audit` | 经验巡检结论 |
+| 12 | `agent_action` | 动作库（命名动作） |
+
+> 2026-09-13 之前，`app_meta` 与 4 张 `agent_*` 表是各模块里的裸 `CREATE TABLE`
+> （不进模型层）。迁 MySQL 时那批 SQL 的 `AUTOINCREMENT`/`TEXT DEFAULT ''`/`TEXT PRIMARY KEY`
+> 全都建不出来，而异常被 `except: pass` 吞掉 —— 表现为「经验库/动作库静默失灵」。
+> 现在全部升为模型，建表只有一条路径。
+
+> **没有外键、没有关系（relationship）**：全部靠应用层维护一致性。分组 ↔ 设备是多对多的
+> **JSON 列表**（`device_group.serials`），删除设备不会级联清理分组里的 serial。
+>
+> **唯一索引只有两个**（设备名 / 指纹，见 §4.2），且都是「空值不参与唯一约束」的语义。
 
 ---
 
@@ -140,50 +157,64 @@
 | `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）。
+> 2026-09-13 起这四张表**已升为 ORM 模型**（见 §1 的说明），建表统一走 `db.create_all()`。
 
 ---
 
 ## 4. 迁移机制
 
-### 4.1 版本化迁移 `SCHEMA_MIGRATIONS`
+### 4.1 建表与补列（以模型为准）
 
-| 版本 | 内容 | 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()`：
+| 步骤 | 做什么 | 幂等性 |
+|------|--------|--------|
+| `db.create_all()` | 建**缺的表**（模型里有的都在） | 幂等 |
+| `_sync_columns()` | 用 `sqlalchemy.inspect` 比对模型与实表，**补实表缺的列** | 幂等 |
+| `_migrate_schema()` | 维护 `app_meta.schema_version` 账本 + 执行数据回填 | 幂等 |
+| `_ensure_unique_indexes()` | 建设备名/指纹唯一索引（见 §4.2） | 幂等 |
+| `_ensure_default_admin()` | 首次创建 `admin/admin123` | 幂等 |
+| `_migrate_old_json()` | 旧 `groups.json`/`jobs.json` 一次性迁移 | 见 §4.3 |
 
-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 日志，**不阻塞启动**
+> 2026-09-13 之前，补列靠 `ALTER TABLE` 报错文本里有没有 `duplicate column name` 来判断
+> 「列已存在」——那是 SQLite 时代的写法，换方言（MySQL 的错误码/文本都不同）就失效了。
+> 现在改为直接读数据库元数据比对，**缺什么补什么，两种方言一套代码**。
 
 ### 4.2 唯一索引（设备身份）
 
-`_migrate_schema()` 末尾会补建两个**部分唯一索引**（幂等，与版本号无关，老库升级时也会补）：
+两个「空值不参与唯一约束」的唯一索引，与版本号无关，每次启动都补建：
 
 | 索引 | 作用 |
 |------|------|
-| `ux_device_name` | 设备**名称唯一**（`WHERE name <> ''`，兼容历史空名） |
-| `ux_device_fingerprint` | **一台物理设备在池中只有一条记录**（`WHERE fingerprint <> ''`） |
+| `ux_device_name` | 设备**名称唯一**（空名不参与，兼容历史未命名设备） |
+| `ux_device_fingerprint` | **一台物理设备在池中只有一条记录**（空指纹不参与） |
+
+实现按方言分叉（`_ensure_unique_indexes()`）：
+
+- **SQLite**：直接用带 `WHERE name <> ''` 的**部分索引**
+- **MySQL 5.7**：不支持过滤索引，改用「**虚拟生成列 + 唯一索引**」——
+  生成列把空值映射成 `NULL`（`IF(col IS NULL OR col='', NULL, col)`），
+  而唯一索引允许多个 `NULL`，正好等于「空值不参与唯一」。生成列名 `name_uq` /
+  `fingerprint_uq`，**只由 DDL 添加、不进 ORM 模型**（进了 `create_all` 会尝试写入
+  它并报 Error 3105）。
 
-> 用**部分索引**而不是表级约束：历史数据可能有空名称/空指纹，`<> ''` 让它们不参与唯一性判断。
 > 若历史数据里已有重复（建索引失败），只告警不回滚、不阻塞启动——约束从此刻起对新数据生效，
 > 老的重复行由管理页「改名」处理。
 
+### 4.2.1 排序规则为什么必须是 `utf8mb4_bin`
+
+SQLite 的文本比较是**逐字节**的（大小写敏感）。MySQL 默认的 `utf8mb4_general_ci`
+是大小写**不**敏感，会让 `Admin`/`admin`、`Phone1`/`phone1` 被判成重复，唯一索引和
+等值查询语义全变。所以库、表、连接三处都统一用 `utf8mb4_bin`（逐码点比较，对合法
+UTF-8 等价于字节序）。
+
+唯一的语义差异：`LIKE` 在 `_bin` 下是大小写敏感的（SQLite 对 ASCII 默认不敏感）。
+当前代码里没有任何 `LIKE`/`ilike` 查询，暂无影响。
+
 ### 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` 键清单
@@ -200,37 +231,37 @@
 | `discovery_subnets` | 扫描网段 JSON 数组 | 同上 |
 | `discovery_interval` | 扫描周期秒（10-3600） | 同上 |
 | `discovery_port` | adb 探测端口（1-65535） | 同上 |
+| `discovery_auto_claim` | 指纹匹配时自动认领（`"1"`/`"0"`，默认关） | 同上 |
+| `deployment_env` | **库环境标签**（`dev`/`prod`），启动时与 `.env` 比对 | `core/db_config.py`（首次连接）/ 迁移脚本 |
+| `deployment_id` | 库唯一标识（uuid），用于识别"这份备份来自哪个库" | 同上 |
+| `deployment_claimed_at` | 标签写入时间 | 同上 |
 
 > ⚠️ `agent_api_key` 是**明文存储**，导出备份的 zip 里也含它——备份预览会固定给出"含敏感信息"告警。
+> `app_meta` 的列名 `key` 在 MySQL 里是保留字，**不要直接拼裸 SQL**，统一走
+> `core/db_config.meta_get / meta_set`（方言中立、自动加引号）。
 
 ---
 
 ## 6. 备份覆盖清单（红线）
 
-`core/system_backup.py` 的 `SUMMARY_TABLES`（12 张，与库中实际业务表一一对应）：
+`core/system_backup.py` 的 `SUMMARY_TABLES` **由模型元数据派生**：
 
-| 表 | 中文标签 |
-|----|---------|
-| `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` | 动作库 |
+```python
+SUMMARY_TABLES = tuple(sorted(t.name for t in db.metadata.tables.values()))
+```
+
+也就是说——**新增一张 ORM 表，自动就进备份覆盖清单**，不可能再漏。
+`TABLE_LABELS`（预览页的中文标签）仍是手工维护，缺标签时回退显示表名。
 
 **双向自检**：
 
 - **导出侧**：登记在 `SUMMARY_TABLES` 但快照里缺失 → 写入 `manifest.coverage_missing` + 日志告警
-- **导入侧**：备份里出现未登记的表（排除 `sqlite_` 前缀）→ 预览告警"请登记进 `core/system_backup.py` 的覆盖清单"（字段 `extra_tables`）
-- `REQUIRED_TABLES = (app_meta, user, task_job, device_group)`：缺任一直接拒绝导入
+- **导入侧**：备份里出现未登记的表（排除 `sqlite_` 前缀）→ 预览告警（字段 `extra_tables`）
+- `REQUIRED_TABLES = (app_meta, user, task_job, device_group)`：缺任一直接拒绝导入（这四项是"判定这是不是本平台备份"的最小集合，故意手工维护）
 
-> **红线**：**新增任何持久化表（含原生建表的 agent 类表），必须同时登记进 `SUMMARY_TABLES` 与 `TABLE_LABELS`**，并更新 [DEPLOY.md](DEPLOY.md) §数据备份。历史教训：`agent_action` 曾漏登记，导致"动作库看起来没备份"（数据其实在快照里，只是清单没列）。
+> **红线**：新增持久化表时**同时补 `TABLE_LABELS` 的中文标签**并更新 [DEPLOY.md](DEPLOY.md) §数据备份。
+> 覆盖清单本身不再需要手工登记（已由 metadata 派生）。历史教训：`agent_action` 曾漏登记，
+> 导致"动作库看起来没备份"（数据其实在快照里，只是清单没列）。
 
 ---
 
@@ -238,7 +269,7 @@
 
 | 路径 | 内容 | 进 git |
 |------|------|--------|
-| `data/users.db`(+`-wal`/`-shm`) | SQLite 主库 | 否 |
+| `data/users.db`(+`-wal`/`-shm`) | SQLite 主库（**仅回退模式用**；连 MySQL 时这些文件不被读写，可留作历史归档） | 否 |
 | `data/apks/*.apk` | 上传的 APK | 否 |
 | `data/backups/` | 导出临时 zip、`pre_restore_*.db`（导入前安全网）、`restore_failed_*` | 否 |
 | `data/restore_staging/<token>/` | 导入暂存（TTL 1800s 自动清理） | 否 |