docs: 同步 P5 备份机制重写——DEPLOY §5 / API §13 / DATA_MODEL §7 / DEVELOPMENT §4.3

- DEPLOY §5.1: 说明 SQLite 现在是「备份交换格式」，恢复走单事务整库替换，
  跨环境导入默认拒绝；§5.2 覆盖清单改为「由 metadata 派生」；§5.3 三个目录
  支持环境变量覆盖及原因
- API §13: 导出/预览/应用三个接口的字段补齐（db_backend/deployment_env/
  source_db_id/source_env/current_env、force_env_mismatch、pre_restore zip）
- DATA_MODEL §7: pre_restore 改 .zip、补目录可覆盖说明
- DEVELOPMENT §4.3: 补三个备份目录环境变量

doc/API.md

@@ -610,37 +610,49 @@
 
 ### POST /api/system/backup/export
 
-**JSON body**（不是表单）：`{"include_apks": false}`。响应为 **zip 附件**：
+**JSON body**（不是表单）：`{"include_apk": true}`（默认 true）。响应为 **zip 附件**：
 
 ```
-users.db           # sqlite 在线备份 API 做的一致快照
-apks/*.apk         # include_apks=true 时
-manifest.json      # {format:"auto_control_backup", version, created_at, schema_version,
-                   #  include_apk, tables:[{table,label,rows}], apks:[…], coverage_missing?}
+users.db           # 当前库（MySQL 或回退 SQLite）整库一致快照成的 SQLite 归档
+apks/*.apk         # include_apk=true 时
+manifest.json      # {format:"auto_control_backup", version:2, created_at, schema_version,
+                   #  db_backend, deployment_env, source_db_id, include_apk,
+                   #  tables:[{table,label,rows}], apks:[…], coverage_missing?}
 ```
 
+> SQLite 在这里是**备份交换格式**而非运行时库：MySQL 下导出时把连接提到 REPEATABLE READ，
+> 保证 12 张表读的是同一时刻。
+
 ### POST /api/system/backup/preview
 
 multipart 上传 `.zip` 或 `.db`（字段 `file`）→ 校验并暂存：
 
 ```json
 {"ok": true, "token": "e172dc75e2f7",
- "preview": {"integrity": "ok", "schema_version": 4, "current_schema_version": 4,
-             "tables": [{"table":"agent_action","label":"动作库","rows":4}],
+ "preview": {"integrity": "ok", "schema_version": 6, "current_schema_version": 6,
+             "source_env": "dev", "current_env": "dev", "source_backend": "mysql",
+             "source_db_id": "704fbbb0…",
+             "tables": [{"table":"agent_action","label":"动作库","rows":5}],
              "missing_optional": [], "extra_tables": [],
-             "warnings": ["备份为全量快照，含用户口令哈希、AI 控制台 API Key 等敏感信息…"]}}
+             "warnings": ["备份为全量数据，含用户口令哈希、AI 配置里的 API Key 等敏感信息…"]}}
 ```
 
 - 完整性 `PRAGMA integrity_check` 必须 `ok`；缺必需表（`app_meta`/`user`/`task_job`/`device_group`）直接拒绝
-- `extra_tables` 非空 = 备份含**未登记进覆盖清单**的表（提示去登记）
+- `extra_tables` 非空 = 备份含**未登记的表**（提示去登记）
+- `source_env` ≠ `current_env` 时 `warnings` 会多一条跨环境告警
 - 暂存 **TTL 30 分钟**，过期自动清理
 - 文件非法 / 未选文件 → 400
 
 ### POST /api/system/backup/apply
 
-`{"token":"…"}` → 先自动把当前库快照到 `data/backups/pre_restore_<ts>.db`（安全网），再把暂存库落到 `data/restore_pending/`。
+`{"token":"…", "force_env_mismatch": false}` → 先自动把当前库导出成
+`data/backups/pre_restore_<ts>.zip`（安全网，可直接再导入回来），再把暂存归档落到
+`data/restore_pending/`。
 
-**必须重启服务才生效**（`web_server.py` 在 `init_db` 之前消费该目录）。token 无效/暂存缺失 → 400。
+- **必须重启服务才生效**：`web_server.py` 在 `init_db` 之后、`TaskManager` 之前消费该目录
+- 重启时**单事务整库替换**（DELETE 全表 + 分块 INSERT），失败自动回滚，当前数据不受影响
+- 备份来源环境与当前库不符时**默认拒绝**（400），要跨环境须显式传 `force_env_mismatch: true`
+- token 无效/暂存缺失 → 400
 
 ---