# 对白类型和画外音角色设计总结

**设计日期**: 2026-02-02  
**设计版本**: v2.0（方案B）

---

## 设计演进

### 初始方案（已废弃）
- ❌ 在 role_type 中增加 4 = narrator（旁白）
- ❌ 问题：维度混乱（主角/配角/群演 按重要性分类，旁白按出场方式分类）

### 最终方案（已采纳）
- ✅ 保持 role_type 原样（1=主角, 2=配角, 3=群演）
- ✅ 新增 is_offscreen 字段标识画外音角色
- ✅ 新增 dialogue_type 字段区分对白类型

---

## 核心设计理念

### 三维度分离

**维度1：角色重要性（role_type）**
- 描述角色在剧情中的地位
- 1 = main（主角）
- 2 = supporting（配角）
- 3 = extra（群演）

**维度2：出场方式（is_offscreen）**
- 描述角色是否出现在画面中
- false = 出现在画面中（默认）
- true = 画外音角色（如纪录片解说员）

**维度3：对白类型（dialogue_type）**
- 描述对白的表现形式
- 1 = normal（普通对白）
- 2 = inner_monologue（内心OS）
- 3 = narration（旁白）

---

## 数据库变更

### screenplay_characters 表

```sql
-- 新增字段
is_offscreen BOOLEAN NOT NULL DEFAULT false

-- 列注释
COMMENT ON COLUMN screenplay_characters.is_offscreen IS 
'是否为画外音角色（不出现在画面中，如纪录片解说员）';

-- 索引
CREATE INDEX idx_screenplay_characters_offscreen 
ON screenplay_characters(is_offscreen) 
WHERE is_offscreen = true;
```

### storyboard_dialogues 表

```sql
-- 新增字段
dialogue_type SMALLINT NOT NULL DEFAULT 1

-- 列注释
COMMENT ON COLUMN storyboard_dialogues.dialogue_type IS 
'对白类型：1=normal(普通对白), 2=inner_monologue(内心OS), 3=narration(旁白)';

-- 索引
CREATE INDEX idx_storyboard_dialogues_type 
ON storyboard_dialogues(dialogue_type) 
WHERE dialogue_type != 1;
```

---

## 使用场景示例

### 场景1：纪录片解说员
```json
{
  "character": {
    "name": "解说员",
    "role_type": "main",        // 重要性：主角（贯穿全片）
    "is_offscreen": true         // 出场方式：画外音
  },
  "dialogue": {
    "content": "公元627年，唐僧踏上了西行之路...",
    "dialogue_type": "narration" // 表现形式：旁白
  }
}
```

### 场景2：甄嬛的回忆旁白
```json
{
  "character": {
    "name": "甄嬛",
    "role_type": "main",         // 重要性：主角
    "is_offscreen": false        // 出场方式：画面中
  },
  "dialogue": {
    "content": "那一年，我还是个天真的少女...",
    "dialogue_type": "narration" // 表现形式：旁白（回忆画外音）
  }
}
```

### 场景3：孙悟空的内心OS
```json
{
  "character": {
    "name": "孙悟空",
    "role_type": "main",              // 重要性：主角
    "is_offscreen": false             // 出场方式：画面中
  },
  "dialogue": {
    "content": "师父又在念紧箍咒了，我得忍住...",
    "dialogue_type": "inner_monologue" // 表现形式：内心OS
  }
}
```

---

## 设计优势

### 1. 维度清晰
- 三个维度互不干扰，各司其职
- 避免了分类标准混乱的问题

### 2. 灵活性高
- 支持任意组合：主角+画外音+旁白、主角+画面中+内心OS 等
- 不强制约束，保持最大灵活性

### 3. 扩展性好
- 未来可以轻松增加更多对白类型（画外音、独白、aside等）
- 可以增加更多角色属性（如 is_virtual 虚拟角色等）

### 4. 业务价值
- **资源库筛选**：可以筛选 `is_offscreen = true` 的角色
- **AI生成优化**：画外音角色不需要生成角色形象图片
- **统计分析**：准确统计各类角色数量
- **TTS处理**：根据对白类型使用不同音色

---

## 前端实现建议

### 角色编辑表单
```tsx
<FormField label="角色类型">
  <Select value={character.roleType}>
    <option value="main">主角</option>
    <option value="supporting">配角</option>
    <option value="extra">群演</option>
  </Select>
</FormField>

<FormField label="出场方式">
  <Checkbox checked={character.isOffscreen}>
    画外音角色（不出现在画面中）
  </Checkbox>
</FormField>
```

### 对白编辑表单
```tsx
<FormField label="对白类型">
  <Select value={dialogue.dialogueType}>
    <option value="normal">普通对白</option>
    <option value="inner_monologue">内心OS</option>
    <option value="narration">旁白</option>
  </Select>
</FormField>
```

### 时间轴对白轨道样式
```typescript
const getDialogueStyle = (type: DialogueType) => {
  switch (type) {
    case 'inner_monologue':
      return 'bg-purple-100 border-purple-400 italic';
    case 'narration':
      return 'bg-amber-100 border-amber-400';
    default:
      return 'bg-blue-100 border-blue-400';
  }
};
```

---

## 相关文档

- [对白类型和画外音角色设计 Changelog](./changelogs/2026-02-02-dialogue-type-and-narrator-role.md)
- [剧本管理服务](../requirements/backend/04-services/project/screenplay-service.md)
- [分镜资源服务](../requirements/backend/04-services/project/storyboard-resource-service.md)

---

**设计版本**: v2.0  
**最后更新**: 2026-02-02