docs(server): 同步数据库迁移规范

This commit is contained in:
YBF
2026-09-17 11:04:36 +08:00
parent 601bacaecc
commit 9ea672023c
2 changed files with 32 additions and 1 deletions
@@ -12,8 +12,30 @@
- `onetalk_contact_profile`Bright 当前联系人资料事实。`channel_account_id + conversation_id` 复合主键,不建立到技术会话表的外键;资料字段允许显式 `null`,只有严格较新的 `observed_at_ms` 才能覆盖整行。它是名片读取 view 的唯一客户资料来源,不是消息事实的嵌入列。
- `onetalk_message_anomaly`:缺字段、协议和同步异常的独立诊断事实。`fingerprint` 仅用于诊断合并;`payload` 必须由写入边界清洗,不能被消息读取、发送或锚点流程消费。
- `onetalk_buyer_fact`:买家标签、特征与联系细节的当前事实,独立于联系人资料。`channel_account_id + conversation_id` 复合主键;`tags_state`/`features_state`/`contact_details_state` 各来源独立表达 confirmed/failedconfirmed 来源整体替换、failed 只更新自身审计;`fact_fingerprint` 必须由最终合并后的集合计算。
- `onetalk_rendered_card_content`:与基础消息解耦的只读 DOM 渲染卡片补全事实。使用相同的 `channel_account_id + conversation_id + message_id` 复合主键;只保存经 shared contract 验证的 allowlisted rendered-card snapshot、fingerprint 和页面观察时间,首个接受快照不可覆盖,后续冲突只递增 `conflict_count`,不承载 Fiber/raw props。
生成的初始迁移为 `apps/server/drizzle/0000_rapid_winter_soldier.sql`,其中显式维护 PostgreSQL 表/字段 `COMMENT ON` 备注(Drizzle 当前版本不会从 TypeScript 注释自动生成数据库备注)。未确认发送不进入任何一张表,普通运行路径不提供物理删除;profile 当前行由读取服务另行受限读取后在内存组合,不复制进 conversation 或 message。媒体切换 migration `0005_young_squadron_supreme` 是一次性开发数据重置:仅 `DELETE` 本仓库拥有的 OneTalk message/anomaly/profile/conversation 事实,再删除 `text/content_type` 并为 `content` 加 v1 kind CHECK;不触及授权、binding 或其它渠道。后续增量迁移:`0006_onetalk_buyer_facts` 新增 `onetalk_buyer_fact` 表;`0007_center_contact_time``onetalk_conversation` 增加规范会话活动时间 `last_contact_time_ms` 与白名单 `message_preview``0008_lucky_captain_universe` 为 buyer fact 增加 contact details 白名单列;`0009_remove_image_dimensions` 移除 image content 的 `width`/`height``0010_wooden_naoko` 将 content v1 CHECK 扩展到六类 kind`0011_mushy_baron_strucker` 在建立名片 exact CHECK 前,将已有带客户资料字段的 `business_card` content 归一化为 marker`0013_nifty_thunderbird` 只重建同一 CHECK 以加入 `product`,不回填、更新或删除历史事实。
生成的初始迁移为 `apps/server/drizzle/0000_rapid_winter_soldier.sql`,其中显式维护 PostgreSQL 表/字段 `COMMENT ON` 备注(Drizzle 当前版本不会从 TypeScript 注释自动生成数据库备注)。未确认发送不进入任何一张表,普通运行路径不提供物理删除;profile 当前行由读取服务另行受限读取后在内存组合,不复制进 conversation 或 message。
迁移按 `apps/server/drizzle/meta/_journal.json` 的顺序连续执行:
- `0001_legal_jackal` 将消息和异常表的 `binding_id` 重命名为 `binding`
- `0002_big_richard_fisk` 移除消息表的 `login_user_id`
- `0003_onetalk_contact_profile_facts` 新增 `onetalk_contact_profile` 当前资料事实表。
- `0004_onetalk_conversation_direct_fact``onetalk_conversation` 增加 `conversation_kind`
- `0005_young_squadron_supreme` 是一次性开发数据重置:仅删除本仓库拥有的 OneTalk message/anomaly/profile/conversation 事实,再删除 `text/content_type` 并为 `content` 加 v1 kind CHECK;不触及授权、binding 或其它渠道。
- `0006_onetalk_buyer_facts` 新增 `onetalk_buyer_fact` 表。
- `0007_center_contact_time``onetalk_conversation` 增加规范会话活动时间 `last_contact_time_ms` 与白名单 `message_preview`
- `0008_lucky_captain_universe` 为 buyer fact 增加 contact details 白名单列及其状态、审计字段。
- `0009_remove_image_dimensions` 从已有 image content 中移除 `width`/`height`
- `0010_wooden_naoko` 将消息 content v1 CHECK 扩展到六类 kind。
- `0011_mushy_baron_strucker` 在建立名片 exact CHECK 前,将已有带客户资料字段的 `business_card` content 归一化为 marker。
- `0012_onetalk_history_generation``onetalk_conversation` 增加 `history_generation`,已有记录默认值为 `initial`
- `0013_nifty_thunderbird` 重建消息 content CHECK 以加入 `product`,不回填、更新或删除历史事实。
- `0014_youthful_iron_lad` 新增独立的 `onetalk_rendered_card_content` 表及其复合主键、scope 索引、字段备注和渲染卡片 v1 CHECK。
- `0015_wild_toad_men` 移除 rendered-card 表中不再使用的 `first_confirmed_at``last_observed_at``last_conflicting_fingerprint``last_conflict_observed_at_ms`,不改写已保存快照。
- `0016_optimal_imperial_guard` 放宽 rendered-card v1 CHECK:保留三种显式 kind 白名单,同时允许不带 `kind` 的合法对象。
迁移说明和目录树必须与 `apps/server/drizzle/` 及其 `_journal.json` 保持同步;新增 migration 后应同时更新本节和目录结构文档。
## Scenario: Schema 注释与 PostgreSQL 备注
@@ -19,6 +19,15 @@ apps/
│ ├── 0005_young_squadron_supreme.sql
│ ├── 0006_onetalk_buyer_facts.sql
│ ├── 0007_center_contact_time.sql
│ ├── 0008_lucky_captain_universe.sql
│ ├── 0009_remove_image_dimensions.sql
│ ├── 0010_wooden_naoko.sql
│ ├── 0011_mushy_baron_strucker.sql
│ ├── 0012_onetalk_history_generation.sql
│ ├── 0013_nifty_thunderbird.sql
│ ├── 0014_youthful_iron_lad.sql
│ ├── 0015_wild_toad_men.sql
│ ├── 0016_optimal_imperial_guard.sql
│ └── meta/_journal.json
├── src/
│ ├── app.ts