# 专项 D：生成链生产化深化 - 规划文档

**专项负责人**：小虾 🦐  
**创建时间**：2026-06-19 10:50 GMT+8  
**状态**：🔄 进行中

---

## 一、专项目标

**把当前的 mock 生成逻辑改造为真实的媒体处理管线。**

从"返回假数据"提升到"真正能生成视频"。

---

## 二、当前状态

### 当前实现（Mock）

**位置**：`apps/worker/tasks.py::generate_video`

```python
def generate_video(task_id: str):
    # Mock: 直接创建一个假的生成结果
    session.add(GeneratedVideoModel(...))
    session.commit()
```

**问题**：
- 没有真实的视频处理
- 返回的是假的文件路径
- 无法真正下载视频

---

## 三、目标实现

### 真实生成流程

```
1. 获取生成任务
   ↓
2. 加载素材库中的素材
   ↓
3. 分析素材元数据（时长/分辨率/编码）
   ↓
4. 根据策略选择素材
   ↓
5. 使用 FFmpeg 进行视频合成
   - 拼接视频片段
   - 添加转场效果
   - 混音（如有配音）
   ↓
6. 生成缩略图
   ↓
7. 上传到 MinIO
   ↓
8. 创建 GeneratedVideo 记录
   ↓
9. 更新任务状态
```

---

## 四、技术方案

### 方案选择：使用 FFmpeg

**理由**：
- 功能强大，支持几乎所有视频格式
- Python 有成熟的 wrapper（ffmpeg-python）
- 性能好，命令行工具稳定

**替代方案**：
- MoviePy（太慢，不适合生产）
- OpenCV（功能有限）
- 云服务（成本高）

---

## 五、实现计划

### Phase 1：基础框架（本次）

- [ ] 安装 ffmpeg-python 依赖
- [ ] 创建 `VideoProcessor` 类
- [ ] 实现简单的视频拼接
- [ ] 生成缩略图
- [ ] 上传到 MinIO
- [ ] 更新 worker 逻辑

### Phase 2：高级功能（后续）

- [ ] 转场效果
- [ ] 字幕叠加
- [ ] 配音混音
- [ ] 滤镜效果
- [ ] 质量优化

---

## 六、架构设计

### 新增模块

```
apps/worker/
└── video_processing/
    ├── __init__.py
    ├── processor.py          # VideoProcessor 核心类
    ├── ffmpeg_wrapper.py     # FFmpeg 命令封装
    ├── thumbnail.py          # 缩略图生成
    └── strategies.py         # 生成策略
```

### VideoProcessor 接口

```python
class VideoProcessor:
    def generate_video(
        self,
        assets: List[Asset],
        strategy: Strategy,
        output_path: str
    ) -> VideoResult:
        """生成视频"""
        pass
    
    def generate_thumbnail(
        self,
        video_path: str,
        timestamp: float = 1.0
    ) -> str:
        """生成缩略图"""
        pass
```

---

## 七、MVP 范围（本次实现）

### ✅ 必须实现

1. **简单拼接**：
   - 把多个视频素材按顺序拼接
   - 输出单个 MP4 文件

2. **缩略图**：
   - 从视频第 1 秒截图

3. **存储**：
   - 上传到 MinIO
   - 返回正确的文件路径

4. **元数据**：
   - 正确记录时长/分辨率/大小

### ❌ 暂不实现

- 转场效果
- 字幕叠加
- 配音混音
- 复杂策略

---

## 八、验收标准

### 成功标准

- ✅ 能从素材库选择素材
- ✅ 能生成真实的 MP4 文件
- ✅ 文件能正常播放
- ✅ 缩略图正常显示
- ✅ 能从前端下载

### 失败标准

- ❌ FFmpeg 报错无法生成
- ❌ 生成的文件无法播放
- ❌ 文件路径错误

---

## 九、依赖和环境

### 系统依赖

- FFmpeg 4.0+ （需要预装）
- Python 3.12+

### Python 依赖

```
ffmpeg-python==0.2.0
pillow>=10.0.0
```

### 检查方式

```bash
ffmpeg -version
```

---

## 十、风险评估

### 已知风险

1. **FFmpeg 未安装**
   - 影响：无法生成视频
   - 应对：提供安装文档

2. **素材格式不兼容**
   - 影响：FFmpeg 报错
   - 应对：添加格式检查和转码

3. **生成时间长**
   - 影响：任务超时
   - 应对：设置合理的超时时间

4. **存储空间**
   - 影响：磁盘满
   - 应对：设置配额限制

---

## 十一、执行顺序

1. **环境检查**：确认 FFmpeg 可用
2. **创建模块**：video_processing 目录结构
3. **实现 Processor**：VideoProcessor 核心类
4. **集成 Worker**：更新 generate_video 任务
5. **测试验证**：生成真实视频
6. **文档更新**：添加部署文档

---

**状态**：准备开始执行  
**预计时间**：1-2 小时