# AI Conversations 数据库迁移指南

**迁移脚本**: `20260213_1200_update_ai_conversations_comments.py`  
**影响表**: `ai_conversations`  
**操作类型**: 更新字段注释（非破坏性）

---

## 📋 迁移内容

### 更新字段注释

#### 1. `target_type` 字段
```sql
-- 旧注释
'目标类型：1=分镜, 2=角色, 3=场景, 4=道具, 5=通用资源, 6=音效, 7=配音'

-- 新注释
'目标类型：1=分镜, 2=角色, 3=场景, 4=道具, 5=通用资源'
```

**变更**: 移除 `6=音效` 和 `7=配音`

#### 2. `media_type` 字段
```sql
-- 旧注释
'媒体类型：1=图片, 2=视频, 3=音频, 4=3D模型, 5=文本'

-- 新注释
'媒体类型：1=图片, 2=视频'
```

**变更**: 移除 `3=音频`, `4=3D模型`, `5=文本`

---

## 🚀 执行迁移

### 1. Docker 环境（推荐）

```bash
# 查看当前迁移状态
docker exec jointo-server-app alembic current

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

# 验证迁移结果
docker exec jointo-server-app alembic current
```

### 2. 本地开发环境

```bash
# 进入 server 目录
cd server

# 查看当前迁移状态
alembic current

# 执行迁移
alembic upgrade head

# 验证迁移结果
alembic current
```

### 3. 生产环境

```bash
# 1. 备份数据库（重要！）
docker exec jointo-server-postgres pg_dump -U jointoAI jointo > backup_$(date +%Y%m%d_%H%M%S).sql

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

# 3. 验证结果
docker exec jointo-server-postgres psql -U jointoAI -d jointo -c "
SELECT 
    col_description('ai_conversations'::regclass, 2) as target_type_comment,
    col_description('ai_conversations'::regclass, 7) as media_type_comment;
"
```

---

## 🔍 验证迁移

### 检查字段注释

```sql
-- 连接到数据库
docker exec -it jointo-server-postgres psql -U jointoAI -d jointo

-- 查看字段注释
SELECT 
    a.attname AS column_name,
    pg_catalog.col_description(a.attrelid, a.attnum) AS column_comment
FROM 
    pg_catalog.pg_attribute a
WHERE 
    a.attrelid = 'ai_conversations'::regclass
    AND a.attname IN ('target_type', 'media_type')
ORDER BY a.attnum;
```

**期望输出**:
```
 column_name  |                     column_comment                      
--------------+---------------------------------------------------------
 target_type  | 目标类型：1=分镜, 2=角色, 3=场景, 4=道具, 5=通用资源
 media_type   | 媒体类型：1=图片, 2=视频
```

---

## 📊 数据影响分析

### 检查受影响的数据

```sql
-- 检查是否有 target_type=6 或 7 的记录
SELECT 
    target_type,
    COUNT(*) as count,
    STRING_AGG(DISTINCT title, ', ') as sample_titles
FROM ai_conversations
WHERE target_type IN (6, 7)
GROUP BY target_type;

-- 检查是否有 media_type=3/4/5 的记录
SELECT 
    media_type,
    COUNT(*) as count,
    STRING_AGG(DISTINCT title, ', ') as sample_titles
FROM ai_conversations
WHERE media_type IN (3, 4, 5)
GROUP BY media_type;
```

### 可选：清理无效数据

**⚠️ 警告**: 此操作会标记数据为已删除，请谨慎执行！

```sql
-- 标记为已删除（软删除）
UPDATE ai_conversations 
SET 
    status = 3,  -- DELETED
    updated_at = now()
WHERE 
    (target_type IN (6, 7) OR media_type IN (3, 4, 5))
    AND status != 3;

-- 查看受影响的行数
SELECT 
    '标记为已删除' as operation,
    COUNT(*) as affected_rows
FROM ai_conversations
WHERE target_type IN (6, 7) OR media_type IN (3, 4, 5);
```

---

## ⏪ 回滚迁移

如果需要回滚到之前的版本：

```bash
# Docker 环境
docker exec jointo-server-app alembic downgrade -1

# 本地环境
cd server && alembic downgrade -1
```

**回滚效果**: 恢复旧的字段注释（包含音效、配音、音频等）

---

## 🔧 故障排查

### 问题 1: 迁移失败

**错误**: `Target database is not up to date`

**解决**:
```bash
# 查看当前版本
docker exec jointo-server-app alembic current

# 查看所有待执行的迁移
docker exec jointo-server-app alembic history

# 按顺序执行迁移
docker exec jointo-server-app alembic upgrade head
```

### 问题 2: 权限不足

**错误**: `permission denied for table ai_conversations`

**解决**:
```sql
-- 检查用户权限
\du

-- 授予权限（如果需要）
GRANT ALL PRIVILEGES ON TABLE ai_conversations TO jointoAI;
```

### 问题 3: 已有无效数据导致前端报错

**解决**:
```sql
-- 方案 A: 软删除无效数据
UPDATE ai_conversations 
SET status = 3 
WHERE target_type IN (6, 7) OR media_type IN (3, 4, 5);

-- 方案 B: 查询时过滤无效数据（应用层）
SELECT * FROM ai_conversations 
WHERE target_type IN (1, 2, 3, 4, 5)
  AND media_type IN (1, 2);
```

---

## 📝 相关文档

- [移除音效配音 Changelog](../changelogs/2026-02-13-remove-sound-effect-voiceover-from-conversations.md)
- [简化 MediaType Changelog](../changelogs/2026-02-13-simplify-media-type-enum.md)
- [业务流程指南](./ai-conversation-generation-workflow.md)

---

## ✅ 迁移检查清单

**执行前**:
- [ ] 备份数据库
- [ ] 查看当前迁移状态
- [ ] 检查受影响的数据量

**执行中**:
- [ ] 运行迁移脚本
- [ ] 验证迁移结果

**执行后**:
- [ ] 验证字段注释
- [ ] 检查应用日志
- [ ] 前端测试（创建对话功能）
- [ ] 可选：清理无效数据

---

## 🎉 完成标志

✅ **字段注释已更新，代码与数据库保持一致！**

**验证方法**:
1. 数据库字段注释正确显示
2. 前端无法创建 target_type=6/7 的对话
3. 前端无法选择 media_type=3/4/5
4. 已有对话正常显示和使用