auto_control/doc/DATA_MODEL.md

数据模型（DATA_MODEL）

适用读者：改后端 / 排数据问题的开发者与运维。 相关文档：ARCHITECTURE.md（运行时架构）、DEPLOY.md §数据备份（备份覆盖红线）、API.md（消费这些数据的接口）。 表结构以 core/models.py 的 ORM 模型为唯一准（2026-09-13 起各模块的裸建表 SQL 已全部并入模型），本文是它们的映射说明。

---

1. 总览

项	值
引擎	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 = 11（迁移清单见 core/models.py 的 SCHEMA_MIGRATIONS：建表/补列以模型为准，这里只作版本账本）

环境与库的绑定（防混库，见 DEPLOY.md §2.2）

DEPLOY_ENV	期望库名	用途
dev	auto_control_dev	本地开发
prod	auto_control	正式环境（220 容器）

启动时校验「.env 声明」与「库名」「库中登记的 app_meta.deployment_env」三方一致，不符拒绝启动。

表清单（17 张，全部是 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	动作库（命名动作）
13	device_install_log	设备端应用商店的下载/安装记录（设备上报，见 DEVICE_AGENT.md）
14	task_step_log	任务步骤明细（每次步骤执行一条，见 §2.8；唯一有无界增长风险的表，靠保留期清理）
15	done_mark	去重账本：跨设备"已做过"标记（见 §2.9；本清单此前漏列，2026-09-24 补上）
16	device_account	已停用：账号台账（见 §2.10；2026-10-12 起页面/接口/任务依赖全部下线，表和 42 行历史数据保留、仍在备份内，可回滚）
17	video_plan	视频发布计划：名字 × 发布日期 × 编号 → 素材 + 标题/正文 + 发布状态 + 分享链接（见 §2.11）

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），且都是「空值不参与唯一约束」的语义。

---

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 后据此认领回原记录
cur_account_name / cur_name_at	String(80)/String(20)	""	上次探测到的抖音当前账号名字（迁移 v13 追加）：只有「按名字找设备」（计划页的推送）会写它。纯缓存 —— 自动任务永远现场读屏幕，缓存旧了也不影响发布的正确性；界面上带时间戳显示

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。

2.8 task_step_log — 任务步骤明细

每一次步骤执行一条（tasks/generic/task.py:_exec_one 里记录），是「日志 → 步骤明细」 页的数据源。与 logs/task.log 的分工：那边是排障原文（什么都写、10MB 滚动）， 这边是结构化的一份——设备/任务/步骤/结果/耗时都是列，能过滤、能统计、能导出 CSV。

列	类型	默认	说明
id	Integer	—	主键
run_id	String(24)	""	一次运行 = 设备 × 任务 × 第几次尝试；TaskManager._run_with_retry 每次尝试生成一个（12 位 hex），把这次尝试的所有步骤串起来
job_id / job_name	String(32/120)	""	任务快照（任务删了明细还在，名字仍可读）
serial / device_name	String(120/80)	""	设备地址与当时的名字（快照，改名不影响历史）
step_path	String(32)	""	嵌套位置，如 2.1.3；容器步骤（loop/group/if_el）会记自己那条，children 追加一级
step_label / step_type	String(120/40)	""	步骤标签与类型（click_el/loop/wait…）
selector	String(300)	""	元素选择器（长选择器截断）
result	String(16)	""	ok / miss（handler 返回 False）/ error（抛异常）/ unknown（未知步骤类型）/ skip（概率未触发）/ cap（本次运行已达上限）
detail	String(500)	""	异常消息、跳过原因等
duration_ms	Integer	0	本步耗时（慢步骤一眼可辨）
created_at	String(20)	""	执行时刻（保留期按它算）

索引：run_id、created_at、(serial, created_at)、(job_id, created_at)。

两条硬边界（都在 core/step_log.py）：

常量	默认	作用
MAX_ROWS_PER_RUN	2000	单次运行最多记 2000 条，超出只补一条 cap 说明行。没有它，forever 循环任务会瞬间写爆这张表
KEEP_DAYS	14	保留期：每天 04:13（+ 每次启动）清理更早的记录

⚠️ 这张表是唯一有无界增长风险的表，而它会自动进整库备份（§6 的派生规则）， 所以 KEEP_DAYS 直接决定备份包体积。调大之前先想清楚导出的 zip 会有多大。

写入走 core/step_log.py 的专用写线程 + 有界队列（任务线程只 put_nowait， 微秒级；队列满丢弃并计数）——步骤执行是热路径，绝不能在任务线程里同步写库。

2.9 done_mark — 去重账本（跨设备"已做过"）

