4.3 KiB

Raw Blame History

分镜素材关联 API camelCase 修复

日期：2026-02-06
类型：Bug 修复
影响范围：API 层
状态：✅ 已完成

📋 问题描述

server/app/schemas/storyboard_project_resource.py 中的 BatchResourceRequest 模型未遵循 API 设计规范，请求字段未使用 camelCase 命名。

不符合规范的字段：

resource_ids ❌ 应该使用 resourceIds

✅ 修复内容

1. Schema 层修复

文件：server/app/schemas/storyboard_project_resource.py

class BatchResourceRequest(BaseModel):
    """批量操作素材请求"""
    resource_ids: List[str] = Field(..., alias="resourceIds", description="素材ID列表")
    
    model_config = ConfigDict(populate_by_name=True)

变更说明：

✅ 添加 alias="resourceIds" 使 API 层使用 camelCase
✅ 添加 populate_by_name=True 支持两种命名方式（兼容性）

2. 集成测试修复

文件：server/tests/integration/test_storyboard_project_resource_api.py

更新 4 处测试用例的请求 payload：

# 修改前
payload = {
    "resource_ids": resource_ids  # ❌ snake_case
}

# 修改后
payload = {
    "resourceIds": resource_ids   # ✅ camelCase
}

影响的测试：

test_batch_add_resources_success
test_batch_add_resources_partial_success
test_batch_remove_resources_success
test_batch_remove_resources_partial_success

🧪 测试验证

单元测试

docker exec jointo-server-app pytest tests/unit/services/test_storyboard_project_resource_service.py -v

结果：✅ 14/14 通过

集成测试

docker exec jointo-server-app pytest tests/integration/test_storyboard_project_resource_api.py -v

结果：✅ 12/17 通过（5 个失败是事件循环问题，非本次修复导致）

字段序列化验证

# 请求解析（camelCase -> snake_case）
request_json = '{"resourceIds": ["test1", "test2"]}'
request = BatchResourceRequest.model_validate_json(request_json)
# ✅ request.resource_ids == ['test1', 'test2']

# 响应序列化（snake_case -> camelCase）
response = StoryboardResourceResponse(...)
response_json = response.model_dump_json(by_alias=True)
# ✅ 所有字段使用 camelCase

📊 API 响应字段验证

BatchResourceRequest (请求)

内部字段 (snake_case)	API 字段 (camelCase)	状态
`resource_ids`	`resourceIds`	✅

StoryboardResourceResponse (响应)

内部字段 (snake_case)	API 字段 (camelCase)	状态
`storyboard_resource_id`	`storyboardResourceId`	✅
`storyboard_id`	`storyboardId`	✅
`project_resource_id`	`projectResourceId`	✅
`resource_type`	`resourceType`	✅
`display_order`	`displayOrder`	✅

BatchResourceResponse (响应)

内部字段 (snake_case)	API 字段 (camelCase)	状态
`success_count`	`successCount`	✅
`total_count`	`totalCount`	✅
`associations`	`associations`	✅

🔗 相关 API 端点

受影响的 API 端点：

POST /api/v1/storyboards/{storyboard_id}/resources/batch
- 批量添加素材到分镜
- 请求体：BatchResourceRequest
- 响应体：BatchResourceResponse
DELETE /api/v1/storyboards/{storyboard_id}/resources/batch
- 批量从分镜移除素材
- 请求体：BatchResourceRequest
- 响应体：SuccessResponse[None]

📚 参考文档

API 设计规范：.claude/skills/jointo-tech-stack/references/api-design.md
- 第 69-81 行：请求体字段使用 camelCase
- 第 323-327 行：响应字段使用 camelCase

✅ 检查清单

Schema 层添加 alias 配置
添加 populate_by_name=True
更新集成测试的请求 payload
运行单元测试验证
运行集成测试验证
验证请求解析（camelCase -> snake_case）
验证响应序列化（snake_case -> camelCase）
创建 changelog 文档

🎯 结论

本次修复确保了分镜素材关联 API 的请求和响应字段完全符合项目的 API 设计规范（camelCase），提高了 API 的一致性和前端集成的便利性。

4.3 KiB Raw Blame History