7.5 KiB

Raw Blame History

Storyboard Resource API CamelCase 规范验证

日期: 2026-02-06
类型: 规范验证
影响范围: server/app/api/v1/storyboard_resources.py 及相关 Schema
状态: ✅ 已验证，符合规范

概述

验证 Storyboard Resource API 的所有响应字段是否符合 camelCase 命名规范，确保前后端接口一致性。

验证内容

1. API 端点验证

验证以下 API 端点的响应字段命名：

分镜图片 API

GET /storyboards/{storyboard_id}/images - 获取图片列表
GET /storyboards/{storyboard_id}/images/active - 获取激活图片
POST /storyboards/{storyboard_id}/images - 创建图片
POST /storyboard-images/{image_id}/activate - 设置激活图片
DELETE /storyboard-images/{image_id} - 删除图片

分镜视频 API

GET /storyboards/{storyboard_id}/videos - 获取视频列表
GET /storyboards/{storyboard_id}/videos/active - 获取激活视频
POST /storyboards/{storyboard_id}/videos - 创建视频
POST /storyboard-videos/{video_id}/activate - 设置激活视频
DELETE /storyboard-videos/{video_id} - 删除视频

对白 API

GET /storyboards/{storyboard_id}/dialogues - 获取对白列表
POST /storyboards/{storyboard_id}/dialogues - 创建对白
PATCH /dialogues/{dialogue_id} - 更新对白
DELETE /dialogues/{dialogue_id} - 删除对白
POST /storyboards/{storyboard_id}/dialogues/reorder - 重新排序对白

配音 API

GET /dialogues/{dialogue_id}/voiceovers - 获取配音列表
GET /dialogues/{dialogue_id}/voiceovers/active - 获取激活配音
POST /dialogues/{dialogue_id}/voiceovers - 创建配音
POST /voiceovers/{voiceover_id}/activate - 设置激活配音
DELETE /voiceovers/{voiceover_id} - 删除配音

2. Schema 验证

验证以下 Response Schema 的字段命名（server/app/schemas/storyboard_resource.py）：

ImageResponse

✅ imageId (image_id)
✅ storyboardId (storyboard_id)
✅ statusStr (status_str)
✅ isActive (is_active)
✅ fileSize (file_size)
✅ storageProvider (storage_provider)
✅ storagePath (storage_path)
✅ aiModel (ai_model)
✅ aiPrompt (ai_prompt)
✅ aiPromptId (ai_prompt_id)
✅ aiParams (ai_params)
✅ errorMessage (error_message)
✅ createdAt (created_at)
✅ completedAt (completed_at)

VideoResponse

✅ videoId (video_id)
✅ storyboardId (storyboard_id)
✅ statusStr (status_str)
✅ isActive (is_active)
✅ frameRate (frame_rate)
✅ fileSize (file_size)
✅ storageProvider (storage_provider)
✅ storagePath (storage_path)
✅ aiModel (ai_model)
✅ aiParams (ai_params)
✅ errorMessage (error_message)
✅ createdAt (created_at)
✅ startedAt (started_at)
✅ completedAt (completed_at)

DialogueResponse

✅ dialogueId (dialogue_id)
✅ storyboardId (storyboard_id)
✅ characterId (character_id)
✅ characterName (character_name)
✅ dialogueType (dialogue_type)
✅ dialogueTypeStr (dialogue_type_str)
✅ sequenceOrder (sequence_order)
✅ startTime (start_time)
✅ createdAt (created_at)
✅ updatedAt (updated_at)

VoiceoverResponse

✅ voiceoverId (voiceover_id)
✅ dialogueId (dialogue_id)
✅ storyboardId (storyboard_id)
✅ audioUrl (audio_url)
✅ statusStr (status_str)
✅ isActive (is_active)
✅ voiceId (voice_id)
✅ voiceName (voice_name)
✅ fileSize (file_size)
✅ storageProvider (storage_provider)
✅ storagePath (storage_path)
✅ errorMessage (error_message)
✅ createdAt (created_at)
✅ completedAt (completed_at)

验证结果

✅ 代码已符合规范

所有 API 响应字段已正确使用 camelCase 命名规范：

Schema 层：所有 Response Schema 已使用 serialization_alias 来转换字段名
API 层：所有 API 端点正确使用 Schema 响应模型构建响应
数据转换：Pydantic 自动处理 snake_case → camelCase 的转换

测试覆盖

单元测试（✅ 全部通过）

创建了 server/tests/test_storyboard_resource_response_fields.py，包含：

✅ TestImageResponseFields::test_image_response_camel_case - 验证图片响应字段
✅ TestVideoResponseFields::test_video_response_camel_case - 验证视频响应字段
✅ TestDialogueResponseFields::test_dialogue_response_camel_case - 验证对白响应字段
✅ TestVoiceoverResponseFields::test_voiceover_response_camel_case - 验证配音响应字段
✅ TestDatetimeSerialization::test_datetime_fields_are_strings - 验证时间字段序列化
✅ TestUUIDSerialization::test_uuid_fields_are_strings - 验证 UUID 字段序列化
✅ TestDecimalSerialization::test_decimal_fields_in_dialogue - 验证对白 Decimal 字段
✅ TestDecimalSerialization::test_decimal_fields_in_voiceover - 验证配音 Decimal 字段

测试结果：8 个测试全部通过

pytest tests/test_storyboard_resource_response_fields.py -v
# ============================= 8 passed in 0.22s =============================

集成测试

现有集成测试 server/tests/integration/test_storyboard_resource_api.py 已包含对 camelCase 字段的验证：

验证 isActive 字段
验证 voiceName 字段
验证 dialogueOrders 请求字段

技术实现

Schema 定义示例

class ImageResponse(BaseModel):
    """分镜图片响应"""
    image_id: str = Field(..., serialization_alias="imageId", description="图片ID")
    storyboard_id: str = Field(..., serialization_alias="storyboardId", description="分镜ID")
    is_active: bool = Field(..., serialization_alias="isActive", description="是否激活")
    file_size: Optional[int] = Field(None, serialization_alias="fileSize", description="文件大小")
    storage_provider: Optional[str] = Field(None, serialization_alias="storageProvider", description="存储提供商")
    # ...
    
    model_config = ConfigDict(from_attributes=True)

API 层使用示例

@router.get("/storyboards/{storyboard_id}/images")
async def get_storyboard_images(...):
    images = await service.get_images(user_id, storyboard_id)
    return success_response(data=[
        ImageResponse(
            image_id=str(img.image_id),
            storyboard_id=str(img.storyboard_id),
            is_active=img.is_active,
            file_size=img.file_size,
            # ...
        )
        for img in images
    ])

自动转换

Pydantic 会自动使用 serialization_alias 进行转换：

# 内部使用 snake_case
response = ImageResponse(image_id="123", is_active=True)

# JSON 序列化时自动转换为 camelCase
response.model_dump(by_alias=True)
# 输出：{"imageId": "123", "isActive": true}

总结

Storyboard Resource API 的所有响应字段已完全符合 camelCase 命名规范，无需进行任何修复。通过单元测试和集成测试确保了规范的正确实施和维护。

后续建议

✅ 保持现有的 Schema 定义方式（使用 serialization_alias）
✅ 在创建新 API 时参考此模式
✅ 定期运行 test_storyboard_resource_response_fields.py 确保规范不被破坏
✅ 对其他 API 模块进行类似的验证（如需要）

7.5 KiB Raw Blame History