docs/v1.0/architecture/changelogs/2026-02-01-dialogue-field-rename-text-to-content.md

对白字段重命名：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 暗示纯文本，限制了扩展可能性

---

变更内容

数据库设计

变更前：

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 '对白文本内容';

变更后：

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 响应格式

变更前：

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

变更后：

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

服务层代码

变更前：

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,
    # ...
)

变更后：

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	评论内容

---

相关文档

• 分镜资源服务
• 分镜看板服务
• 剧本服务

---

总结

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

---

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