4.5 KiB

Raw Blame History

Screenplay Character Image Field 重命名与类型优化

日期: 2026-01-30
类型: 文档优化
影响范围: 剧本服务 (Screenplay Service)

变更概述

优化 screenplay_characters 表中角色图片字段的命名和数据类型，使其更符合业务语义和项目规范。

变更详情

1. 字段重命名

表: screenplay_characters

变更项	修改前	修改后
字段名	`avatar_url`	`character_image_url`
数据类型	`TEXT`	`VARCHAR(500)`
注释	角色头像	角色形象图片地址

2. 修改理由

命名优化

语义准确性: avatar_url 通常指用户头像，而剧本角色需要的是"角色形象图片"
业务区分: 与 users.avatar_url（用户头像）区分开，避免混淆
命名一致性: 与 character 前缀保持一致（如 character_id）

类型优化

性能提升: VARCHAR(500) 比 TEXT 索引效率更高
存储优化: URL 长度通常不超过 500 字符，无需使用无限长度的 TEXT
规范统一: 与项目中其他 URL 字段保持一致（如 users.avatar_url VARCHAR(500)）

3. 影响范围

文档修改

✅ docs/requirements/backend/04-services/project/screenplay-service.md
- 表结构定义
- Model 定义
- Schema 定义
- API 响应示例
- 字段注释
✅ docs/requirements/database-design.md
- 表结构定义

代码影响（未来开发时需注意）

⚠️ SQLModel 模型定义
⚠️ Pydantic Schema 定义
⚠️ API 响应字段
⚠️ 前端 API 调用

技术细节

数据库表结构（修改后）

CREATE TABLE screenplay_characters (
    character_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    screenplay_id UUID NOT NULL,
    name TEXT NOT NULL,
    description TEXT,
    character_image_url VARCHAR(500), -- 修改后
    role_type SMALLINT NOT NULL DEFAULT 2,
    line_count INTEGER DEFAULT 0,
    appearance_count INTEGER DEFAULT 0,
    metadata JSONB NOT NULL DEFAULT '{}',
    created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
);

COMMENT ON COLUMN screenplay_characters.character_image_url IS '角色形象图片地址';

Schema 定义（修改后）

class CharacterCreate(BaseModel):
    """创建角色请求"""
    name: str = Field(..., min_length=1, max_length=255)
    description: Optional[str] = None
    character_image_url: Optional[str] = Field(None, max_length=500)  # 修改后
    role_type: CharacterRoleType = CharacterRoleType.SUPPORTING

class CharacterResponse(BaseModel):
    """角色响应"""
    character_id: str = Field(..., alias="characterId")
    screenplay_id: str = Field(..., alias="screenplayId")
    name: str
    description: Optional[str]
    character_image_url: Optional[str] = Field(None, alias="characterImageUrl")  # 修改后
    role_type: str = Field(..., alias="roleType")
    line_count: int = Field(..., alias="lineCount")
    appearance_count: int = Field(..., alias="appearanceCount")
    created_at: datetime = Field(..., alias="createdAt")
    updated_at: datetime = Field(..., alias="updatedAt")

API 响应示例（修改后）

{
  "character_id": "019d1234-5678-7abc-def0-123456789abc",
  "name": "张三",
  "description": "男主角，30岁，程序员",
  "character_image_url": "https://storage.jointo.ai/characters/123.jpg",
  "role_type": "main",
  "line_count": 150,
  "appearance_count": 45,
  "created_at": "2026-01-30T10:00:00Z",
  "updated_at": "2026-01-30T10:00:00Z"
}

兼容性说明

当前状态

✅ 项目处于文档阶段，未开始开发
✅ 无需数据迁移
✅ 无破坏性变更

未来开发注意事项

前端开发: 使用 characterImageUrl 字段名（camelCase）
后端开发: 使用 character_image_url 字段名（snake_case）
数据验证: URL 长度限制为 500 字符
字段别名: Pydantic 使用 alias="characterImageUrl" 实现自动转换

总结

此次优化提升了字段命名的语义准确性和数据类型的性能表现，为后续开发奠定了更规范的基础。由于项目尚未开始开发，此变更无任何破坏性影响。

4.5 KiB Raw Blame History