3.9 KiB

Raw Blame History

数据库字段重命名：metadata → meta_data

日期: 2026-02-03
类型: 架构优化
影响范围: 数据库模型、Schema、Service、API
迁移文件: 20260203_1521_9a6a8471bda0_rename_metadata_to_meta_data_and_add_ai_conversations.py

背景

在实现 Screenplay 和 AI Conversation 功能时，发现使用 metadata 作为字段名会与 SQLAlchemy 的保留属性冲突，导致服务启动失败。

问题

# ❌ 错误：metadata 是 SQLAlchemy 保留字段
class ScreenplayCharacter(SQLModel, table=True):
    metadata: Dict[str, Any] = Field(...)  # 与 SQLModel.metadata 冲突

解决方案

将所有 metadata 字段重命名为 meta_data，避免与 SQLAlchemy 保留字段冲突。

变更内容

1. 数据库字段重命名

涉及表：

screenplay_characters.metadata → meta_data
screenplay_locations.metadata → meta_data
screenplay_props.metadata → meta_data
screenplay_element_tags.metadata → meta_data
ai_conversations.metadata → meta_data
ai_conversation_messages.metadata → meta_data

2. 新增表

同时在此次迁移中创建了 AI Conversation 相关表：

ai_conversations - AI 对话会话表
ai_conversation_messages - AI 对话消息表

3. 代码层修改

模型文件（6个）：

server/app/models/screenplay_character.py
server/app/models/screenplay_location.py
server/app/models/screenplay_prop.py
server/app/models/screenplay_element_tag.py
server/app/models/ai_conversation.py
server/app/models/ai_conversation_message.py

Schema 文件（4个）：

server/app/schemas/screenplay.py
server/app/schemas/screenplay_tag.py
server/app/schemas/ai_conversation.py
server/app/schemas/ai_conversation_message.py

Service 文件（3个）：

server/app/services/screenplay_service.py
server/app/services/screenplay_tag_service.py
server/app/services/ai_conversation_service.py

API 文件（4个）：

server/app/api/v1/screenplays.py
server/app/api/v1/screenplay_tags.py
server/app/api/v1/ai_conversations.py
server/app/api/v1/ai_prompts.py

技术细节

字段定义

# 新的字段定义
meta_data: Dict[str, Any] = Field(
    default_factory=dict,
    sa_column=Column(JSONB, nullable=False, server_default='{}'),
    description="元数据"
)

命名优势

避免保留字冲突：meta_data 不是 SQLAlchemy 保留字段
语义清晰：明确表示"元数据"
符合规范：使用 snake_case 命名，符合 Python 社区规范
更少混淆：不会与 SQLAlchemy 的 metadata 属性冲突

迁移步骤

1. 数据库迁移

# 应用迁移
docker exec jointo-server-app python scripts/db_migrate.py upgrade

2. 验证

# 检查字段名
docker exec jointo-server-postgres psql -U jointoAI -d jointo -c "\d screenplay_characters"

# 验证服务启动
docker restart jointo-server-app
docker logs jointo-server-app --tail 20

影响评估

破坏性变更

✅ 数据库字段名变更（通过迁移自动处理）
✅ API 请求/响应字段名变更（前端需同步更新）

兼容性

✅ 现有数据自动迁移
✅ 服务正常启动
⚠️ 前端代码需要同步更新字段名

后续工作

前端同步：更新前端代码中所有 metadata 字段为 meta_data
API 文档：更新 API 文档中的字段说明
测试验证：确保所有相关功能正常工作

经验教训

避免使用保留字：在设计数据库字段时，应避免使用框架的保留字段名
提前验证：在实现功能前，应先验证字段名是否会产生冲突
统一命名规范：使用 snake_case 命名，避免与框架内置属性冲突

参考

SQLAlchemy 保留字段：https://docs.sqlalchemy.org/en/20/core/metadata.html
Jointo 技术栈规范：docs/architecture/tech-stack.md

3.9 KiB Raw Blame History