JieXi/开发文档/开发需求.md

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

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。
   • 将第三方接口返回的数据统一映射为平台标准数据结构：

     {
       "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、站点信息、分组限制、并发数等）需持久化存储在数据库或配置表中，并在后台可视化管理。