xiaoxia-saas/docs/PHASE7-DESIGN.md

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

属性：

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（素材库）

职责：

• 组织和管理素材
• 区分视频库、配音库、图片库

属性：

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（生成任务）

职责：

• 表示一次视频生成请求
• 追踪状态和进度

属性：

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（生成结果）

职责：

• 表示最终产出的成片

属性：

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 开发！ 🦐