列	类型	说明
id	Integer PK
scope_key	String(300) UNIQUE	幂等的全部依据：任务ID | 身份值 | 时间桶
kind	String(12)	day / hours / all（有效期策略，任务级 dedup_reset）
job_id	String(32) idx	哪个任务
job_name	String(120)
serial / device_name	String	哪台设备（界面上显示"谁做过了"）
identity	String(200)	身份值（如抖音号 35377983067）
created_at	String(20) idx

索引：job_id、created_at、(job_id, created_at)。

为什么靠唯一索引：多台设备会同时判断"没做过"，"先查后插"有竞态（两台都插）； 唯一索引 + INSERT ... ON DUPLICATE KEY/INSERT OR IGNORE 的受影响行数才是原子的。 实现在 core/dedup.py（check / mark / list_marks / delete_mark / clear_job / purge_old）。

保留期：每天 04:23 清理过保留期（core/dedup.KEEP_DAYS，默认 180 天）的记录， 但只清 day/hours 桶——kind='all'（"只做一次"）清了就等于去重失效，永不清理。 量级很小（设备数 × 天数），单条 DELETE 足够，不需要像步骤明细那样分批。

⚠️ 这张表自动进整库备份（§6 派生规则）；接任务步骤见 TASK_DEV.md §4.6。

2.10 device_account — 账号台账（已停用，表保留）

2026-10-12：账号管理整块下线。 页面（「账号」页）、接口（/api/ledger*）、 服务层（core/ledger.py 已删）、任务取号（cmp_source=device/all/group）、 设备端身份页的账号块（accounts_b64）、设备池的「账号 N」列全部移除。

为什么留着表和这 42 行数据：删数据不可逆，而这张表在备份清单里（红线：功能涉及的数据 必须纳入备份）—— 先停用、确认稳定后再单开一次清理动作。 发布计划改走名字（见 §2.11），不再需要台账。

唯一从 core/ledger.py 迁走的是 serial_of(设备名) → 当前地址（与账号无关）， 现在在 core/device_pool.py。

历史结构（停用前）：一台设备上登录着哪些账号。「账号」页维护。

列	类型	说明
id	String(32) PK	uuid 前 8 位
device_name	String(80) index	设备号（= 设备池里的设备名，如 A01）
serial	String(120)	录入时的地址快照（设备换 IP / 改名后台账仍能靠任一侧找回）
phone	String(32) index	手机号
nickname	String(80)	账号名称
douyin_id	String(64) index	抖音号（纯号），如 35377983067
registered_at	String(20)	注册时间（原样存文本，如 2026/9/24）
sim_in_device	Boolean	卡在机内（空 = 否）
can_post_video	Boolean	可发视频（空 = 否）
bio / note	Text	简介 / 备注
created_at / updated_at	String(20)	字符串时间（仓库惯例）

（停用前的）三个使用方：① web「账号」页（列表/增删改/从 Excel 粘贴导入）； ② 任务「条件判断」取号（cmp_source=device/all/group）；③ 手机端 Agent 的身份大字页（accounts_b64）。 三个都已移除；发布计划现在按名字走（§2.11）。

⚠️ 历史提醒：douyin_id 是纯号，绝不能当去重身份（done_mark.identity 存的是元素原文、 逐字算 key，格式不一致会让去重静默失效）—— 这是当年 cmp_source 取号的边界， 现在候选值来自"本次要发的名字"，同理不得拿去填 ident_value。

这张表仍在整库备份内（§6 派生规则）—— 停用不等于删数据。

2.11 video_plan — 视频发布计划（一个名字在某天要发的一个视频）

