# 对白字段重命名：text → content

> **变更日期**：2026-02-01  
> **影响范围**：数据库设计、API 文档  
> **变更类型**：设计优化

---

## 变更概述

将 `storyboard_dialogues` 表的对白内容字段从 `text` 重命名为 `content`，以提高语义明确性并与项目整体命名保持一致。

---

## 变更原因

### 1. **避免字段名过于通用**
- `text` 作为字段名太通用，在代码中可能不够明确
- `text` 是 SQL 数据类型名，虽然不是保留字，但在某些上下文中可能造成混淆

### 2. **与项目整体保持一致**
- 剧本表（`screenplays`）使用 `content` 字段存储剧本内容
- 对白是剧本的组成部分，使用相同命名更统一
- 形成一致的命名模式：`screenplay.content` → `dialogue.content`

### 3. **语义更清晰**
- `content` 明确表示"内容"，在代码中更容易理解
- `dialogue.content` 比 `dialogue.text` 更清晰地表达"对白的内容"

### 4. **扩展性更好**
- 未来如果需要支持富文本对白（如表情、强调标记、音调标记）
- `content` 更适合承载结构化内容
- `text` 暗示纯文本，限制了扩展可能性

---

## 变更内容

### 数据库设计

**变更前**：
```sql
CREATE TABLE storyboard_dialogues (
    dialogue_id UUID PRIMARY KEY,
    storyboard_id UUID NOT NULL,
    character_id UUID,
    character_name TEXT,
    text TEXT NOT NULL,  -- ❌ 旧字段名
    -- ...
);

COMMENT ON COLUMN storyboard_dialogues.text IS '对白文本内容';
```

**变更后**：
```sql
CREATE TABLE storyboard_dialogues (
    dialogue_id UUID PRIMARY KEY,
    storyboard_id UUID NOT NULL,
    character_id UUID,
    character_name TEXT,
    content TEXT NOT NULL,  -- ✅ 新字段名
    -- ...
);

COMMENT ON COLUMN storyboard_dialogues.content IS '对白内容';
```

### API 响应格式

**变更前**：
```json
{
  "dialogue_id": "...",
  "character_name": "张三",
  "text": "你好，最近怎么样？",  // ❌ 旧字段名
  "sequence_order": 1
}
```

**变更后**：
```json
{
  "dialogue_id": "...",
  "character_name": "张三",
  "content": "你好，最近怎么样？",  // ✅ 新字段名
  "sequence_order": 1
}
```

### 服务层代码

**变更前**：
```python
dialogue = StoryboardDialogue(
    storyboard_id=storyboard_id,
    character_id=dialogue_data.character_id,
    character_name=dialogue_data.character_name,
    text=dialogue_data.text,  # ❌ 旧字段名
    sequence_order=sequence_order,
    # ...
)
```

**变更后**：
```python
dialogue = StoryboardDialogue(
    storyboard_id=storyboard_id,
    character_id=dialogue_data.character_id,
    character_name=dialogue_data.character_name,
    content=dialogue_data.content,  # ✅ 新字段名
    sequence_order=sequence_order,
    # ...
)
```

---

## 影响范围

### 已更新的文档

1. **storyboard-resource-service.md**
   - 数据库表设计
   - 服务实现代码
   - API 接口示例
   - 数据库迁移脚本

2. **storyboard-board-service.md**
   - 分镜看板数据结构中的对白字段引用

### 待更新的部分

由于前端尚未开发，无需修改前端代码。后续开发时直接使用 `content` 字段名。

---

## 迁移计划

### 阶段 1：文档更新（已完成）
- ✅ 更新数据库设计文档
- ✅ 更新 API 文档
- ✅ 更新服务实现示例
- ✅ 创建本变更日志

### 阶段 2：代码实现（待开发时执行）
- ⏳ 创建数据库迁移脚本
- ⏳ 实现 Model 层（SQLModel）
- ⏳ 实现 Schema 层（Pydantic）
- ⏳ 实现 Repository 层
- ⏳ 实现 Service 层
- ⏳ 实现 API 层

### 阶段 3：前端开发（待开发时执行）
- ⏳ 前端直接使用 `content` 字段名
- ⏳ TypeScript 类型定义使用 `content`

---

## 技术细节

### 命名对比

| 方案 | 优点 | 缺点 |
|------|------|------|
| `text` | 简洁，常见 | 太通用，是 SQL 类型名 |
| `content` ✅ | 语义明确，与剧本表一致，扩展性好 | 略长 |
| `dialogue_text` | 完全明确 | 冗余（表名已经是 dialogues） |
| `line` | 专业术语 | 可能不够直观 |
| `speech` | 语义明确 | 不如 content 通用 |

### 与其他表的一致性

| 表名 | 内容字段 | 说明 |
|------|---------|------|
| `screenplays` | `content` | 剧本内容 |
| `storyboard_dialogues` | `content` ✅ | 对白内容（已修改） |
| `comments` | `content` | 评论内容 |

---

## 相关文档

- [分镜资源服务](../requirements/backend/04-services/project/storyboard-resource-service.md)
- [分镜看板服务](../requirements/backend/04-services/project/storyboard-board-service.md)
- [剧本服务](../requirements/backend/04-services/project/screenplay-service.md)

---

## 总结

此次变更将对白字段从 `text` 重命名为 `content`，提高了代码的语义明确性和可维护性，并与项目整体命名保持一致。由于前端尚未开发，此变更不会产生任何迁移成本，是最佳的优化时机。

---

**变更日期**：2026-02-01  
**文档版本**：v1.0