# 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 调用

## 技术细节

### 数据库表结构（修改后）

```sql
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 定义（修改后）

```python
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 响应示例（修改后）

```json
{
  "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"
}
```

## 兼容性说明

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

### 未来开发注意事项
1. **前端开发**: 使用 `characterImageUrl` 字段名（camelCase）
2. **后端开发**: 使用 `character_image_url` 字段名（snake_case）
3. **数据验证**: URL 长度限制为 500 字符
4. **字段别名**: Pydantic 使用 `alias="characterImageUrl"` 实现自动转换

## 相关文档

- [Screenplay Service 文档](../requirements/backend/04-services/project/screenplay-service.md)
- [Database Design 文档](../requirements/database-design.md)
- [Jointo Tech Stack - 命名规范](.claude/skills/jointo-tech-stack/references/naming.md)

## 总结

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