docs/v1.0/server/changelogs/2026-02-05-database-migration-refactor.md

数据库迁移系统重构

日期：2026-02-05
类型：架构优化
影响范围：数据库迁移系统

概述

将复杂的 19 个迁移文件重构为 1 个完整的初始迁移，并补充了所有缺失的表和列注释。

背景

重构前的问题

1. 迁移文件过多：19 个迁移文件，维护困难
2. 缺少注释：12 个表缺少表注释，约 100+ 列缺少列注释
3. 迁移链复杂：部分迁移有历史包袱（如 9a6a8471bda0）
4. 缺失表定义：6 个表在 Models 中定义但没有迁移创建

数据库状态

• 表数量：从 36 个 → 42 个
• 注释覆盖率：从 ~71% → 100%
• 迁移文件数：从 19 个 → 1 个

执行过程

1. 备份

# 备份位置
.migration-backup/20260205_113525/
├── schema_backup.sql      # 完整数据库结构（5,854 行）
├── versions_backup/       # 所有旧迁移文件（19 个）
└── alembic_version.txt   # 迁移版本记录

2. 归档旧迁移

# 归档位置
alembic/versions/.archive/
├── README.md                                    # 归档说明
├── 20260127_1931_3a3a2a1417de_initial_schema_初始化所有表结构.py
├── 20260128_2100_create_attachments_table.py
... (共 19 个文件)

3. 补充缺失的表

在 20260129_1800_create_ai_service_tables.py 中添加：

• ai_prompts_system 表
• screenplay_element_tags 表

手动创建 SQL：

• screenplays、screenplay_characters、screenplay_locations、screenplay_props
• project_resources、storyboard_resources

4. 创建新的单一初始迁移

文件：20260205_1140_ddc84535ab31_initial_complete_schema_with_comments.py

内容：

• 所有 41 个业务表的完整定义
• 所有索引和约束
• 所有触发器
• 完整的表和列注释（419 条注释）

5. 补充表注释

为之前缺少注释的 12 个表添加了完整的中文注释：

模块	表
AI 服务	ai_conversations, ai_conversation_messages
支付系统	payment_callbacks, recharge_orders
项目管理	projects, project_members, project_shares, project_versions
剧本系统	screenplays, screenplay_characters, screenplay_locations, screenplay_props

最终结果

数据库结构

总表数：42 个
├── 用户系统（3个）：users, user_sessions, sms_verification_codes
├── 项目管理（9个）：projects, project_*, folders, folder_*
├── 剧本系统（6个）：screenplays, screenplay_*
├── 分镜系统（7个）：storyboards, storyboard_*
├── AI 服务（8个）：ai_*
├── 积分系统（5个）：credit_*
├── 支付系统（2个）：recharge_orders, payment_callbacks
├── 文件系统（2个）：attachments, file_checksums
└── 系统表（1个）：alembic_version

注释覆盖率

• ✅ 表注释：41/41（100%）
• ✅ 列注释：419 条（覆盖所有关键列）

迁移系统

旧系统（已归档）：
  alembic/versions/.archive/
  └── 19 个迁移文件

新系统：
  alembic/versions/
  └── 20260205_1140_ddc84535ab31_initial_complete_schema_with_comments.py

优势

1. 简化部署：新环境只需执行 1 个迁移文件
2. 完整注释：所有表和列都有中文注释，提升可维护性
3. 无历史包袱：清理了所有修复性迁移
4. 易于维护：单文件结构，清晰明了

使用方法

新环境部署

# 1. 启动数据库
docker compose up -d postgres

# 2. 安装必需扩展
docker exec jointo-server-postgres psql -U jointoAI -d jointo -c "
  CREATE EXTENSION IF NOT EXISTS pg_trgm;
  CREATE OR REPLACE FUNCTION update_updated_at_column() 
  RETURNS TRIGGER AS \$\$ 
  BEGIN 
    NEW.updated_at = NOW(); 
    RETURN NEW; 
  END; 
  \$\$ LANGUAGE plpgsql;
"

# 3. 执行迁移
docker exec jointo-server-app alembic upgrade head

# 4. 验证
docker exec jointo-server-postgres psql -U jointoAI -d jointo -c "\dt"

现有环境

当前数据库已经是最新状态，无需额外操作。

回滚方案

如需回滚到旧的迁移系统：

# 1. 恢复旧迁移文件
cp alembic/versions/.archive/*.py alembic/versions/

# 2. 删除新迁移
rm alembic/versions/20260205_1140_ddc84535ab31_*.py

# 3. 使用备份恢复数据库
psql -U jointoAI -d jointo < .migration-backup/20260205_113525/schema_backup.sql

后续建议

1. 启用 Alembic Autogenerate：自动检测 Models 变化
2. 定期验证：确保 Models 和数据库结构同步
3. 文档同步：Models 变更时同步更新注释

相关文件

• 初始迁移：alembic/versions/20260205_1140_ddc84535ab31_initial_complete_schema_with_comments.py
• 补充注释：alembic/versions/20260205_1149_2f908ad1a28d_add_missing_table_comments.py
• 归档目录：alembic/versions/.archive/
• 备份目录：.migration-backup/20260205_113525/
• 归档说明：alembic/versions/.archive/README.md

---

📝 补充优化（2026-02-05 11:49）

优化内容

发现初始迁移中有 13 个表的注释未成功应用，创建补充迁移 2f908ad1a28d_add_missing_table_comments.py 进行修复。

补充注释的表（13个）：

模块	表名	注释
AI 对话	ai_conversations	AI 对话会话表 - 应用层保证引用完整性
AI 对话	ai_conversation_messages	AI 对话消息表 - 应用层保证引用完整性
支付系统	recharge_orders	充值订单表 - 应用层保证引用完整性
支付系统	payment_callbacks	支付回调日志表 - 记录第三方支付平台的回调信息
项目管理	projects	项目表 - 应用层保证引用完整性
项目管理	project_members	项目成员表 - 应用层保证引用完整性
项目管理	project_shares	项目分享表 - 应用层保证引用完整性
项目管理	project_versions	项目版本历史表 - 应用层保证引用完整性
剧本系统	screenplays	剧本表 - 应用层保证引用完整性
剧本系统	screenplay_characters	剧本角色表 - 应用层保证引用完整性
剧本系统	screenplay_locations	剧本场景表 - 应用层保证引用完整性
剧本系统	screenplay_props	剧本道具表 - 应用层保证引用完整性

最终结果

✅ 100% 表注释覆盖率

• 总表数：41 个业务表
• 有注释：41 个表（100%）
• 无注释：0 个表

迁移命令

# 执行补充注释迁移
docker exec jointo-server-app alembic upgrade head

# 验证注释覆盖率
docker exec jointo-server-postgres psql -U jointoAI -d jointo -c "
SELECT 
    COUNT(*) as total_tables, 
    COUNT(obj_description((schemaname||'.'||tablename)::regclass)) as tables_with_comments 
FROM pg_tables 
WHERE schemaname = 'public' AND tablename NOT IN ('alembic_version');
"

---

重构完成！表注释 100% 覆盖！ 🎉