# 移除剧本解析分镜数量参数

**日期**: 2026-02-09  
**类型**: Breaking Change  
**影响范围**: 剧本解析 API

## 变更概述

移除 `POST /api/v1/screenplays/{screenplay_id}/parse` 端点的 `storyboardCount` 参数，改为系统根据剧本内容自动决定分镜数量。

## 变更原因

1. **简化用户体验**: 用户无需手动指定分镜数量，减少决策负担
2. **智能化**: AI 可以根据剧本内容、剧情节奏、场景切换等因素智能生成合适数量的分镜
3. **参数冗余**: 已有 `auto_create_storyboards` 参数控制是否创建分镜，`storyboard_count` 参数显得多余

## 变更详情

### API 变更

**之前**:
```json
POST /api/v1/screenplays/{screenplay_id}/parse
{
  "customRequirements": "增加特写镜头",
  "storyboardCount": 10  // 已移除
}
```

**现在**:
```json
POST /api/v1/screenplays/{screenplay_id}/parse
{
  "customRequirements": "增加特写镜头"
}
```

### Schema 变更

**`ScreenplayParseRequest`**:
- ❌ 移除: `storyboard_count` 字段（及其 `storyboardCount` 别名）
- ✅ 保留: `custom_requirements` 字段

### 后端逻辑变更

1. **AI Service** (`server/app/services/ai_service.py`):
   - 移除 `storyboard_count` 参数
   - 更新日志输出

2. **AI Task** (`server/app/tasks/ai_tasks.py`):
   - 移除 `storyboard_count` 参数
   - 移除 Prompt 中的固定分镜数量要求
   - AI 根据剧本内容自动决定分镜数量

3. **API 路由** (`server/app/api/v1/screenplays.py`):
   - 移除 `request.storyboard_count` 的传递
   - 更新日志输出

### 测试变更

1. **Schema 测试** (`server/tests/unit/schemas/test_screenplay_parse_request.py`):
   - 移除所有 `storyboard_count` 相关测试
   - 保留 `custom_requirements` 测试

2. **集成测试** (`server/tests/integration/test_screenplay_api.py`):
   - 移除 `test_parse_screenplay_with_storyboard_count_only` 测试
   - 移除 `test_parse_screenplay_storyboard_count_validation` 测试
   - 更新 `test_parse_screenplay_with_custom_requirements` 测试
   - 新增 `test_parse_screenplay_without_requirements` 测试

## 向后兼容性

**Breaking Change**: 此变更不向后兼容。

- 前端如果仍然传递 `storyboardCount` 参数，Pydantic 会忽略该字段（不会报错）
- 建议前端尽快移除该参数的传递

## 迁移指南

### 前端迁移

**之前**:
```typescript
const response = await api.post(`/api/v1/screenplays/${id}/parse`, {
  customRequirements: "增加特写镜头",
  storyboardCount: 10  // 移除此行
});
```

**现在**:
```typescript
const response = await api.post(`/api/v1/screenplays/${id}/parse`, {
  customRequirements: "增加特写镜头"
  // 分镜数量由系统自动决定
});
```

### 后端迁移

如果有其他服务调用 `parse_screenplay` 方法，需要移除 `storyboard_count` 参数：

**之前**:
```python
await ai_service.parse_screenplay(
    user_id=user_id,
    screenplay_id=screenplay_id,
    screenplay_content=content,
    storyboard_count=10  # 移除此行
)
```

**现在**:
```python
await ai_service.parse_screenplay(
    user_id=user_id,
    screenplay_id=screenplay_id,
    screenplay_content=content
    # 分镜数量由 AI 自动决定
)
```

## 影响范围

### 受影响的文件

- `server/app/schemas/screenplay.py` - Schema 定义
- `server/app/api/v1/screenplays.py` - API 路由
- `server/app/services/ai_service.py` - AI Service
- `server/app/tasks/ai_tasks.py` - Celery Task
- `server/tests/unit/schemas/test_screenplay_parse_request.py` - Schema 测试
- `server/tests/integration/test_screenplay_api.py` - 集成测试

### 不受影响的功能

- `auto_create_storyboards` 参数仍然有效，控制是否创建分镜
- 分镜创建逻辑不变，仅数量由 AI 自动决定
- 其他剧本解析功能（角色、场景、道具、标签）不受影响

## 测试验证

### 单元测试

```bash
docker exec jointo-server-app pytest server/tests/unit/schemas/test_screenplay_parse_request.py -v
```

### 集成测试

```bash
docker exec jointo-server-app pytest server/tests/integration/test_screenplay_api.py::TestScreenplayParseAPI -v
```

## 后续优化

1. **AI Prompt 优化**: 调整 AI Prompt，让 AI 更智能地决定分镜数量
2. **分镜质量评估**: 收集用户反馈，评估自动分镜的质量
3. **可选参数恢复**: 如果用户强烈需要控制分镜数量，可以考虑恢复为可选参数

## 相关文档

- [剧本服务文档](../guides/screenplay-service.md)
- [AI 服务文档](../guides/ai-service.md)
- [API 设计规范](../../architecture/api-design-principles.md)