Xiaoxia AI
80a57ff0fe
Phase 6 completion: - Add Analytics page with charts (user growth, revenue, retention) - Add SystemMonitor page (CPU, memory, services health) - Add LogViewer page (log search, filtering, details) - Update sidebar navigation with Admin submenu - Add recharts to package.json for data visualization Phase 7 Day 1-2: - Create Asset and AssetLibrary domain entities - Define AssetRepository and AssetLibraryRepository interfaces - Implement InMemory repositories for testing - Implement PostgreSQL repository adapter - Update SQLAlchemy models for assets and asset_libraries - Add database migration script 004_asset_management.sql Architecture: Strict Clean Architecture compliance Testing: InMemory adapters ready for unit tests Database: Migration script with indexes and foreign keys
515 lines
12 KiB
Markdown
515 lines
12 KiB
Markdown
# 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 开发！** 🦐
|