# Screenplay API 字段命名规范修复

**日期**: 2026-02-06  
**类型**: Bug修复  
**影响范围**: Screenplay模块API响应

## 问题描述

Screenplay 模块的 API 响应字段未统一使用 camelCase 命名规范，部分端点直接返回 service 层结果，导致响应字段名为 snake_case（数据库字段名），不符合 API 设计规范。

## 修复内容

### 1. API 层修改 (`server/app/api/v1/screenplays.py`)

修复以下端点的响应字段序列化：

#### 剧本 CRUD
- ✅ 获取剧本列表 - 使用 `ScreenplayListItem` 序列化，正确转换 pageSize/totalPages
- ✅ 创建剧本 - 使用 `ScreenplayResponse` 序列化
- ✅ 获取剧本详情 - 已正确（保持不变）
- ✅ 更新剧本 - 使用 `ScreenplayResponse` 序列化
- ✅ 审批剧本 - 使用 `ScreenplayResponse` 序列化
- ✅ 获取版本历史 - 使用 `VersionResponse` 序列化

#### 默认标签管理
- ✅ 设置角色默认标签 - 手动映射字段到 `SetDefaultTagResponse`
- ✅ 设置场景默认标签 - 手动映射字段到 `SetDefaultTagResponse`
- ✅ 设置道具默认标签 - 手动映射字段到 `SetDefaultTagResponse`

#### 角色/场景/道具管理
- ✅ 创建角色 - 使用 `CharacterResponse` 序列化
- ✅ 获取角色列表 - 使用 `CharacterResponse` 序列化，正确转换 pageSize/totalPages
- ✅ 创建场景 - 使用 `LocationResponse` 序列化
- ✅ 获取场景列表 - 使用 `LocationResponse` 序列化，正确转换 pageSize/totalPages
- ✅ 创建道具 - 使用 `PropResponse` 序列化
- ✅ 获取道具列表 - 使用 `PropResponse` 序列化，正确转换 pageSize/totalPages

#### 剧本解析
- ✅ 解析剧本 - 使用 `ScreenplayParseResponse` 序列化

### 2. Schema 层修改 (`server/app/schemas/screenplay.py`)

#### 添加字段验证器

为 `CharacterResponse` 添加 `role_type` 字段验证器：

```python
@field_validator('role_type', mode='before')
@classmethod
def validate_role_type(cls, value: Any) -> str:
    """将 IntEnum 转换为字符串"""
    if isinstance(value, int):
        # 1=main, 2=supporting, 3=extra
        role_type_map = {1: 'main', 2: 'supporting', 3: 'extra'}
        return role_type_map.get(value, 'supporting')
    return str(value)
```

**原因**: 数据库中 `role_type` 存储为 IntEnum（整数），但 API 响应需要返回字符串（'main', 'supporting', 'extra'）

#### 导入更新

添加必要的导入：
- `ScreenplayListItem` - 用于剧本列表序列化
- `ScreenplayParseResponse` - 用于解析任务响应
- `field_validator` - 用于字段验证

### 3. 测试更新

#### 字段命名验证测试 (`tests/test_screenplay_response_fields.py`)

新增 Schema 层字段命名验证测试，确保所有响应模型正确使用 camelCase：
- `test_screenplay_response_fields` - 验证 ScreenplayResponse
- `test_character_response_fields` - 验证 CharacterResponse
- `test_location_response_fields` - 验证 LocationResponse
- `test_prop_response_fields` - 验证 PropResponse
- `test_version_response_fields` - 验证 VersionResponse
- `test_screenplay_parse_response_fields` - 验证 ScreenplayParseResponse

#### 集成测试更新 (`tests/integration/test_screenplay_api.py`)

更新字段名检查：
- `word_count` → `wordCount`
- `page_size` → `pageSize`
- `total_pages` → `totalPages`

## 测试结果

### Schema 层测试
```bash
pytest tests/test_screenplay_response_fields.py -v
# ✅ 6 passed in 0.04s
```

### 集成测试
```bash
pytest tests/integration/test_screenplay_api.py -v
# ✅ 25 passed in 17.89s
```

所有测试通过，确认修复成功。

## 影响范围

### 前端影响
前端需要更新所有 screenplay 相关的 API 调用，确保使用 camelCase 字段名：

**分页字段**:
- `page_size` → `pageSize`
- `total_pages` → `totalPages`

**剧本字段**:
- `screenplay_id` → `screenplayId`
- `project_id` → `projectId`
- `word_count` → `wordCount`
- `scene_count` → `sceneCount`
- `character_count` → `characterCount`
- `file_url` → `fileUrl`
- `file_size` → `fileSize`
- `mime_type` → `mimeType`
- `parsing_status` → `parsingStatus`
- `created_at` → `createdAt`
- `updated_at` → `updatedAt`
- 等...

**角色字段**:
- `character_id` → `characterId`
- `role_type` → `roleType`
- `is_offscreen` → `isOffscreen`
- `line_count` → `lineCount`
- `order_index` → `orderIndex`
- `has_tags` → `hasTags`
- `default_tag_id` → `defaultTagId`
- 等...

### 向后兼容性
⚠️ **破坏性变更**: 此修复改变了 API 响应的字段命名，前端需要同步更新。

## 最佳实践总结

### API 层响应规范
1. ✅ 始终使用 Pydantic schema 序列化响应
2. ✅ 使用 `model_dump(by_alias=True, mode='json')` 确保字段名转换
3. ✅ 不直接返回 service 层的原始结果
4. ✅ 分页响应使用 camelCase: `pageSize`, `totalPages`

### Schema 设计规范
1. ✅ 所有 ID 字段使用 alias（如 `screenplayId`, `characterId`）
2. ✅ 复合词使用 camelCase（如 `wordCount`, `sceneCount`）
3. ✅ 时间戳字段使用 camelCase（如 `createdAt`, `updatedAt`）
4. ✅ 枚举字段使用 field_validator 转换类型

### 测试规范
1. ✅ Schema 层单元测试验证字段命名
2. ✅ 集成测试验证端到端字段名
3. ✅ 测试断言使用 camelCase 字段名

## 参考文档
- [API 设计规范](../references/api-design.md)
- [后端开发规范](../references/backend.md)
- [测试规范](../references/testing.md)