# 技术设计文档

## 上下文
项目需要实现视频内容分析和总结功能，使用阿里云 DashScope 多模态 API 进行视频解析。系统需要支持视频上传、内容解析、自动总结以及多视频对比功能。

## 目标 / 非目标

### 目标
- 提供 RESTful API 用于视频文件上传和管理
- 集成阿里云 DashScope API 进行视频内容解析
- 自动生成视频内容总结
- 支持多个视频之间的内容对比
- 使用 MongoDB 持久化存储视频元数据和分析结果
- 提供简洁的静态前端页面进行交互

### 非目标
- 视频流式处理（当前仅支持文件上传）
- 实时视频分析（异步处理）
- 视频编辑功能
- 用户认证和权限管理（当前版本）

## 决策

### 1. 后端框架：Python Flask
**决策**：使用 Python Flask 构建 RESTful API 后端

**原因**：
- Python 对 AI/ML 生态支持良好，DashScope SDK 为 Python 原生
- Flask 轻量级，适合快速开发 RESTful API
- 易于集成第三方服务

**考虑的替代方案**：
- FastAPI：性能更好，但 Flask 更简单直接
- Django：功能完整但过于重量级

### 2. 数据库：MongoDB
**决策**：使用 MongoDB 存储视频元数据和分析结果

**原因**：
- 文档数据库适合存储非结构化的分析结果
- 灵活的 schema 便于扩展
- 项目已有 MongoDB 配置

**考虑的替代方案**：
- PostgreSQL：关系型数据库，但分析结果结构可能变化
- SQLite：轻量但不适合生产环境

### 3. 视频解析服务：阿里云 DashScope
**决策**：使用 DashScope MultiModalConversation API（qwen3-vl-plus 模型）

**原因**：
- 官方提供的多模态视频理解能力
- 支持视频抽帧分析（fps 参数）
- API 调用简单，集成方便

**配置要点**：
- fps 参数控制抽帧频率（默认 2，即每 0.5 秒一帧）
- API Key 通过环境变量或配置文件管理
- 需要处理 API 调用失败和重试

### 4. 文件存储：本地文件系统
**决策**：使用本地 uploads/ 目录存储视频文件

**原因**：
- 简单直接，无需额外服务
- 适合中小规模部署

**考虑的替代方案**：
- 对象存储（OSS/S3）：适合大规模部署，但增加复杂度
- 数据库存储：不适合大文件

### 5. 前端：静态页面
**决策**：使用纯 HTML/CSS/JavaScript 静态页面

**原因**：
- 简单直接，无需构建工具
- 易于部署和维护
- 满足当前功能需求

**考虑的替代方案**：
- React/Vue 框架：功能强大但增加复杂度
- 服务端渲染：当前不需要 SEO

## 架构设计

### 后端架构
```
app/
├── __init__.py          # Flask 应用初始化
├── config.py            # 配置管理
├── routes/
│   └── video_routes.py  # 视频相关路由
├── services/
│   ├── video_service.py      # 视频处理服务
│   ├── dashscope_service.py  # DashScope API 封装
│   └── analysis_service.py   # 分析业务逻辑
├── models/
│   ├── video.py         # 视频模型
│   ├── analysis.py      # 分析结果模型
│   └── comparison.py    # 对比结果模型
└── utils/
    ├── file_utils.py    # 文件处理工具
    └── validators.py    # 验证工具
```

### API 端点设计
```
POST   /api/videos/upload              # 上传视频
GET    /api/videos                      # 获取视频列表
GET    /api/videos/{video_id}           # 获取视频详情
POST   /api/videos/{video_id}/analyze   # 解析视频内容
POST   /api/videos/{video_id}/summarize # 生成视频总结
GET    /api/videos/{video_id}/summary   # 获取视频总结
POST   /api/videos/compare              # 对比多个视频
GET    /api/videos/compare/{comparison_id} # 获取对比结果
```

### 数据模型设计

**Video 文档**：
```python
{
  "_id": ObjectId,
  "filename": str,
  "file_path": str,
  "upload_time": datetime,
  "file_size": int,
  "status": str,  # "uploaded", "analyzing", "analyzed", "failed"
  "mime_type": str
}
```

**AnalysisResult 文档**：
```python
{
  "_id": ObjectId,
  "video_id": ObjectId,
  "analysis_type": str,  # "content", "summary"
  "content": str,
  "fps": int,
  "created_at": datetime
}
```

**Comparison 文档**：
```python
{
  "_id": ObjectId,
  "video_ids": [ObjectId],
  "comparison_result": str,
  "created_at": datetime
}
```

## 风险 / 权衡

### 风险
1. **API 调用失败** → 实现重试机制和错误处理
2. **大文件上传超时** → 设置合理的文件大小限制和超时时间
3. **视频解析耗时** → 异步处理，返回任务 ID，客户端轮询状态
4. **存储空间增长** → 定期清理或归档旧文件

### 权衡
- **同步 vs 异步处理**：当前采用同步处理，简单但可能阻塞。后续可改为异步任务队列
- **本地存储 vs 对象存储**：当前使用本地存储，简单但扩展性有限

## 迁移计划
- 无需迁移（新功能）

## 开放问题
- [ ] 是否需要实现视频文件清理策略（自动删除旧文件）？
- [ ] 是否需要支持批量视频上传？
- [ ] 视频解析的 fps 参数是否需要可配置？
- [ ] 是否需要实现解析结果缓存机制？