init

开发文档/开发需求.md

@@ -0,0 +1,173 @@
+# 短视频解析平台 —— 开发需求文档
+
+## 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、站点信息、分组限制、并发数等）需持久化存储在数据库或配置表中，并在后台可视化管理。