# 移除 AI 对话中的音效和配音生成类型

**日期**: 2026-02-13  
**类型**: 架构调整  
**影响范围**: AI 对话系统、数据模型

---

## 📋 背景

### 业务决策
音效和配音**不再通过 AI 对话生成**，改用专用的 API 接口处理。

**原因**:
1. 音效和配音的生成流程与图片/视频不同，需要额外的上下文（如 `dialogue_id`）
2. 对话系统主要面向图片和视频生成，音频场景需要单独设计
3. 简化对话系统的复杂度

---

## 🔧 实施内容

### 1. 移除枚举值

**文件**: `server/app/models/ai_conversation.py`

```python
class TargetType(IntEnum):
    """目标类型"""
    STORYBOARD = 1      # 分镜
    CHARACTER = 2       # 角色
    SCENE = 3           # 场景
    PROP = 4            # 道具
    RESOURCE = 5        # 通用资源
    # ❌ 移除: SOUND_EFFECT = 6
    # ❌ 移除: VOICEOVER = 7
```

### 2. 更新 Schema 文档

**文件**: `server/app/schemas/ai_conversation.py`

```python
target_type: int = Field(
    ..., 
    alias="targetType", 
    description="目标类型（1=分镜 2=角色 3=场景 4=道具 5=资源）"
)
```

### 3. 清理验证逻辑

**文件**: `server/app/services/ai_conversation_service.py`

**移除**:
- `TargetType.SOUND_EFFECT` 和 `TargetType.VOICEOVER` 的验证分支
- 相关的 Repository 临时代码
- `VALID_COMBINATIONS` 中的音效/配音配置

### 4. 简化生成结果保存逻辑

**文件**: `server/app/services/ai_generation_result_service.py`

**移除方法**:
- `_save_sound_effect()` - 音效保存逻辑
- `_save_voiceover()` - 配音保存逻辑

**保留**:
- `_save_storyboard_audio()` - 仅作为扩展预留，记录警告日志

### 5. 更新 API 文档

**文件**: `server/app/api/v1/ai_conversations.py`

```python
# 更新注释
"""
支持多态关联 + 标签系统：
- target_type: 目标类型（分镜/角色/场景/道具/资源）
"""
```

---

## 📊 数据库影响

### 现有数据处理

**`ai_conversations` 表**:
```sql
-- 如果已有 target_type=6 或 7 的数据，需要手动清理或迁移
SELECT COUNT(*) FROM ai_conversations 
WHERE target_type IN (6, 7);

-- 可选：标记为已删除
UPDATE ai_conversations 
SET status = 3  -- DELETED
WHERE target_type IN (6, 7);
```

**数据库字段注释更新**:
```sql
COMMENT ON COLUMN "public"."ai_conversations"."target_type" IS 
  '目标类型：1=分镜, 2=角色, 3=场景, 4=道具, 5=通用资源';
```

---

## 🔄 新的业务场景映射

| target_type | 业务场景 | 存储表 | 生成方式 |
|------------|----------|--------|---------|
| 1 | 分镜图片/视频 | `storyboard_images` / `storyboard_videos` | ✅ AI 对话生成 |
| 2 | 角色形象 | `project_resources` | ✅ AI 对话生成 |
| 3 | 场景图片 | `project_resources` | ✅ AI 对话生成 |
| 4 | 道具图片 | `project_resources` | ✅ AI 对话生成 |
| ~~6~~ | ~~音效~~ | `storyboard_sound_effects` | ❌ 使用专用 API |
| ~~7~~ | ~~配音~~ | `storyboard_voiceovers` | ❌ 使用专用 API |

---

## 📝 相关代码文件

### 修改文件
- `server/app/models/ai_conversation.py` - 移除枚举值
- `server/app/schemas/ai_conversation.py` - 更新文档
- `server/app/api/v1/ai_conversations.py` - 更新注释
- `server/app/services/ai_conversation_service.py` - 清理验证逻辑
- `server/app/services/ai_generation_result_service.py` - 移除保存方法

### 数据库迁移
- `server/alembic/versions/20260213_1200_update_ai_conversations_comments.py` - 更新字段注释

**运行迁移**:
```bash
# Docker 环境
docker exec jointo-server-app alembic upgrade head

# 本地环境
cd server && alembic upgrade head
```

### 更新文档
- `docs/server/guides/ai-conversation-generation-workflow.md` - 更新业务流程
- `docs/server/changelogs/2026-02-13-ai-generation-result-auto-save.md` - 更新实现文档

---

## ⚠️ 注意事项

### 1. 向后兼容性
- **已有数据**: 如果数据库中存在 `target_type=6` 或 `7` 的记录，不会自动删除
- **API 行为**: 前端仍然可以传入 6 或 7，但会被验证逻辑拒绝

### 2. 前端适配
前端需要移除以下场景：
- 创建音效对话 (target_type=6)
- 创建配音对话 (target_type=7)

### 3. 音效和配音的新流程
音效和配音改为使用专用 API：
- 音效生成: `POST /api/v1/storyboards/{id}/sound-effects`
- 配音生成: `POST /api/v1/storyboards/{id}/voiceovers`

（具体 API 待实现）

---

## ✅ 验证清单

- [x] 移除 `TargetType.SOUND_EFFECT` 和 `VOICEOVER` 枚举
- [x] 更新 Schema 文档注释
- [x] 清理验证逻辑
- [x] 移除音效/配音保存方法
- [x] 更新 API 注释
- [x] 更新业务流程文档
- [x] 更新实现文档
- [x] 创建数据库迁移脚本
- [ ] 运行数据库迁移（生产环境）
- [ ] 前端适配（移除相关入口）
- [ ] 已有数据清理（可选）

---

## 🎉 总结

本次调整**简化了 AI 对话系统的复杂度**，明确了对话生成的边界：

**对话生成适用场景**:
- ✅ 分镜图片/视频
- ✅ 角色/场景/道具形象

**不适用场景**:
- ❌ 音效（需要音频描述 + 时长控制）
- ❌ 配音（需要关联对白 + 语音选择）

音效和配音的生成流程将通过专用 API 实现，提供更精细的参数控制。