「发布计划」页维护；服务层 core/video_plan.py，接口 /api/video_plan/*（见 API.md §2.14）， 任务步骤「发布视频」按它自动发布（见 TASK_DEV.md §4.7）。 **素材文件（视频/图片）**落在 data/videos/YYYY-MM/（文件名 {sha1[:12]}_{安全原名}，内容寻址），不进整库备份（§6）。

列	类型	说明
id	String(32) PK	uuid 前 8 位
nickname	String(80)	识别键：上传文件名里的名字（= 抖音昵称）。运行时就按它取计划、找设备/账号
account_id / phone / douyin_id / device_name / serial	String	已停用（老台账快照，保留列不再写入）：账号 id / 手机号 / 抖音号 / 设备号 / 地址
release_date	String(10) index	2026-09-12 纯日期（等值比较走索引）
seq / seq_auto	Integer / Boolean	编号从 1 起（不用 0 表示"无"）；seq_auto=号是自动分配的
title	Text	标题（发布页的「标题」框；标题 txt 配对写入）
body	Text	正文/文案（发布页的文案框，可带 #话题）—— 标题 txt 一行里用 `
video_file / video_name / video_size / video_sha1	各自	素材（视频或图片，看扩展名）：落盘相对路径 / 原始名 / 大小 / 内容指纹（重复上传判据）。推送时扩展名原样带到手机——抖音按它判断视频还是图文
status	String(16) index	见下方状态机
stage	String(16)	失败发生在哪一步：push/scan/post/verify
attempts	Integer	尝试次数（上限 3，超了不再自动取）
published_at / share_url / link_at / video_deleted_at	String	发布时刻 / 作品分享链接 / 抓到链接的时刻 / 素材何时清理
push_verify / push_remote	String(16)/String(200)	推送后的相册校验：ok=已进相册索引 / no_index=文件在但没进索引（相册里可能看不到）/ nofile=文件不在；push_remote = 推到手机上的绝对路径（删它、排查用）。文件推上去了 ≠ 相册里点得到它，所以单独存一列而不是混进 last_error
posted_serial / posted_device_name	String(120)/String(80)	实际是哪台设备发的（推送时现场写）。计划不再绑设备，所以"这条最后是谁发的"只能这么记 —— 排查"怎么发到那台机器上去了"全靠它
last_error / note / created_at / updated_at		失败原因 / 人工备注 / 时间

状态机（本表的灵魂，别简化）：

pending    有视频、还没标题              ready      素材齐，等推送
pushing    已推到手机（等人/用户的步骤去发）  done       已发布（终态）
skipped    人工跳过（终态）              failed     推送阶段就失败 —— 还没到抖音，**可安全重试**
unknown    推送之后出的岔子 —— **可能已经发出去了，绝不自动重试**，要人工裁决

平台只负责把素材推到手机（push_release 步骤 / 计划页「推送到手机」）： 推文件 → 触发相册刷新 → 把标题写进手机剪贴板。抖音里怎么发由用户在任务画布上自己写， 最后放一个 mark_release「标记发布结果」回写这里的状态（published→done、failed、unknown）。 这样抖音改版时用户改自己的步骤即可，不用等平台发版。

⚠ failed 与 unknown 必须分开：把"不知道自己发没发"混成"知道自己没发"， 就是重复发布的来源。stage 是两者互相转换的唯一依据（core/video_plan.STAGE_STATUS）。 界面上的 unknown 卡片标橙 + 硬提示，人工到抖音确认后点「已发出 / 未发出」裁决。

唯一性：(nickname, release_date, seq) 由服务层保证，不加 DB 唯一索引 —— seq 从 1 起、没有"空值"可言，做部分唯一索引要写三处方言适配 + MySQL 生成列（§4.2）， 收益不匹配；违反的代价只是低频人工上传产生的重复行（可见、可删）。

索引：(release_date,status) 时间线主查询 · (nickname,release_date) 按名字取计划/查重（主路径）· (account_id,release_date) · (phone,release_date,seq) 老台账路径（已停用，保留）· (video_file) 清理时反查引用。 后三个里带 account_id/phone 的两个是历史遗留（账号台账停用后不再走），等确认稳定后一并清理。 ix_video_plan_name_date 由 _ensure_plain_indexes() 在启动时补建（create_all 不管已有表的新索引）。

这张表自动进整库备份（§6 派生规则）；素材文件不进备份包，见 §6 与 §7。

---

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

2026-09-13 起这四张表已升为 ORM 模型（见 §1 的说明），建表统一走 db.create_all()。

---

4. 迁移机制

4.1 建表与补列（以模型为准）

模型定义是唯一真相。启动时：

步骤	做什么	幂等性
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

2026-09-13 之前，补列靠 ALTER TABLE 报错文本里有没有 duplicate column name 来判断 「列已存在」——那是 SQLite 时代的写法，换方言（MySQL 的错误码/文本都不同）就失效了。 现在改为直接读数据库元数据比对，缺什么补什么，两种方言一套代码。

4.2 唯一索引（设备身份）

两个「空值不参与唯一约束」的唯一索引，与版本号无关，每次启动都补建：

索引	作用
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 仍在 → 直接归档，防止"用户删空数据后重启又复原"。

---

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）	同上
agent_task_draft	AI 建任务最近一份任务草稿（JSON {draft,warnings,prompt,created}，只留最近一份、超限自动瘦身）。不是任务：入库仍要用户在步骤编辑器确认后走 POST /api/jobs	AI 建任务页 / submit_task 工具
discovery_enabled	自动发现开关（"1"/"0"）	工具页「设备池管理」
discovery_subnets	扫描网段 JSON 数组	同上
discovery_interval	扫描周期秒（10-3600）	同上
discovery_port	adb 探测端口（1-65535）	同上
discovery_auto_claim	指纹匹配时自动认领（"1"/"0"，默认关）	同上
agent_store_enabled	设备端应用商店开关（"1"/"0"，默认关）	应用管理页
agent_device_token	设备端令牌（Agent 调设备接口用；属凭据）	同上（启用时自动生成，可重置）
agent_device_token_at	令牌生成/重置时间	同上
deployment_env	库环境标签（dev/prod），启动时与 .env 比对	core/db_config.py（首次连接）/ 迁移脚本
deployment_id	库唯一标识（uuid），用于识别"这份备份来自哪个库"	同上
deployment_claimed_at	标签写入时间	同上
notify_webhooks	通知 / Webhook 全部配置（JSON：{version, settings, webhooks[]}，见 NOTIFY.md §4）。不建表——新增/删除 webhook 都只改这一个键	系统 → 通知 页
step_defaults	步骤默认值（JSON：{步骤类型: {字段: 值}}，见 TASK_DEV.md §3.1）。新建步骤时预填用。只存与出厂值不同的字段，这样以后调出厂默认能跟着走	任务 → 动作配置 页
device_battery	电量监控配置（JSON：{enabled, low, critical, skip_charging, interval}，见 NOTIFY.md §3.1）。只存与出厂值不同的字段（出厂：low=20 critical=10 skip_charging=true interval=60）。电量本身不落库——只放采集线程的内存缓存（重启重新采一轮），所以没有对应表、不动备份覆盖清单	工具 → 设备发现 → 电量监控

⚠️ agent_api_key 是明文存储，导出备份的 zip 里也含它——备份预览会固定给出"含敏感信息"告警。 同理 notify_webhooks 里的 webhook URL 本身就是凭据（企业微信 ?key=、钉钉 ?access_token=、 飞书 /hook/<token>）：拿到它就能往群里发消息。接口回显/发送记录/日志一律走 notifier.mask_url()/scrub() 打码，导出备份时也按敏感信息对待。 app_meta 的列名 key 在 MySQL 里是保留字，不要直接拼裸 SQL，统一走 core/db_config.meta_get / meta_set（方言中立、自动加引号）。

---

6. 备份覆盖清单（红线）

core/system_backup.py 的 SUMMARY_TABLES 由模型元数据派生：

SUMMARY_TABLES = tuple(sorted(t.name for t in db.metadata.tables.values()))

也就是说——新增一张 ORM 表，自动就进备份覆盖清单，不可能再漏。 TABLE_LABELS（预览页的中文标签）仍是手工维护，缺标签时回退显示表名。

双向自检：

• 导出侧：登记在 SUMMARY_TABLES 但快照里缺失 → 写入 manifest.coverage_missing + 日志告警
• 导入侧：备份里出现未登记的表（排除 sqlite_ 前缀）→ 预览告警（字段 extra_tables）
• REQUIRED_TABLES = (app_meta, user, task_job, device_group)：缺任一直接拒绝导入（这四项是"判定这是不是本平台备份"的最小集合，故意手工维护）

素材文件不进备份包：create_export() 只打包 data/apks/*.apk，不含 data/videos/ （几十 GB 会把"数据库备份"这个核心能力搞坏）。备份的 manifest.json 里有 videos.included=false + 数量/字节数，备份预览页也会提示"素材需另外备份 data/videos/" —— 不能让人以为备份了。恢复后素材要重新上传（计划与发布状态、分享链接都在表里，已备份）。

红线：新增持久化表时同时补 TABLE_LABELS 的中文标签并更新 DEPLOY.md §数据备份。 覆盖清单本身不再需要手工登记（已由 metadata 派生）。历史教训：agent_action 曾漏登记， 导致"动作库看起来没备份"（数据其实在快照里，只是清单没列）。

---

7. 数据目录

路径	内容	进 git
data/users.db(+-wal/-shm)	SQLite 主库（仅回退模式用；连 MySQL 时这些文件不被读写，可留作历史归档）	否
data/apks/*.apk	上传的 APK	否
data/videos/YYYY-MM/*	视频发布计划的素材（几百 MB 一个；不进整库备份，见 §6）	否
data/backups/	导出临时 zip、pre_restore_*.zip（导入前安全网）、restore_failed_*	否
data/restore_staging/<token>/	导入暂存（TTL 1800s 自动清理）	否
data/restore_pending/	待生效恢复任务（重启时单事务消费）	否

后三个目录可用环境变量改到别处（DATA_BACKUP_DIR / DATA_RESTORE_STAGING_DIR / DATA_RESTORE_PENDING_DIR）——自动化测试必须这么做，否则测试造的待生效恢复任务 会被服务当成用户的操作在下次重启时消费掉。 | 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 红线）。