# Phase 7: 核心视频剪辑业务 - 详细设计文档

> 版本：v1.0  
> 创建时间：2026-06-17  
> 负责人：小虾 🦐  
> 预计时间：4-6 周

---

## 📋 目标

基于 Phase 1-2 已完成的基础架构和 Phase 4-6 的 SAAS 产品化能力，实现核心视频剪辑业务功能，让用户能够完整走通从"上传素材"到"生成成片"的主链路。

---

## 🎯 核心目标（来自 MVP 范围文档）

根据 `saas-mvp-scope.md`，Phase 7 必须实现：

1. **素材管理** - 用户能上传素材、查看素材列表
2. **素材分类** - 系统能完成素材分类、给出准备度
3. **生成任务** - 用户能发起生成、查看任务进度
4. **成片结果** - 用户能查看并下载生成结果

**一句话：从"进入系统"到"拿到成片"这条主链必须完整跑通。**

---

## 📐 架构原则

严格遵循已建立的 Clean Architecture：

```
Domain Layer (领域层)
  ↓
Ports Layer (接口层)
  ↓
Application Layer (应用层 - Use Cases)
  ↓
Adapters Layer (适配器层)
  ↓
API Layer (FastAPI 路由)
```

**禁止：**
- 在 API 层写业务逻辑
- 在 Domain 层依赖外部框架
- 跳过 Use Case 直接调用 Repository

---

## 🗂️ 核心对象设计（来自 saas-core-objects.md）

### 1. Asset（素材）

**职责：**
- 表示用户上传的视频、图片、音频素材
- 记录文件元数据、存储位置、分类结果
- 关联到 Project 和 Workspace

**属性：**
```python
class Asset(BaseEntity):
    id: str                          # 素材 ID
    workspace_id: str                # 所属工作空间
    project_id: str                  # 所属项目
    asset_library_id: str            # 所属素材库
    
    # 文件信息
    name: str                        # 文件名
    file_type: AssetType             # 类型：video/image/audio
    file_size: int                   # 文件大小（字节）
    file_url: str                    # 存储地址（OSS）
    thumbnail_url: Optional[str]     # 缩略图地址
    duration: Optional[float]        # 视频时长（秒）
    
    # 元数据
    width: Optional[int]             # 视频宽度
    height: Optional[int]            # 视频高度
    fps: Optional[float]             # 帧率
    codec: Optional[str]             # 编码格式
    
    # 分类信息
    classification_status: ClassificationStatus  # pending/processing/completed/failed
    classification_result: Optional[dict]        # 分类结果（JSON）
    quality_score: Optional[float]               # 质量评分 0-100
    
    # 状态
    status: AssetStatus              # uploading/ready/processing/error
    uploaded_by_user_id: str         # 上传者
    created_at: datetime
    updated_at: datetime
```

### 2. AssetLibrary（素材库）

**职责：**
- 组织和管理素材
- 区分视频库、配音库、图片库

**属性：**
```python
class AssetLibrary(BaseEntity):
    id: str
    workspace_id: str
    project_id: Optional[str]        # 项目级或工作空间级
    name: str
    kind: LibraryKind                # video/voice/image
    asset_count: int                 # 素材数量
    total_size: int                  # 总大小（字节）
    created_at: datetime
```

### 3. GenerationTask（生成任务）

**职责：**
- 表示一次视频生成请求
- 追踪状态和进度

**属性：**
```python
class GenerationTask(BaseEntity):
    id: str
    workspace_id: str
    project_id: str
    
    # 策略
    strategy_id: Optional[str]       # 生成策略
    asset_library_id: str            # 使用的素材库
    voice_library_id: Optional[str]  # 使用的配音库
    
    # 状态
    status: TaskStatus               # pending/running/completed/failed/cancelled
    progress: float                  # 进度 0-100
    
    # 结果
    result_count: int                # 生成成片数量
    error_message: Optional[str]     # 错误信息
    
    # 时间
    started_at: Optional[datetime]
    completed_at: Optional[datetime]
    created_by_user_id: str
    created_at: datetime
```

### 4. GeneratedVideo（生成结果）

**职责：**
- 表示最终产出的成片

**属性：**
```python
class GeneratedVideo(BaseEntity):
    id: str
    workspace_id: str
    project_id: str
    generation_task_id: str          # 来源任务
    
    # 文件信息
    name: str
    file_url: str                    # 存储地址
    file_size: int
    duration: float
    thumbnail_url: Optional[str]
    
    # 元数据
    width: int
    height: int
    fps: float
    
    # 生成信息
    generated_at: datetime
    created_at: datetime
```

---

## 🔄 核心流程设计（来自 saas-core-flows.md）

### 流程一：上传素材

