# #1197 预览生成接口方案评估

## 背景

智能剪辑「一键生成」流程中，第3步预览生成当前被跳过，直接进入下一步。需要实现真正的预览生成功能，让用户在正式生成前能看到效果预览。

## 现状分析

### 现有生成链路

```
API 触发生成 → GenerationTask入库 → Celery异步任务 → UnifiedRenderService渲染 → OSS上传 → 更新状态
```

**关键节点：**
1. **API层**：`POST /generation-tasks` 或 `POST /templates/{id}/generate` 触发生成
2. **任务调度**：Celery task `worker.generate_video`
3. **渲染引擎**：`UnifiedRenderService`（统一渲染引擎，已接入9个效果层）
4. **输出配置**：默认 720p (1280x720)，支持 `resolution` 字段自定义
5. **产物存储**：`GeneratedVideo` 表记录，OSS 存储视频文件

### 已有可复用能力

| 能力 | 位置 | 是否可复用 |
|------|------|-----------|
| 任务创建与状态管理 | `GenerationTask` + `CreateGenerationTaskUseCase` | ✅ 是 |
| 素材下载与预处理 | `_download_video_assets` / `_download_voice_asset` | ✅ 是 |
| 统一渲染引擎 | `UnifiedRenderService` | ✅ 是 |
| 分辨率配置 | `resolution` 字段已支持 | ✅ 是 |
| 混音与后处理 | `_render_video` 内流程 | ✅ 是 |
| OSS 上传与查重 | `_upload_and_dedup` | ✅ 是 |
| 进度追踪 | `append_log` / `progress` 字段 | ✅ 是 |

## 方案对比

### 方案A：复用现有生成链路 + is_preview 标记（推荐）

**思路**：在现有 GenerationTask 上加 `is_preview` 标记，预览生成走完整链路但参数降级。

**改动点：**
1. **数据模型**：`GenerationTask` 加 `is_preview: bool` 字段（默认 false）；`GeneratedVideo` 加 `is_preview: bool`
2. **API 层**：生成接口加 `is_preview` 参数，预览任务不计入配额
3. **渲染参数**：预览模式下自动调整
   - 分辨率：480p (854x480)
   - 时长：限制前 15 秒（或模板第一个片段）
   - 码率：降低至 1.5Mbps（正式 4Mbps）
   - 效果层：跳过高级转场/粒子特效等耗时效果
4. **任务调度**：预览任务走低优先级队列（或复用现有队列，标记优先级）
5. **前端对接**：预览生成结果带 `is_preview=true` 标记，前端展示"预览"标签

**优点：**
- 代码复用率 90%+，改动最小
- 与正式生成逻辑一致，预览效果真实可信
- 进度查询、结果展示等功能直接复用
- 后续可平滑升级：预览满意后一键转正式生成

**缺点：**
- 需要区分预览和正式任务，避免数据混淆
- 预览任务和正式任务竞争同一队列资源（可后续优化为独立队列）

**开发量估算**：2-3 天
- 数据模型 + 迁移：0.5 天
- API 层改造：0.5 天
- 渲染参数降级：1 天
- 测试 + 联调：1 天

---

### 方案B：新建独立预览接口 + 轻量渲染逻辑

**思路**：新建独立的预览生成接口，使用简化的渲染逻辑（如只拼接素材+基础配音，跳过大部分效果）。

**改动点：**
1. 新增 `PreviewTask` 数据模型
2. 新增 `POST /api/v1/preview/generate` 接口
3. 新增独立的 Celery task `worker.generate_preview`
4. 简化渲染流程：只做素材裁剪+拼接+配音，跳过转场/滤镜/字幕特效等

**优点：**
- 完全隔离，不影响正式生成链路
- 可以做极致优化，预览生成速度快
- 数据模型清晰，不会混淆

**缺点：**
- 代码重复率高，两套生成逻辑维护成本翻倍
- 预览效果与正式生成可能不一致（效果层差异）
- 前端需要对接两套接口
- 无法从预览升级为正式生成（需重新走完整流程）

