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