**步骤：**
1. 用户选择项目
2. 点击"上传素材"
3. 选择文件（支持拖拽）
4. 前端直传到阿里云 OSS
5. 获取 OSS 地址后调用 API 创建 Asset 记录
6. 返回素材列表

**API 设计：**
```
POST /api/v1/assets/upload-token
  → 获取 OSS 上传凭证
  
POST /api/v1/assets
  → 创建素材记录
  
GET /api/v1/assets?project_id={id}&library_id={id}
  → 查询素材列表
```

**关键规则：**
- 文件大小限制：视频 ≤ 500MB，图片 ≤ 10MB
- 支持格式：视频（mp4/mov/avi），图片（jpg/png），音频（mp3/wav）
- 自动生成缩略图
- 解析视频元数据（宽高、时长、编码）

---

### 流程二：素材分类

**步骤：**
1. 用户点击"分类素材"
2. 创建分类任务
3. Celery Worker 异步执行分类
4. 调用 AI 模型识别场景/人物/动作
5. 更新 Asset 的 classification_result
6. 前端轮询或 WebSocket 更新状态

**API 设计：**
```
POST /api/v1/assets/classify
  → 触发分类任务
  
GET /api/v1/assets/{id}/classification
  → 查询分类结果
```

**关键规则：**
- 分类任务异步执行
- 单个文件失败不影响其他
- 分类结果包括：场景标签、质量评分、建议
- 支持批量分类

---

### 流程三：发起生成任务

**步骤：**
1. 用户选择项目
2. 配置生成策略（选择素材库、配音库、数量）
3. 提交生成请求
4. 创建 GenerationTask
5. Celery Worker 执行视频生成
6. 生成成片保存到 OSS
7. 创建 GeneratedVideo 记录
8. 用户查看进度和结果

**API 设计：**
```
POST /api/v1/generation/tasks
  → 创建生成任务
  
GET /api/v1/generation/tasks/{id}
  → 查询任务状态
  
GET /api/v1/generation/tasks/{id}/results
  → 查询生成结果
```

**关键规则：**
- 生成任务异步执行
- 实时更新进度（0-100%）
- 支持取消任务
- 单次生成失败记录错误，不影响其他

---

### 流程四：查看和下载成片

**步骤：**
1. 用户打开"成片列表"
2. 查看缩略图和元信息
3. 点击预览或下载

**API 设计：**
```
GET /api/v1/generated-videos?project_id={id}
  → 成片列表
  
GET /api/v1/generated-videos/{id}
  → 成片详情
  
GET /api/v1/generated-videos/{id}/download-url
  → 获取下载地址（临时签名 URL）
```

**关键规则：**
- 下载地址有效期 1 小时
- 支持批量下载
- 显示生成时间和来源任务

---

## 📅 开发排期（4 周）

### Week 1: 素材管理基础（2026-06-17 ~ 2026-06-23）

#### Day 1-2: 数据模型与 Repository
- [ ] Asset 实体定义（Domain 层）
- [ ] AssetLibrary 实体定义
- [ ] AssetRepository 接口（Ports 层）
- [ ] AssetLibraryRepository 接口
- [ ] InMemory 实现（测试用）
- [ ] PostgreSQL 实现
- [ ] 数据库迁移脚本

#### Day 3-4: OSS 集成与上传
- [ ] 阿里云 OSS Adapter 实现
- [ ] 获取上传凭证 API
- [ ] 创建素材记录 Use Case
- [ ] 素材列表查询 Use Case
- [ ] 视频元数据提取（FFmpeg）

#### Day 5-6: 前端素材管理
- [ ] 素材库页面（列表、上传按钮）
- [ ] 拖拽上传组件
- [ ] 上传进度显示
- [ ] 素材卡片展示（缩略图、信息）
- [ ] 筛选和搜索

#### Day 7: 测试与优化
- [ ] 单元测试（Use Cases）
- [ ] 集成测试（API）
- [ ] 大文件上传测试
- [ ] 错误处理完善

---

### Week 2: 素材分类功能（2026-06-24 ~ 2026-06-30）

#### Day 1-2: 分类任务基础
- [ ] ClassificationJob 实体定义
- [ ] ClassificationJobRepository 接口
- [ ] 触发分类 Use Case
- [ ] 查询分类结果 Use Case
- [ ] Celery Task 定义

#### Day 3-4: AI 分类集成
- [ ] AI 模型 Adapter（Mock 或真实模型）
- [ ] 视频场景识别
- [ ] 质量评分算法
- [ ] 分类结果存储

#### Day 5-6: 前端分类展示
- [ ] 分类按钮
- [ ] 分类进度展示
- [ ] 分类结果标签显示
- [ ] 按分类筛选素材

