Skip to content

七、数据结构与生命周期 ​

本章速览:读完后你会知道 —— ① 迁移为什么只能前进、163 个迁移怎么管理;② 100 张表按域怎么分组;③ 字段/主键/软删/时间/逻辑引用的约定;④ 哪些表会自动清理、哪些永久保留;⑤ 删除一条数据时会级联发生什么。

逐表列定义(列/类型/注释/索引)太大,放在 附录 M:数据字典;这里讲能指导设计与排障的规则: 迁移怎么走、表怎么分组、字段怎么约定、数据活多久、删除时会发生什么。

7.1 迁移与版本:只前进,不回改 ​

  • 结构变化只能新增 db/migration/V{n}__<说明>.sql;已有的迁移禁止修改(生产 flyway_schema_history 记录的是校验和,改旧文件会让应用启动失败)。
  • 当前 163 个迁移(V1 → V163,无缺号);发布前 deploy/scripts/test-migrations.sh 会在临时库 全量重放一遍,确认"从零建库"没问题。
  • 迁移里同时负责配置键种子(INSERT sys_config):配置键必须由迁移登记,运行期才允许写 (SysConfigServiceImpl.saveBatch 会拒绝未登记的键,见 6.2)。
  • 删除表/列要先确认没有读点:用"搜代码 + 查文档 + 看生产行数"三条都过一遍再写迁移; 历史出现的"删表后旧 Job 还在写"就是靠这道检查兜住的。

7.2 表分组(100 张,按域) ​

域张数前缀内容
AI 与记忆27ai_*对话/轮次/知识库/向量块/记忆事件/关系状态/关怀/仪式/叙事/出网账本/用量/迁移游标
扩展平台现存 24 张extension_*(23)+ webhook_delivery包/版本/安装/触发器/运行/能力/策略/效果/审批/密钥/预算/自愈
博客内容14blog_*文章/历史/标签关系/页面/说说/相册/照片/评论/留言/友链/分类/标签/系列/片段
系统13sys_*配置/用户/文件/文件夹/审计/登录/任务/邮件/搜索/订阅/访问/部件/API Key
会话与采集7agent_*会话/轮次/原始行/采集账本/工具调用/轮次附件/采集令牌
日程5daily_*待办/重复系列/课次/节假日/提醒
笔记5note_*笔记/笔记本/标签/标签关系/历史
通知与主动4notify_*(2)+ proactive_log + proactive_compose通道/投递留痕/主动账本/预润色缓存
其它1chat_attachment聊天附件元数据(消息本体在 ai_message)

表名清单由文档检查器与生产库逐表核对(100 张全覆盖);每张表的列定义在附录 M。

7.3 字段与建表约定 ​

约定做法为什么
主键雪花 BIGINT(id),对外 JSON 转字符串单机无自增冲突;JS 不丢精度
软删deleted TINYINT(0/1)+ 查询默认过滤内容可恢复;日志类不软删(直接按保留期物理删)
时间create_time/update_time DATETIME 由 DB 默认值维护;业务时间 Asia/Shanghai统一口径;扩展平台调度时间例外(存 UTC)
无物理外键引用列只建索引,关系由应用层维护避免迁移顺序/锁表;删父前必须显式处理子行
自然键/幂等各表用唯一索引做幂等:dedup_key、natural_key、(session_id,line_no)、run_identity"重试/重复投递/重启"不产生第二条副作用
JSON 列配置/清单/快照用 JSON(MySQL 8 JSON 类型)灵活;但不把需要查询的字段塞进 JSON
生成列如 daily_course_session.natural_key 为 STORED 生成列唯一索引约束需要稳定表达式
大文本LONGTEXT 只用于正文/摘要/历史;列表查询禁止 SELECT * 大字段控制内存与带宽
注释每张表/关键列有中文 COMMENT(附录 M 按注释展示)读库即文档

7.4 数据生命周期与保留策略 ​

只增不减的表必须有人清,否则迟早撑爆磁盘。当前清理任务:

任务清理对象保留期(默认)配置
RawRetentionJobagent_session_raw14 天site.conversation.raw-retention-days
RawRetentionJobagent_turn(只删"记忆抽取水位已覆盖"的行)0 = 永久(默认关)site.conversation.agent-turn-retention-days
LedgerRetentionJobagent_tool_call_log、ai_egress_log180 天cosmos.ops.ledger-retention.{enabled,days}
ExtensionRetentionJobextension_run、extension_run_event、extension_policy_decision、extension_capability_call、extension_effect、extension_message_delivery180 天cosmos.extension.retention.{enabled,days}
ProactiveComposeCacheService.purgeScheduled过期/失败预润色缓存过期即删每小时 :20
备份保留本地 db/uploads/hindsight 备份7 天 / 7 份(可配)备份脚本

永久保留的表(设计如此):sys_config、sys_audit_log(合规)、ai_token_usage(用量凭证)、 ai_memory_archive(归档快照)、proactive_log(主动账本)、extension_* 的安装/版本/授权。 sys_job_log、notify_log、mail_log 等由运维台"数据清理"手动或按需清理(保留天数参数)。

清理的安全设计:

  • 分批删除(每批 N 行、单轮有上限),避免长事务锁表;
  • 删除 0 行也写 job log("这一轮确实跑过");
  • 孤儿文件清理先做引用反查(全部 MediaReferenceProvider),反查失败按"未知"保守保留;
  • 备份清理保留最新 N 份与"最后可恢复点",不会一次删光。

7.5 时区、大整数与序列化 ​

  • 业务时间:JVM 时区固定 Asia/Shanghai(TimezoneGuard + TZ 环境变量);接口输出本地时间字符串。
  • 扩展平台时间:next_run_at/last_run_at 统一 UTC(LocalDateTime.now(ZoneOffset.UTC)); 判断 due 必须用 UTC_TIMESTAMP(),用本地 NOW() 会误报(审查 #83 踩过)。
  • 大整数:Jackson 把 Long 序列化为字符串;MCP 回执里 id 一律字符串,前端不 Number(); 这是为了绕开 JS 2^53 精度问题(历史事故:id 被截断导致"数据不存在")。
  • 枚举:库里存字符串(status='active'),不用魔法数字;状态常量集中在实体类/常量类。

7.6 删除与级联:每处都要想清楚 ​

删除对象行为
文章/说说/相册/页面软删(可恢复);门户立即不可见(SQL 过滤)
笔记软删进回收站;恢复时保留标签关系(审查 #55)
待办删除任务级联删步骤;删除未投递提醒
课程删除当天课次;已生成的提醒一并取消(未投递的)
记忆soft/hard 两档;hard 连向量一起删;幂等
文件/附件先查引用(MediaReferenceProvider),无引用才删记录+磁盘
扩展卸载只停用不删除历史(run/effect/审计保留)

全库 0 个物理外键:所有 *_id/*_key 都是逻辑引用。排查"这条数据属于谁"时看列注释 (附录 M)与本文档的模块章节;删除父行前必须在代码里处理子行,否则会留下孤儿数据。

本页由 docs/vite-cosmos-项目说明.md 自动生成;请改源文件,不要改生成物。