# 分镜素材关联 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`

```python
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：

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

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

**影响的测试**：
1. `test_batch_add_resources_success`
2. `test_batch_add_resources_partial_success`
3. `test_batch_remove_resources_success`
4. `test_batch_remove_resources_partial_success`

---

## 🧪 测试验证

### 单元测试
```bash
docker exec jointo-server-app pytest tests/unit/services/test_storyboard_project_resource_service.py -v
```

**结果**：✅ 14/14 通过

### 集成测试
```bash
docker exec jointo-server-app pytest tests/integration/test_storyboard_project_resource_api.py -v
```

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

### 字段序列化验证
```python
# 请求解析（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 端点：

1. **POST** `/api/v1/storyboards/{storyboard_id}/resources/batch`
   - 批量添加素材到分镜
   - 请求体：`BatchResourceRequest`
   - 响应体：`BatchResourceResponse`

2. **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

---

## ✅ 检查清单

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

---

## 🎯 结论

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