videoSummary/openspec/changes/add-video-analysis-feature/design.md

技术设计文档

上下文

项目需要实现视频内容分析和总结功能，使用阿里云 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 文档：

{
  "_id": ObjectId,
  "filename": str,
  "file_path": str,
  "upload_time": datetime,
  "file_size": int,
  "status": str,  # "uploaded", "analyzing", "analyzed", "failed"
  "mime_type": str
}

AnalysisResult 文档：

{
  "_id": ObjectId,
  "video_id": ObjectId,
  "analysis_type": str,  # "content", "summary"
  "content": str,
  "fps": int,
  "created_at": datetime
}

Comparison 文档：

{
  "_id": ObjectId,
  "video_ids": [ObjectId],
  "comparison_result": str,
  "created_at": datetime
}

风险 / 权衡

风险

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

权衡

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

迁移计划

• 无需迁移（新功能）

开放问题

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