# ADR 004: 景别和运镜枚举标准化

> **状态**：已接受  
> **日期**：2025-01-27  
> **决策者**：架构团队  
> **影响范围**：前端、后端、数据库

---

## 背景

在开发分镜管理功能时，发现前后端对景别（Shot Size）和运镜（Camera Movement）的枚举定义不一致：

### 问题

1. **景别不一致**：
   - 前端有 8 种，后端只有 6 种
   - 命名格式不统一（前端用 `extreme_long_shot`，后端用 `extreme_long`）
   - 缺少关键镜头类型（如过肩镜头）

2. **运镜不一致**：
   - 前端有 `truck`、`arc`、`follow`
   - 后端有 `track`、`crane`、`handheld`
   - 两边各有侧重，无法互通

3. **专业性问题**：
   - 未参考国际影视行业标准
   - 部分术语不够专业或使用频率低

## 决策

基于国际影视行业标准（参考 FilmDaft、StudioBinder 等专业资料），统一前后端枚举定义。

### 景别（Shot Types）- 8 种

| 枚举值 | 中文 | 使用场景 |
|--------|------|----------|
| `extreme_wide_shot` | 大远景 | 建立场景、展示环境 |
| `wide_shot` | 远景 | 展示人物与环境关系 |
| `full_shot` | 全景 | 展示全身动作 |
| `medium_shot` | 中景 | 腰部以上，最常用 |
| `medium_close_up` | 中近景 | 胸部/肩部以上，对话 |
| `close_up` | 特写 | 面部情感表达 |
| `extreme_close_up` | 大特写 | 局部细节、戏剧张力 |
| `over_shoulder` | 过肩镜头 | 对话场景必备 |

**去掉的选项**：
- `medium_long_shot`（中远景）- 使用频率低
- `cowboy_shot`（牛仔镜头）- 仅特定类型片使用

**新增的选项**：
- `over_shoulder`（过肩镜头）- 对话场景最常用

### 运镜（Camera Movements）- 9 种

| 枚举值 | 中文 | 使用场景 |
|--------|------|----------|
| `static` | 固定 | 基础镜头 |
| `pan` | 摇镜 | 水平扫描 |
| `tilt` | 俯仰 | 垂直扫描 |
| `dolly` | 推拉 | 前后移动 |
| `zoom` | 变焦 | 焦距变化 |
| `tracking` | 跟踪 | 跟随主体 |
| `arc` | 环绕 | 圆周运动 |
| `crane` | 升降 | 垂直移动/摇臂 |
| `handheld` | 手持 | 纪录片风格 |

**合并的选项**：
- `follow` + `track` → `tracking`（使用专业术语）

**去掉的选项**：
- `truck`（横移）- 可用 dolly 侧向替代
- `pedestal`（升降）- 已被 crane 覆盖

## 理由

### 1. 专业性

- 基于国际影视行业标准（FilmDaft、StudioBinder、NFI 等权威资料）
- 使用专业术语，符合行业习惯
- 覆盖从广告片、短视频到电影、剧集的所有场景

### 2. 实用性

- 去除低频选项（如 cowboy_shot、truck）
- 新增高频选项（如 over_shoulder）
- 覆盖 95% 的实际拍摄场景

### 3. 一致性

- 前后端使用相同的枚举值
- 统一命名格式（snake_case）
- 便于数据交换和验证

### 4. 简洁性

- 景别 8 种，运镜 9 种
- 降低用户选择成本
- 每个选项都有明确的使用场景

## 影响

### 数据库

```sql
-- 需要更新 ENUM 类型定义
ALTER TYPE shot_size_type RENAME TO shot_size_type_old;
CREATE TYPE shot_size_type AS ENUM (
    'extreme_wide_shot',
    'wide_shot',
    'full_shot',
    'medium_shot',
    'medium_close_up',
    'close_up',
    'extreme_close_up',
    'over_shoulder'
);

ALTER TYPE camera_movement_type RENAME TO camera_movement_type_old;
CREATE TYPE camera_movement_type AS ENUM (
    'static',
    'pan',
    'tilt',
    'dolly',
    'zoom',
    'tracking',
    'arc',
    'crane',
    'handheld'
);
```

### 后端

- 更新 `app/models/storyboard.py` 中的 Enum 定义
- 更新 `app/schemas/storyboard.py` 中的 Schema 定义
- 更新文档 `docs/requirements/backend/04-services/project/storyboard-service.md`

### 前端

- 更新 `client/src/constants/storyboard.ts` 中的常量定义
- 更新 `client/src/types/storyboard.ts` 中的类型定义
- 可能需要更新使用这些常量的组件

### 数据迁移

如果数据库中已有数据，需要：
1. 创建迁移脚本
2. 映射旧值到新值
3. 更新现有记录

## 替代方案

### 方案 A：保持现状

**优点**：无需修改  
**缺点**：前后端不一致，不专业

### 方案 B：以前端为准

**优点**：前端已在使用  
**缺点**：缺少专业术语（如 over_shoulder）

### 方案 C：以后端为准

**优点**：后端更简洁  
**缺点**：分类不够细致

### 方案 D：统一为专业标准（已选择）

**优点**：专业、实用、一致  
**缺点**：需要同时修改前后端

## 验证

- ✅ 覆盖对话场景（medium_shot, medium_close_up, over_shoulder, close_up）
- ✅ 覆盖动作场景（wide_shot, full_shot, tracking, dolly, handheld）
- ✅ 覆盖情感特写（close_up, extreme_close_up, static, dolly）
- ✅ 覆盖建立场景（extreme_wide_shot, wide_shot, pan, crane）
- ✅ 覆盖艺术镜头（arc, crane, extreme_close_up）
- ✅ 覆盖纪录片风格（handheld, medium_shot, close_up）

## 参考资料

1. [FilmDaft - Guide to Camera Shots](https://filmdaft.com/camera-shots-moves-angles-overview-guide/)
2. [StudioBinder - Ultimate Guide to Camera Shots](https://www.studiobinder.com/blog/ultimate-guide-to-camera-shots/)
3. [NFI - Types of Film Shots](https://www.nfi.edu/types-of-film-shots/)
4. [Shotkit - 7 Essential Camera Movements](https://shotkit.com/camera-movements/)

## 相关文档

- [分镜管理服务文档](../../requirements/backend/04-services/project/storyboard-service.md)
- [数据库设计文档](../../requirements/database-design.md)

---

**决策日期**：2025-01-27  
**实施日期**：2025-01-27  
**审核人**：架构团队