#### Day 7: 测试与优化
- [ ] 分类准确性测试
- [ ] 批量分类压力测试
- [ ] 错误恢复测试

---

### Week 3: 视频生成功能（2026-07-01 ~ 2026-07-07）

#### Day 1-2: 生成任务模型
- [ ] GenerationTask 实体定义
- [ ] GenerationStrategy 实体定义
- [ ] GenerationTaskRepository 接口
- [ ] PostgreSQL 实现

#### Day 3-4: 生成逻辑实现
- [ ] 创建生成任务 Use Case
- [ ] 查询任务状态 Use Case
- [ ] Celery 生成 Worker
- [ ] 视频合成逻辑（FFmpeg）
- [ ] 进度更新机制

#### Day 5-6: 前端生成界面
- [ ] 生成配置页面
- [ ] 素材库选择
- [ ] 配音库选择
- [ ] 生成策略配置
- [ ] 提交生成按钮
- [ ] 任务进度实时展示

#### Day 7: 测试
- [ ] 生成成功路径测试
- [ ] 生成失败恢复测试
- [ ] 并发生成测试

---

### Week 4: 成片管理与收尾（2026-07-08 ~ 2026-07-14）

#### Day 1-2: 成片模型与查询
- [ ] GeneratedVideo 实体定义
- [ ] GeneratedVideoRepository 接口
- [ ] 成片列表查询 Use Case
- [ ] 下载地址签名 Use Case

#### Day 3-4: 前端成片页面
- [ ] 成片列表页面
- [ ] 视频预览播放器
- [ ] 下载按钮
- [ ] 批量下载功能

#### Day 5-6: 端到端集成
- [ ] 主链路完整测试（上传→分类→生成→下载）
- [ ] 性能优化
- [ ] 错误处理完善

#### Day 7: 文档与发布
- [ ] API 文档更新
- [ ] 用户使用文档
- [ ] 部署到测试环境
- [ ] Phase 7 完成总结

---

## 🔒 开发规则与约束

### 规则 1: 严格分层
- Domain 层不依赖任何框架
- Use Case 只调用 Repository 接口
- API 层只负责参数验证和路由

### 规则 2: 数据隔离
- 所有查询必须过滤 workspace_id
- 跨 Workspace 访问返回 403
- Project 必须属于 Workspace

### 规则 3: 文件存储
- 所有文件存储到阿里云 OSS
- 文件路径格式：`workspaces/{workspace_id}/assets/{asset_id}/file.mp4`
- 下载地址使用临时签名 URL（1 小时有效）

### 规则 4: 异步任务
- 长任务（分类、生成）必须异步执行
- 使用 Celery + Redis
- 任务状态存储到数据库
- 支持任务取消

### 规则 5: 错误处理
- 单个素材失败不影响批次
- 记录详细错误日志
- 用户友好的错误提示

### 规则 6: 配额限制
- 检查 Workspace 存储配额
- 上传前验证文件大小
- 超出配额提示升级

### 规则 7: 测试覆盖
- 每个 Use Case 至少 1 个单元测试
- 主链路至少 1 个集成测试
- API 端点至少 1 个测试

---

## 🎯 验收标准

Phase 7 完成的标准：

**功能完整性：**
- [ ] 用户可以上传视频、图片、音频素材
- [ ] 系统能自动分类素材并给出质量评分
- [ ] 用户可以配置策略并发起视频生成
- [ ] 系统能异步生成视频并展示进度
- [ ] 用户可以查看、预览、下载生成的成片

**技术指标：**
- [ ] 文件上传成功率 > 99%
- [ ] 分类准确率 > 85%
- [ ] 生成成功率 > 95%
- [ ] 单个视频生成时间 < 5 分钟
- [ ] API 响应时间 < 500ms

**质量标准：**
- [ ] 核心流程测试覆盖率 > 80%
- [ ] 无 P0/P1 Bug
- [ ] 代码符合 Clean Architecture
- [ ] API 文档完整

---

## 📝 技术栈

**后端：**
- FastAPI（API 层）
- Celery（异步任务）
- FFmpeg（视频处理）
- 阿里云 OSS SDK（文件存储）
- PostgreSQL（数据存储）
- Redis（任务队列）

**前端：**
- React 18（已有）
- Ant Design Upload 组件
- Video.js（视频播放器）

**AI 模型：**
- 一期可以 Mock
- 二期接入真实模型

---

## 🚫 明确不做的内容（一期范围外）

- 复杂的视频编辑功能
- 实时预览
- 协同编辑
- 视频模板市场
- 发布到外部平台
- 高级AI特效

---

**老大确认后，我就按这个详细设计开始 Phase 7 开发！** 🦐
