# 短视频解析平台 —— 开发需求文档

## 1. 项目概述

本项目是一个聚合多家短视频解析接口的 Web 平台，对外提供统一的视频解析服务。  
后台支持管理员管理解析接口、用户、站点配置等功能，并支持基础的限流与队列控制。

## 2. 技术栈与基础要求

- 后端语言：**Python**
- 数据库：**MySQL**
- 前端：Web 页面，需**适配移动端（响应式布局）**
- 部署形态：Web 应用（具体框架、部署方式可由开发时确定）

## 3. 主要功能模块

### 3.1 前台解析平台

1. 用户可在前台输入短视频链接，平台调用内部解析接口，返回统一格式的数据。
2. 平台内部对接多个解析接口（含多个哔哩哔哩解析接口），通过“适配器模式”进行统一封装。
3. 前台展示解析结果时，只需要以下字段：
   - 封面（cover）
   - 视频 URL（video_url）
   - 标题（title）
   - 简介（description）
4. 前台页面需要适配移动端，保证在手机端有良好显示与操作体验。

### 3.2 用户系统

1. **注册登录**
   - 用户通过**邮箱注册**，注册时需要邮箱验证码。
   - 支持登录、退出登录。
2. **邮箱验证码场景**
   - 用户注册
   - 重置密码
   - 找回密码  
   上述操作均需要发送邮箱验证码并进行校验。
3. **用户信息存储（MySQL）**
   - 用户名（名称）
   - 邮箱
   - 密码（需加密存储）
   - 注册 / 最近登录 IP
   - 使用解析的次数（可按总次数和/或按日统计）
   - 用户分组（如：游客、普通用户、VIP 用户、SVIP 用户）
4. **解析次数限制**
   - 未登录用户：每天最多解析 **5 次**
   - 已登录用户：每天最多解析 **10 次**
   - 管理员后台可根据用户所属分组自定义每日解析次数（见「用户分组管理」）。

### 3.3 用户分组与限流策略

1. 默认用户分组：**普通用户**
2. 预设分组类型（可在后台配置每日解析次数）：
   - 游客
   - 普通用户
   - VIP 用户
   - SVIP 用户
3. 功能需求：
   - 管理员可在后台给用户分配 / 修改所属分组。
   - 每个分组可单独配置“每日最大解析次数”。
   - 平台在用户发起解析时，需要根据分组和当日已用次数进行校验与限制。

### 3.4 队列与并发控制

1. 平台采用**队列模式**处理解析请求：
   - 多用户同时访问时，请求需要进入队列排队。
2. **并发上限控制**：
   - 默认最大并发解析数为 **3**。
   - 并发上限值需支持在后台由管理员配置。
3. 队列中的请求按照先进先出（FIFO）处理，并在前台给出简要提示（例如：排队中、预计等待等，可以简单实现）。

## 4. 解析接口与适配器设计

### 4.1 多解析接口接入

1. 在“开发文档文件夹”中有多个解析接口的 API 文档。
2. 平台需要为**每一个解析接口**开发独立的**适配器（Adapter）**：
   - 负责调用对应的第三方解析 API。
   - 将第三方接口返回的数据**统一映射**为平台标准数据结构：
     ```json
     {
       "cover": "...",
       "video_url": "...",
       "title": "...",
       "description": "..."
     }
     ```
3. 若某些 API **没有开发文档或示例返回值**：
   - 使用其自带的测试链接进行调用。
   - 开发过程中自行记录返回值结构和字段含义，并在代码或内部文档中进行整理记录。

### 4.2 哔哩哔哩多接口负载均衡与健康检查

1. 哔哩哔哩解析接口将接入 **3 个不同的接口**。
2. 平台需要对这 3 个接口做**负载均衡**，例如：
   - 轮询
   - 权重
   - 或按健康状态优先级选择
3. 管理员后台需提供任务配置：
   - 可以设置**定时任务**，定期对这三个 B 站接口执行健康检查。
   - 检查使用的视频链接由管理员在后台自行配置（如健康检查用的固定测试视频链接）。
4. **健康检查逻辑**：
   - 定时任务按设定时间间隔调用 3 个接口，对测试视频链接进行解析。
   - 如解析失败、超时或返回异常等，视为健康检查不通过。
   - 健康检查不通过时，需给管理员发送邮件告警（可简要说明是哪个接口异常）。

## 5. 管理员后台功能

### 5.1 管理员账户与安全

1. 默认管理员账号：
   - 用户名：`shihao`
   - 密码：`80012029Lz`
2. 管理员登录系统后，可以为自己的账号开启**二次验证（2FA）**：
   - 支持基于 TOTP（如 Google Authenticator）或其他实现方式（具体实现可由开发决定）。
3. 后台需要基本的权限控制，非管理员账号无法访问后台管理页面。

### 5.2 站点配置管理

管理员可以在后台管理以下站点级配置：

1. 网站基础信息
   - 网站 Logo（上传或填 URL）
   - 网站标题
   - 网站公告（可显示在前台）
   - 网站底部信息（如备案号、版权信息等）
2. 并发与队列配置
   - 最大并发解析数（默认 3，可修改）
3. 用户分组配置
   - 各分组每日解析次数限制
4. 解析接口管理
   - 各解析接口启用 / 禁用
   - 各接口权重（如用于简单负载均衡）
   - B 站接口健康检查测试链接配置及定时任务配置参数

### 5.3 SMTP 邮件配置与负载均衡

1. 系统初始使用一套**默认 SMTP 配置**。
2. 管理员可以在后台：
   - 修改默认 SMTP 配置
   - 新增多个 SMTP 配置
   - 对多个 SMTP 进行**负载均衡**（如轮询发送或故障切换）。
3. 提供**发送测试邮件**功能，方便管理员验证 SMTP 配置是否可用。
4. SMTP 配置将用于：
   - 用户注册验证码邮件
   - 找回密码 / 重置密码验证码邮件
   - 管理员通知邮件（例如接口健康检查失败告警）

### 5.4 统计与日志

管理员后台需要提供基础统计信息展示，包括但不限于：

1. 访问 / 解析统计
   - 按 IP 统计使用次数
   - 总解析次数、成功/失败次数
   - 按时间维度的分布（例如每日/每小时解析次数趋势）
2. 接口使用情况
   - 各解析接口被调用次数
   - 失败率、平均响应时间（可选，视实现复杂度）
3. 用户使用情况
   - 各用户解析次数
   - 各用户分组下的使用量对比

（统计精度可以根据实际实现情况简化，核心是能看到基本的 IP 使用、时间分布和接口使用情况）

---

## 6. 安全与其他要求

1. 用户密码必须进行加密存储（如使用 PBKDF2、bcrypt 等方式）。
2. 接口调用需做好基础的异常处理、超时控制及错误日志记录。
3. 对解析次数限制、队列和并发控制要在服务端进行校验，避免被前端绕过。
4. 所有配置项（如 SMTP、站点信息、分组限制、并发数等）需持久化存储在数据库或配置表中，并在后台可视化管理。