397 lines
9.1 KiB
Markdown
Executable File
397 lines
9.1 KiB
Markdown
Executable File
# InfoGenie 后端架构文档
|
||
|
||
## 项目概述
|
||
|
||
InfoGenie（万象口袋）是一个基于前后端分离架构的多功能聚合软件应用。后端采用Flask框架提供RESTful API服务，前端通过HTTP请求调用后端API，实现数据交互和业务逻辑处理。
|
||
|
||
## 技术栈
|
||
|
||
### 核心框架
|
||
- **Web框架**: Flask 2.3.3
|
||
- **数据库**: MongoDB (Flask-PyMongo 2.3.0)
|
||
- **认证**: JWT (PyJWT 2.8.0)
|
||
- **跨域**: Flask-CORS 4.0.0
|
||
|
||
### 辅助工具
|
||
- **邮件服务**: Flask-Mail 0.9.1
|
||
- **密码加密**: Werkzeug 2.3.7
|
||
- **环境配置**: python-dotenv 1.0.0
|
||
- **API限流**: Flask-Limiter 3.5.0
|
||
|
||
## 架构设计原则
|
||
|
||
### 前后端分离
|
||
- 后端专注于数据处理和业务逻辑
|
||
- 前端负责用户界面和交互体验
|
||
- 通过RESTful API进行数据交换
|
||
- 完全解耦，便于独立开发和部署
|
||
|
||
### 模块化设计
|
||
- 按功能划分独立模块
|
||
- 每个模块职责单一
|
||
- 便于维护和扩展
|
||
|
||
## 核心模块详解
|
||
|
||
### 1. 认证模块 (auth.py)
|
||
|
||
**功能职责**:
|
||
- 用户注册和登录
|
||
- JWT Token生成和管理
|
||
- 邮箱验证码验证
|
||
- QQ邮箱格式验证
|
||
|
||
**API端点**:
|
||
```
|
||
POST /api/auth/send-verification # 发送验证码
|
||
POST /api/auth/verify-code # 验证验证码
|
||
POST /api/auth/register # 用户注册
|
||
POST /api/auth/login # 用户登录
|
||
POST /api/auth/logout # 用户登出
|
||
GET /api/auth/check # 检查登录状态
|
||
```
|
||
|
||
**数据流程**:
|
||
1. 前端发送注册/登录请求
|
||
2. 后端验证邮箱格式（仅支持QQ邮箱）
|
||
3. 发送验证码邮件到用户邮箱
|
||
4. 用户输入验证码完成验证
|
||
5. 验证成功后生成JWT Token返回给前端
|
||
|
||
**安全特性**:
|
||
- 密码使用Werkzeug进行哈希加密
|
||
- JWT Token 7天有效期
|
||
- 验证码5分钟有效期，限制尝试次数
|
||
|
||
### 2. 用户管理模块 (user_management.py)
|
||
|
||
**功能职责**:
|
||
- 用户资料管理
|
||
- 密码修改
|
||
- 每日签到系统
|
||
- 用户游戏数据管理
|
||
- 账户删除
|
||
|
||
**API端点**:
|
||
```
|
||
GET /api/user/profile # 获取用户资料
|
||
POST /api/user/change-password # 修改密码
|
||
GET /api/user/stats # 获取用户统计
|
||
GET /api/user/game-data # 获取游戏数据
|
||
POST /api/user/checkin # 每日签到
|
||
POST /api/user/delete # 删除账户
|
||
```
|
||
|
||
**数据结构**:
|
||
```json
|
||
{
|
||
"邮箱": "user@qq.com",
|
||
"用户名": "用户名",
|
||
"密码": "哈希密码",
|
||
"头像": "QQ头像URL",
|
||
"注册时间": "2025-01-01T00:00:00",
|
||
"最后登录": "2025-01-01T00:00:00",
|
||
"登录次数": 10,
|
||
"用户状态": "active",
|
||
"等级": 5,
|
||
"经验": 1200,
|
||
"萌芽币": 1500,
|
||
"签到系统": {
|
||
"连续签到天数": 7,
|
||
"今日是否已签到": true,
|
||
"签到时间": "2025-01-01"
|
||
}
|
||
}
|
||
```
|
||
|
||
**业务逻辑**:
|
||
- 签到奖励：300萌芽币 + 200经验
|
||
- 等级升级：100 × 1.2^(等级) 经验需求
|
||
|
||
### 3. 邮件服务模块 (email_service.py)
|
||
|
||
**功能职责**:
|
||
- 验证码邮件发送
|
||
- QQ邮箱格式验证
|
||
- QQ头像获取
|
||
- 邮件模板管理
|
||
|
||
**邮件模板**:
|
||
- 注册验证码邮件（HTML格式）
|
||
- 登录验证码邮件（HTML格式）
|
||
- 支持自定义邮件内容和样式
|
||
|
||
**安全考虑**:
|
||
- 仅支持QQ邮箱（qq.com、vip.qq.com、foxmail.com）
|
||
- 使用SSL加密连接
|
||
- 验证码存储在内存中（生产环境建议使用Redis）
|
||
|
||
### 4. AI模型应用模块 (aimodelapp.py)
|
||
|
||
**功能职责**:
|
||
- 集成多种AI服务（DeepSeek、Kimi）
|
||
- 提供AI功能API接口
|
||
- 统一AI接口调用
|
||
- 管理用户萌芽币消费（每次调用消耗100萌芽币）
|
||
|
||
**支持的AI功能**:
|
||
1. **AI聊天接口** (`/api/aimodelapp/chat`)
|
||
2. **姓名分析** (`/api/aimodelapp/name-analysis`)
|
||
3. **变量命名助手** (`/api/aimodelapp/variable-naming`)
|
||
4. **AI写诗助手** (`/api/aimodelapp/poetry`)
|
||
5. **AI语言翻译** (`/api/aimodelapp/translation`)
|
||
6. **现代文转文言文** (`/api/aimodelapp/classical_conversion`)
|
||
7. **AI表情制作器** (`/api/aimodelapp/expression-maker`)
|
||
8. **Linux命令生成** (`/api/aimodelapp/linux-command`)
|
||
9. **获取可用模型** (`/api/aimodelapp/models`)
|
||
|
||
**AI配置**:
|
||
```json
|
||
{
|
||
"deepseek": {
|
||
"api_key": "your-api-key",
|
||
"api_base": "https://api.deepseek.com",
|
||
"model": ["deepseek-chat", "deepseek-reasoner"]
|
||
},
|
||
"kimi": {
|
||
"api_key": "your-api-key",
|
||
"api_base": "https://api.moonshot.cn",
|
||
"model": ["kimi-k2-0905-preview", "kimi-k2-0711-preview"]
|
||
}
|
||
}
|
||
```
|
||
|
||
**调用流程**:
|
||
1. 前端发送AI请求（包含消息、模型提供商等参数）
|
||
2. 后端加载AI配置文件
|
||
3. 调用对应AI API（带重试机制）
|
||
4. 返回AI响应给前端
|
||
|
||
## API设计规范
|
||
|
||
### 请求/响应格式
|
||
|
||
**成功响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {...},
|
||
"message": "操作成功",
|
||
"timestamp": "2025-01-01T00:00:00"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "错误信息",
|
||
"error": "错误详情"
|
||
}
|
||
```
|
||
|
||
### 认证方式
|
||
|
||
**JWT Token认证**:
|
||
```
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
**支持的认证端点**:
|
||
- 所有 `/api/user/*` 端点需要认证
|
||
- 部分 `/api/aimodelapp/*` 端点需要认证
|
||
|
||
### 错误处理
|
||
|
||
**HTTP状态码**:
|
||
- 200: 成功
|
||
- 400: 请求参数错误
|
||
- 401: 未认证/认证失败
|
||
- 403: 权限不足
|
||
- 404: 资源不存在
|
||
- 409: 资源冲突
|
||
- 500: 服务器内部错误
|
||
|
||
## 数据库设计
|
||
|
||
### MongoDB集合
|
||
|
||
**主要集合**: `userdata`
|
||
- 存储所有用户相关数据
|
||
- 支持动态字段扩展
|
||
- 使用ObjectId作为用户唯一标识
|
||
|
||
### 数据关系
|
||
- 用户数据自包含，无复杂关联
|
||
- 通过用户ID进行数据关联
|
||
- 支持水平扩展
|
||
|
||
## 部署和配置
|
||
|
||
### 环境配置
|
||
|
||
**必需环境变量**:
|
||
```
|
||
SECRET_KEY=your-secret-key
|
||
MONGO_URI=mongodb://localhost:27017/InfoGenie
|
||
MAIL_USERNAME=your-email@qq.com
|
||
MAIL_PASSWORD=your-app-password
|
||
```
|
||
|
||
### 启动方式
|
||
|
||
**开发环境**:
|
||
```bash
|
||
python app.py
|
||
```
|
||
|
||
**生产环境**:
|
||
- 支持Docker部署
|
||
- 提供docker-compose配置
|
||
- 支持Gunicorn WSGI服务器
|
||
|
||
### 静态文件服务
|
||
|
||
**支持的前端资源**:
|
||
- `/60sapi/*`: 60秒API相关文件
|
||
- `/smallgame/*`: 小游戏相关文件
|
||
- `/aimodelapp/*`: AI模型应用相关文件
|
||
|
||
## 安全考虑
|
||
|
||
### 数据安全
|
||
- 密码哈希存储
|
||
- JWT Token安全传输
|
||
- 输入数据验证和过滤
|
||
|
||
### API安全
|
||
- CORS配置（生产环境限制域名）
|
||
- API限流保护
|
||
- 请求日志记录
|
||
|
||
### 部署安全
|
||
- 环境变量管理敏感信息
|
||
- HTTPS证书配置
|
||
- 防火墙和访问控制
|
||
|
||
## 前后端协作指南
|
||
|
||
### 前端调用示例
|
||
|
||
**用户登录**:
|
||
```javascript
|
||
// 1. 发送验证码
|
||
fetch('/api/auth/send-verification', {
|
||
method: 'POST',
|
||
headers: { 'Content-Type': 'application/json' },
|
||
body: JSON.stringify({ email: 'user@qq.com', type: 'login' })
|
||
});
|
||
|
||
// 2. 验证验证码并登录
|
||
fetch('/api/auth/login', {
|
||
method: 'POST',
|
||
headers: { 'Content-Type': 'application/json' },
|
||
body: JSON.stringify({
|
||
email: 'user@qq.com',
|
||
code: '123456'
|
||
})
|
||
});
|
||
|
||
// 3. 保存token到localStorage
|
||
localStorage.setItem('token', response.token);
|
||
```
|
||
|
||
**调用需要认证的API**:
|
||
```javascript
|
||
fetch('/api/user/profile', {
|
||
method: 'GET',
|
||
headers: {
|
||
'Authorization': `Bearer ${localStorage.getItem('token')}`
|
||
}
|
||
});
|
||
```
|
||
|
||
### 数据约定
|
||
|
||
**前端发送数据格式**:
|
||
- 所有请求使用JSON格式
|
||
- 必填字段验证
|
||
- 参数命名使用snake_case
|
||
|
||
**后端返回数据格式**:
|
||
- 统一响应格式
|
||
- 时间戳使用ISO格式
|
||
- 错误信息清晰明确
|
||
|
||
### 开发协作流程
|
||
|
||
1. **API设计阶段**:
|
||
- 后端定义API接口规范
|
||
- 前端根据规范开发调用代码
|
||
- 约定数据格式和错误处理
|
||
|
||
2. **联调阶段**:
|
||
- 使用统一的测试数据
|
||
- 验证各种边界情况
|
||
- 确认错误处理逻辑
|
||
|
||
3. **部署阶段**:
|
||
- 后端部署API服务
|
||
- 前端配置API基础URL
|
||
- 验证跨域和认证配置
|
||
|
||
## 新功能添加
|
||
|
||
### 1. AI功能萌芽币消费系统
|
||
|
||
**功能描述**:
|
||
- 用户每次调用AI模型应用（aimodelapp）需消耗100萌芽币
|
||
- 当用户萌芽币余额不足时，无法使用AI功能
|
||
- 记录用户的AI使用历史
|
||
|
||
**API端点**:
|
||
```
|
||
GET /api/aimodelapp/coins # 查询用户萌芽币余额和使用历史
|
||
```
|
||
|
||
**技术实现**:
|
||
- 使用装饰器模式实现请求前验证和扣除萌芽币
|
||
- 在MongoDB中记录用户AI使用历史
|
||
- 通过JWT Token验证用户身份
|
||
|
||
**业务逻辑**:
|
||
1. 当用户请求AI功能时，首先验证JWT Token
|
||
2. 检查用户萌芽币余额是否≥100
|
||
3. 如余额充足，先扣除萌芽币，然后再调用AI服务
|
||
4. 记录使用历史，包括API类型、时间和消费萌芽币数量
|
||
5. 返回AI服务结果给用户
|
||
|
||
**响应示例（查询萌芽币余额）**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"coins": 200,
|
||
"ai_cost": 100,
|
||
"can_use_ai": true,
|
||
"username": "用户名",
|
||
"usage_count": 1,
|
||
"recent_usage": [
|
||
{
|
||
"api_type": "chat",
|
||
"cost": 100,
|
||
"timestamp": "2025-09-16T11:15:47.285720"
|
||
}
|
||
]
|
||
},
|
||
"message": "当前萌芽币余额: 200"
|
||
}
|
||
```
|
||
|
||
**前端开发注意事项**:
|
||
- 每个需要调用AI功能的页面应首先检查用户萌芽币余额
|
||
- 当萌芽币不足时，向用户提示并引导用户通过签到等方式获取萌芽币
|
||
- 可在UI中展示用户最近的AI使用记录和萌芽币消费情况
|
||
|
||
---
|