**开发量估算**：4-5 天
- 数据模型 + 接口：1 天
- 简化渲染逻辑：2 天
- 测试 + 联调：1-2 天

---

### 方案C：图片预览（首帧/关键帧截图）

**思路**：不生成视频，只生成几张关键帧的预览图片。

**优点：**
- 生成速度极快（秒级）
- 资源消耗小

**缺点：**
- 预览效果差，用户无法感知动态效果
- 无法验证配音、转场、节奏等时间维度的效果
- 用户体验不佳，不如"真预览"有说服力

**开发量估算**：1-2 天

---

## 推荐方案：方案A（复用现有生成链路）

### 核心理由

1. **效果保真**：预览和正式生成用同一套渲染引擎，效果一致，用户信任度高
2. **开发效率**：90% 代码复用，2-3 天可上线
3. **可扩展性强**：后续可加「预览转正式」「低分辨率快速预览」等增强功能
4. **维护成本低**：一套生成逻辑，bug 修复和新功能同时生效

### 详细设计

#### 1. 数据模型变更

```python
# GenerationTask 新增字段
is_preview: bool = False
"""是否为预览生成"""

preview_of: str = ""
"""预览对应的正式任务 ID（或反向关联）"""

# GeneratedVideo 新增字段
is_preview: bool = False
"""是否为预览视频"""
```

**迁移**：alembic 新增 migration，两个表各加 1-2 个字段。

#### 2. API 层

```
POST /api/v1/generation-tasks
  Body 增加 is_preview: bool = false
  
POST /api/v1/templates/{id}/generate
  Query 增加 is_preview: bool = false
```

**配额处理**：预览生成不计入用户配额，不占用生成次数限制。

#### 3. 渲染参数降级

| 参数 | 正式生成 | 预览生成 |
|------|---------|---------|
| 分辨率 | 720p (1280x720) | 480p (854x480) |
| 码率 | 4 Mbps | 1.5 Mbps |
| 时长 | 完整时长 | 前 15 秒（或第一段） |
| 帧率 | 30 fps | 24 fps |
| 转场效果 | 完整转场 | 仅淡入淡出（或简单切） |
| 特效滤镜 | 全部启用 | 跳过粒子/光效等高级效果 |
| 字幕 | 完整渲染 | 正常渲染（字幕是核心信息） |
| 配音 | 完整混音 | 正常混音（配音是核心信息） |

**实现方式**：在 `_render_video` 或 UnifiedRenderService 入口处，根据 `is_preview` 标记调整渲染配置。

#### 4. 任务调度

- 初期复用现有队列，预览任务正常排队
- 后续如需优化，可拆分独立预览队列（低优先级）
- 预览任务可设置较短超时时间

#### 5. 前端对接

- 调用生成接口时传 `is_preview=true`
- 结果列表中预览视频带「预览」标签
- 预览满意后可一键「升级为正式生成」（重新触发全分辨率生成，可复用素材下载缓存）

### 实施步骤

**Phase 1（MVP，2天）：**
1. 数据模型 + 迁移
2. API 层支持 is_preview 参数
3. 渲染分辨率降级（480p）
4. 不计入配额
5. 基础测试

**Phase 2（优化，1-2天）：**
1. 时长限制（前15秒）
2. 效果层降级（跳高级效果）
3. 预览任务低优先级队列
4. 预览转正式生成功能

## 与前端对齐点

1. 预览生成的触发时机（第3步自动生成？用户点击才生成？）
2. 预览时长是固定15秒还是完整但低清？
3. 是否需要「预览转正式生成」功能
4. 预览视频的展示形态（和正式视频一样还是有特殊UI）

## 风险与注意事项

1. **数据混淆**：确保统计、计费、列表展示时正确区分预览和正式任务
2. **存储成本**：预览视频也占 OSS 空间，可设置自动清理（7天后自动删除）
3. **用户预期**：要明确告诉用户这是预览，效果和正式生成一致但清晰度低
4. **并发压力**：如果用户频繁生成预览，可能增加系统负载，需要限流