docs/v1.0/server/changelogs/2026-02-06-screenplay-api-camelcase-fix.md

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 字段验证器：

@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 层测试

pytest tests/test_screenplay_response_fields.py -v
# ✅ 6 passed in 0.04s

集成测试

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 设计规范
• 后端开发规范
• 测试规范