shumengya/InfoGenie
2
2
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

继续更新

Browse Source
This commit is contained in:
树萌芽
2025-09-17 22:03:31 +08:00
parent 887f6fb5d6
commit 98c6371c4e
4 changed files with 273 additions and 734 deletions
Download Patch File Download Diff File Expand all files Collapse all files

163
InfoGenie-backend/DOCKER_README.md
View File

@@ -1,163 +0,0 @@
# InfoGenie 后端 Docker 部署指南
## 项目概述
InfoGenie 是一个基于 Flask 的 Python 后端应用，提供用户认证、AI 模型应用、小游戏等功能。
## Docker 部署
### 前置要求
- Docker >= 20.0
- Docker Compose >= 2.0
### 快速开始
1. **克隆项目并进入后端目录**
```bash
cd InfoGenie-backend
```
2. **设置环境变量**
```bash
cp .env.example .env # 如果有示例文件
# 编辑 .env 文件，设置必要的环境变量
```
3. **构建并运行**
```bash
# 方法1：使用构建脚本
./build_docker.sh
# 方法2：使用 Docker Compose（推荐）
docker-compose up -d
```
### 环境变量配置
在 `.env` 文件中配置以下变量：
```env
# Flask 配置
SECRET_KEY=your-secret-key-here
FLASK_ENV=production
# MongoDB 配置
MONGO_URI=mongodb://mongodb:27017/InfoGenie
# 邮件配置
MAIL_USERNAME=your-email@qq.com
MAIL_PASSWORD=your-app-password
# AI 配置（可选）
# 在 ai_config.json 中配置 AI API 密钥
```
### 服务端口
- 后端 API: `http://localhost:5002`
- MongoDB: `localhost:27017`
- 健康检查: `http://localhost:5002/api/health`
### Docker Compose 命令
```bash
# 启动服务
docker-compose up -d
# 查看日志
docker-compose logs -f infogenie-backend
# 停止服务
docker-compose down
# 重建镜像
docker-compose build --no-cache
# 清理数据卷
docker-compose down -v
```
### 单独构建 Docker 镜像
如果不需要 MongoDB，可以单独构建后端镜像：
```bash
# 构建镜像
docker build -t infogenie-backend:latest .
# 运行容器（需要外部 MongoDB）
docker run -d \
--name infogenie-backend \
-p 5002:5002 \
-e MONGO_URI=mongodb://your-mongo-host:27017/InfoGenie \
-e SECRET_KEY=your-secret-key \
infogenie-backend:latest
```
## 项目结构
```
InfoGenie-backend/
├── Dockerfile # Docker 镜像构建文件
├── docker-compose.yml # Docker Compose 配置
├── build_docker.sh # 构建脚本
├── .dockerignore # Docker 忽略文件
├── app.py # Flask 应用主入口
├── config.py # 应用配置
├── requirements.txt # Python 依赖
├── ai_config.json # AI 模型配置
├── modules/ # 功能模块
│ ├── auth.py # 用户认证
│ ├── user_management.py # 用户管理
│ ├── email_service.py # 邮件服务
│ └── aimodelapp.py # AI 模型应用
└── test/ # 测试文件
```
## 注意事项
1. **安全性**: 生产环境请使用强密码和随机生成的 SECRET_KEY
2. **数据库**: 默认使用 MongoDB 6.0，确保数据持久化
3. **端口**: 如需修改端口，请同时更新 Dockerfile 和 docker-compose.yml
4. **日志**: 应用日志通过 `docker-compose logs` 查看
5. **备份**: 重要数据请定期备份 MongoDB 数据卷
## 故障排除
### 常见问题
1. **端口占用**
```bash
# 检查端口占用
lsof -i :5002
# 修改端口映射
docker-compose up -d --scale infogenie-backend=0
docker-compose up -d
```
2. **数据库连接失败**
```bash
# 检查 MongoDB 状态
docker-compose ps
docker-compose logs mongodb
```
3. **构建失败**
```bash
# 清理缓存重新构建
docker system prune -f
docker-compose build --no-cache
```
## 开发环境
本地开发仍可使用原有的 `start_backend.sh` 脚本：
```bash
./start_backend.sh
```
## 许可证
本项目采用 MIT 许可证。

492
InfoGenie-backend/后端架构文档.md
View File

@@ -1,396 +1,166 @@
# InfoGenie 后端架构文档 # InfoGenie后端项目专业技术总结
## 项目概述 ## 项目架构概述
InfoGenie（神奇万事通）是一个基于前后端分离架构的多功能聚合软件应用。后端采用Flask框架提供RESTful API服务，前端通过HTTP请求调用后端API，实现数据交互和业务逻辑处理。 InfoGenie后端采用了**模块化、松耦合**的设计理念，基于Flask框架构建RESTful API服务，实现了前后端完全分离的现代Web应用架构。整体架构遵循了**单一职责原则**和**关注点分离原则**，各模块独立封装，通过清晰定义的API接口进行交互。
## 技术栈 ## 核心技术栈
### 核心框架 ### 基础框架
- **Web框架**: Flask 2.3.3 - **Web框架**: Flask 2.3.3（轻量、灵活、可扩展）
- **数据库**: MongoDB (Flask-PyMongo 2.3.0) - **API设计**: RESTful架构（资源导向、无状态通信）
- **认证**: JWT (PyJWT 2.8.0) - **数据库**: MongoDB（适用于文档型数据存储，通过Flask-PyMongo 2.3.0集成）
- **跨域**: Flask-CORS 4.0.0 - **认证机制**: JWT Token（PyJWT 2.8.0，支持7天有效期）
### 辅助工具 ### 中间件与辅助工具
- **邮件服务**: Flask-Mail 0.9.1 - **CORS支持**: Flask-CORS 4.0.0（解决跨域资源共享问题）
- **密码加密**: Werkzeug 2.3.7 - **密码安全**: Werkzeug 2.3.7（提供高强度密码哈希功能）
- **环境配置**: python-dotenv 1.0.0 - **邮件服务**: 基于SMTP协议的邮件发送（使用smtplib直接实现，无依赖Flask-Mail）
- **API限流**: Flask-Limiter 3.5.0 - **环境配置**: python-dotenv 1.0.0（分离配置与代码，增强安全性）
- **API限流**: Flask-Limiter 3.5.0（防止API滥用，提高系统稳定性）
## 架构设计原则 ## 架构设计亮点
### 前后端分离 ### 1. 应用工厂模式
- 后端专注于数据处理和业务逻辑 项目采用**应用工厂模式**（Factory Pattern）创建Flask应用实例，便于测试和多环境部署：
- 前端负责用户界面和交互体验 ```python
- 通过RESTful API进行数据交换 def create_app():
- 完全解耦，便于独立开发和部署 app = Flask(__name__)
app.config.from_object(Config)
### 模块化设计 # 初始化各种扩展和注册蓝图
- 按功能划分独立模块 return app
- 每个模块职责单一
- 便于维护和扩展
## 核心模块详解
### 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 # 检查登录状态
``` ```
**数据流程**: ### 2. 蓝图模块化设计
1. 前端发送注册/登录请求 采用Flask蓝图（Blueprint）实现功能模块化，提高代码复用性和可维护性：
2. 后端验证邮箱格式（仅支持QQ邮箱） - `auth_bp`: 用户认证模块
3. 发送验证码邮件到用户邮箱 - `user_bp`: 用户管理模块
4. 用户输入验证码完成验证 - `aimodelapp_bp`: AI模型应用模块
5. 验证成功后生成JWT Token返回给前端
**安全特性**: ### 3. 装饰器模式
- 密码使用Werkzeug进行哈希加密 大量使用装饰器模式实现横切关注点（Cross-cutting Concerns）如认证、权限验证、萌芽币消费等：
- JWT Token 7天有效期 ```python
- 验证码5分钟有效期，限制尝试次数 @verify_user_coins
def ai_function_endpoint():
### 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 # 删除账户
``` ```
**数据结构**: ### 4. 统一响应格式
实现了一致的API响应格式，便于前端处理：
```json
{
"success": true|false,
"data": {},
"message": "操作信息",
"timestamp": "ISO格式时间戳"
}
```
## 安全设计分析
### 1. 多层次认证体系
- **JWT Token认证**: 无状态认证机制，适合分布式部署
- **验证码邮箱认证**: 双因素认证提高安全性
- **QQ邮箱格式验证**: 限制注册邮箱类型，减少垃圾注册
### 2. 数据安全措施
- **密码哈希存储**: 使用Werkzeug提供的高强度哈希算法
- **敏感配置外部化**: 通过环境变量注入敏感配置
- **路径遍历防护**: 静态文件服务实现了路径限制检查
```python
if not os.path.commonpath([base_directory, full_path]) == base_directory:
return jsonify({'error': '非法文件路径'}), 403
```
### 3. 请求安全控制
- **API限流**: 防止暴力攻击和资源耗尽
- **CORS限制**: 生产环境可配置严格的跨域策略
- **请求参数验证**: 严格验证所有客户端输入
## 业务模块分析
### 1. 认证模块（auth.py）
实现了基于JWT的无状态认证系统，通过邮箱验证码进行用户身份确认，支持注册、登录和会话管理。设计重点包括：
- 验证码5分钟有效期机制
- JWT token 7天有效期管理
- 认证装饰器实现代码复用
### 2. 用户管理模块（user_management.py）
负责用户资料、签到系统、萌芽币管理等核心业务功能，实现了：
- 用户资料CRUD操作
- 每日签到奖励系统（经验值和萌芽币）
- 用户等级动态计算逻辑
### 3. AI模型应用模块（aimodelapp.py）
集成多种AI服务（DeepSeek、Kimi）并实现统一接口调用，特点：
- 萌芽币消费装饰器模式（每次调用消耗100萌芽币）
- AI调用带重试机制（提高系统稳定性）
- 多模型提供商支持（提高可用性和容错性）
### 4. 邮件服务模块（email_service.py）
负责验证码邮件发送、QQ邮箱格式验证等功能，特点：
- 直接使用smtplib实现，减少依赖
- HTML格式邮件模板支持
- 验证码管理机制（内存存储，生产环境建议使用Redis）
## 数据库设计
采用MongoDB文档型数据库，主要集合为`userdata`，存储用户相关所有数据。MongoDB的选择优势：
- **灵活的数据结构**: 适合存储复杂且不断演化的用户数据
- **文档自包含**: 减少关联查询，提高读取性能
- **水平扩展能力**: 支持未来系统规模扩展需求
用户数据模型设计合理，包含核心字段：
```json ```json
{ {
"邮箱": "user@qq.com", "邮箱": "user@qq.com",
"用户名": "用户名", "用户名": "用户名",
"密码": "哈希密码", "密码": "哈希密码",
"头像": "QQ头像URL", "头像": "QQ头像URL",
"注册时间": "2025-01-01T00:00:00", "注册时间": "ISO时间格式",
"最后登录": "2025-01-01T00:00:00",
"登录次数": 10,
"用户状态": "active",
"等级": 5,
"经验": 1200,
"萌芽币": 1500, "萌芽币": 1500,
"签到系统": { "签到系统": {
"连续签到天数": 7, "连续签到天数": 7,
"今日是否已签到": true, "今日是否已签到": true
"签到时间": "2025-01-01"
} }
} }
``` ```
**业务逻辑**: ## 部署与运维
- 签到奖励：300萌芽币 + 200经验
- 等级升级：100 × 1.2^(等级) 经验需求
### 3. 邮件服务模块 (email_service.py) ### 多环境配置支持
实现了开发、测试和生产环境的配置分离：
**功能职责**: ```python
- 验证码邮件发送 config = {
- QQ邮箱格式验证 'development': DevelopmentConfig,
- QQ头像获取 'production': ProductionConfig,
- 邮件模板管理 'testing': TestingConfig,
'default': DevelopmentConfig
**邮件模板**:
- 注册验证码邮件（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"]
}
} }
``` ```
**调用流程**: ### Docker化部署
1. 前端发送AI请求（包含消息、模型提供商等参数） 提供了完整的Docker化部署方案：
2. 后端加载AI配置文件 - Dockerfile定义应用容器
3. 调用对应AI API（带重试机制） - docker-compose.yml配置多容器协作
4. 返回AI响应给前端 - 支持环境变量注入敏感配置
## API设计规范 ## 技术亮点与优化空间
### 请求/响应格式 ### 亮点
1. **模块化设计**: 通过Flask蓝图实现功能解耦
2. **装饰器封装**: 横切关注点(cross-cutting concerns)集中处理
3. **统一错误处理**: 全局一致的错误响应机制
4. **AI服务抽象**: 屏蔽不同AI提供商的实现差异
**成功响应**: ### 优化空间
```json 1. **缓存机制**: 可引入Redis缓存验证码、热点数据等
{ 2. **异步处理**: 邮件发送、AI调用等耗时操作可改为异步执行
"success": true, 3. **日志系统**: 增强日志记录和监控能力
"data": {...}, 4. **单元测试**: 增加自动化测试覆盖率
"message": "操作成功",
"timestamp": "2025-01-01T00:00:00"
}
```
**错误响应**: ## 结论
```json
{
"success": false,
"message": "错误信息",
"error": "错误详情"
}
```
### 认证方式 InfoGenie后端项目展现了良好的软件工程实践，采用模块化设计、RESTful API架构和多层次安全控制，构建了一个可扩展、可维护的后端系统。该项目不仅满足了当前的业务需求，还为未来功能扩展和性能优化预留了空间。
**JWT Token认证**: 特别是在AI功能集成方面，通过抽象接口和装饰器模式，实现了业务逻辑与技术实现的分离，体现了良好的软件设计原则。萌芽币消费系统的实现也展示了面向业务模型的领域设计能力。
```
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使用记录和萌芽币消费情况
---

166
InfoGenie-backend/后端项目专业总结.md
View File

@@ -1,166 +0,0 @@
# InfoGenie后端项目专业技术总结
## 项目架构概述
InfoGenie后端采用了**模块化、松耦合**的设计理念，基于Flask框架构建RESTful API服务，实现了前后端完全分离的现代Web应用架构。整体架构遵循了**单一职责原则**和**关注点分离原则**，各模块独立封装，通过清晰定义的API接口进行交互。
## 核心技术栈
### 基础框架
- **Web框架**: Flask 2.3.3（轻量、灵活、可扩展）
- **API设计**: RESTful架构（资源导向、无状态通信）
- **数据库**: MongoDB（适用于文档型数据存储，通过Flask-PyMongo 2.3.0集成）
- **认证机制**: JWT Token（PyJWT 2.8.0，支持7天有效期）
### 中间件与辅助工具
- **CORS支持**: Flask-CORS 4.0.0（解决跨域资源共享问题）
- **密码安全**: Werkzeug 2.3.7（提供高强度密码哈希功能）
- **邮件服务**: 基于SMTP协议的邮件发送（使用smtplib直接实现，无依赖Flask-Mail）
- **环境配置**: python-dotenv 1.0.0（分离配置与代码，增强安全性）
- **API限流**: Flask-Limiter 3.5.0（防止API滥用，提高系统稳定性）
## 架构设计亮点
### 1. 应用工厂模式
项目采用**应用工厂模式**（Factory Pattern）创建Flask应用实例，便于测试和多环境部署：
```python
def create_app():
app = Flask(__name__)
app.config.from_object(Config)
# 初始化各种扩展和注册蓝图
return app
```
### 2. 蓝图模块化设计
采用Flask蓝图（Blueprint）实现功能模块化，提高代码复用性和可维护性：
- `auth_bp`: 用户认证模块
- `user_bp`: 用户管理模块
- `aimodelapp_bp`: AI模型应用模块
### 3. 装饰器模式
大量使用装饰器模式实现横切关注点（Cross-cutting Concerns）如认证、权限验证、萌芽币消费等：
```python
@verify_user_coins
def ai_function_endpoint():
# 业务逻辑
```
### 4. 统一响应格式
实现了一致的API响应格式，便于前端处理：
```json
{
"success": true|false,
"data": {},
"message": "操作信息",
"timestamp": "ISO格式时间戳"
}
```
## 安全设计分析
### 1. 多层次认证体系
- **JWT Token认证**: 无状态认证机制，适合分布式部署
- **验证码邮箱认证**: 双因素认证提高安全性
- **QQ邮箱格式验证**: 限制注册邮箱类型，减少垃圾注册
### 2. 数据安全措施
- **密码哈希存储**: 使用Werkzeug提供的高强度哈希算法
- **敏感配置外部化**: 通过环境变量注入敏感配置
- **路径遍历防护**: 静态文件服务实现了路径限制检查
```python
if not os.path.commonpath([base_directory, full_path]) == base_directory:
return jsonify({'error': '非法文件路径'}), 403
```
### 3. 请求安全控制
- **API限流**: 防止暴力攻击和资源耗尽
- **CORS限制**: 生产环境可配置严格的跨域策略
- **请求参数验证**: 严格验证所有客户端输入
## 业务模块分析
### 1. 认证模块（auth.py）
实现了基于JWT的无状态认证系统，通过邮箱验证码进行用户身份确认，支持注册、登录和会话管理。设计重点包括：
- 验证码5分钟有效期机制
- JWT token 7天有效期管理
- 认证装饰器实现代码复用
### 2. 用户管理模块（user_management.py）
负责用户资料、签到系统、萌芽币管理等核心业务功能，实现了：
- 用户资料CRUD操作
- 每日签到奖励系统（经验值和萌芽币）
- 用户等级动态计算逻辑
### 3. AI模型应用模块（aimodelapp.py）
集成多种AI服务（DeepSeek、Kimi）并实现统一接口调用，特点：
- 萌芽币消费装饰器模式（每次调用消耗100萌芽币）
- AI调用带重试机制（提高系统稳定性）
- 多模型提供商支持（提高可用性和容错性）
### 4. 邮件服务模块（email_service.py）
负责验证码邮件发送、QQ邮箱格式验证等功能，特点：
- 直接使用smtplib实现，减少依赖
- HTML格式邮件模板支持
- 验证码管理机制（内存存储，生产环境建议使用Redis）
## 数据库设计
采用MongoDB文档型数据库，主要集合为`userdata`，存储用户相关所有数据。MongoDB的选择优势：
- **灵活的数据结构**: 适合存储复杂且不断演化的用户数据
- **文档自包含**: 减少关联查询，提高读取性能
- **水平扩展能力**: 支持未来系统规模扩展需求
用户数据模型设计合理，包含核心字段：
```json
{
"邮箱": "user@qq.com",
"用户名": "用户名",
"密码": "哈希密码",
"头像": "QQ头像URL",
"注册时间": "ISO时间格式",
"萌芽币": 1500,
"签到系统": {
"连续签到天数": 7,
"今日是否已签到": true
}
}
```
## 部署与运维
### 多环境配置支持
实现了开发、测试和生产环境的配置分离：
```python
config = {
'development': DevelopmentConfig,
'production': ProductionConfig,
'testing': TestingConfig,
'default': DevelopmentConfig
}
```
### Docker化部署
提供了完整的Docker化部署方案：
- Dockerfile定义应用容器
- docker-compose.yml配置多容器协作
- 支持环境变量注入敏感配置
## 技术亮点与优化空间
### 亮点
1. **模块化设计**: 通过Flask蓝图实现功能解耦
2. **装饰器封装**: 横切关注点(cross-cutting concerns)集中处理
3. **统一错误处理**: 全局一致的错误响应机制
4. **AI服务抽象**: 屏蔽不同AI提供商的实现差异
### 优化空间
1. **缓存机制**: 可引入Redis缓存验证码、热点数据等
2. **异步处理**: 邮件发送、AI调用等耗时操作可改为异步执行
3. **日志系统**: 增强日志记录和监控能力
4. **单元测试**: 增加自动化测试覆盖率
## 结论
InfoGenie后端项目展现了良好的软件工程实践，采用模块化设计、RESTful API架构和多层次安全控制，构建了一个可扩展、可维护的后端系统。该项目不仅满足了当前的业务需求，还为未来功能扩展和性能优化预留了空间。
特别是在AI功能集成方面，通过抽象接口和装饰器模式，实现了业务逻辑与技术实现的分离，体现了良好的软件设计原则。萌芽币消费系统的实现也展示了面向业务模型的领域设计能力。

186
README.md
View File

@@ -13,12 +13,31 @@ InfoGenie 是一个前后端分离的多功能聚合应用，提供实时数据
### 🏗️ 技术架构 ### 🏗️ 技术架构
- **前端**: React 18.2.0 + Styled Components + React Router 6.15.0 + Axios #### 前端技术栈
- **后端**: Python Flask 2.3.3 + MongoDB + PyMongo 4.5.0 - **核心框架**: React 18.2.0 + React Router DOM 6.15.0
- **认证**: QQ邮箱验证 + 验证码登录 - **样式方案**: Styled Components 6.0.7 (CSS-in-JS)
- **邮件服务**: Flask-Mail + QQ SMTP - **HTTP客户端**: Axios 1.5.0
- **架构**: 前后端分离，RESTful API - **UI组件**: React Icons 4.11.0 + React Hot Toast 2.4.1
- **部署**: 支持Docker容器化部署 - **状态管理**: React Context API
- **构建工具**: Create React App
- **PWA支持**: Service Worker
#### 后端技术栈
- **Web框架**: Flask 2.3.3 (轻量、灵活、可扩展)
- **数据库**: MongoDB + PyMongo 4.5.0 (文档型数据存储)
- **认证机制**: JWT Token (PyJWT 2.8.0，7天有效期)
- **密码安全**: Werkzeug 2.3.7 (高强度密码哈希)
- **跨域支持**: Flask-CORS 4.0.0
- **API限流**: Flask-Limiter 3.5.0 (防止API滥用)
- **环境配置**: python-dotenv 1.0.0
- **邮件服务**: 基于SMTP协议的原生实现
#### 架构特点
- **前后端分离**: RESTful API架构，无状态通信
- **混合架构**: React SPA + 静态HTML页面无缝集成
- **模块化设计**: Flask蓝图 + React组件化
- **容器化部署**: Docker + docker-compose支持
- **多环境配置**: 开发/测试/生产环境分离
### 🌟 主要功能 ### 🌟 主要功能
@@ -36,10 +55,43 @@ InfoGenie 是一个前后端分离的多功能聚合应用，提供实时数据
- 即点即玩 - 即点即玩
#### 🤖 AI模型模块 #### 🤖 AI模型模块
- AI变量命名助手 - **AI变量命名助手**: 智能生成编程变量名
- AI写诗小助手 - **AI写诗小助手**: 基于主题创作诗歌
- AI姓名评测 - **AI姓名评测**: 姓名寓意分析和评分
- 需要登录验证 - **萌芽币消费系统**: 每次AI调用消耗100萌芽币
- **多模型支持**: 集成DeepSeek、Kimi等AI服务
- **需要登录验证**: JWT Token认证
#### 👤 用户系统
- **邮箱验证注册**: QQ邮箱验证码注册登录
- **用户资料管理**: 头像、用户名等个人信息
- **签到系统**: 每日签到获取经验值和萌芽币
- **等级系统**: 基于经验值的用户等级计算
- **萌芽币管理**: 虚拟货币系统，用于AI功能消费
- **使用统计**: AI调用次数和萌芽币消费记录
## 🏛️ 架构设计亮点
### 🔄 混合架构创新
- **React SPA核心层**: 处理用户认证、全局状态管理和主要导航逻辑
- **静态HTML模块**: 大量功能模块使用原生HTML/CSS/JS实现，降低加载时间
- **通信机制**: 通过postMessage API实现SPA与静态页面的数据交换
### 🧩 模块化设计
- **前端组件化**: 基于React的原子设计系统，从原子级别到页面级别
- **后端蓝图架构**: Flask蓝图实现功能模块解耦，提高可维护性
- **装饰器模式**: 横切关注点(认证、萌芽币消费)集中处理
### 🔒 安全与性能
- **多层次认证**: JWT Token + 邮箱验证码双因素认证
- **API限流保护**: 防止暴力攻击和资源耗尽
- **性能优化**: 代码分割、懒加载、PWA缓存策略
- **数据安全**: 密码哈希存储、敏感配置外部化
### 🚀 部署与扩展
- **容器化部署**: Docker + docker-compose支持
- **多环境配置**: 开发/测试/生产环境分离
- **微服务友好**: 模块化设计便于未来微服务拆分
## 🚀 快速开始 ## 🚀 快速开始
@@ -54,13 +106,13 @@ InfoGenie 是一个前后端分离的多功能聚合应用，提供实时数据
#### 后端依赖 #### 后端依赖
```bash ```bash
cd backend cd InfoGenie-backend
pip install -r requirements.txt pip install -r requirements.txt
``` ```
#### 前端依赖 #### 前端依赖
```bash ```bash
cd frontend/react-app cd InfoGenie-frontend
npm install npm install
``` ```
@@ -74,32 +126,64 @@ npm install
### 🖥️ 前端部署 ### 🖥️ 前端部署
1. 进入前端目录：`cd frontend/react-app` 1. 进入前端目录：`cd InfoGenie-frontend`
2. 安装依赖：`npm install` 2. 安装依赖：`npm install`
3. 构建生产环境应用：`npm run build` 3. 构建生产环境应用：`npm run build`
4. 将 `build` 目录下的所有文件上传到前端服务器的网站根目录 4. 将 `build` 目录下的所有文件上传到前端服务器的网站根目录
也可以直接运行 `frontend/react-app/deploy.bat` 脚本进行构建。 也可以直接运行 `InfoGenie-frontend/build_frontend.bat` 脚本进行构建。
### ⚙️ 后端部署 ### ⚙️ 后端部署
1. 进入后端目录：`cd backend` #### 方式一：传统部署
1. 进入后端目录：`cd InfoGenie-backend`
2. 安装依赖：`pip install -r requirements.txt` 2. 安装依赖：`pip install -r requirements.txt`
3. 配置环境变量或创建 `.env` 文件，包含以下内容： 3. 配置环境变量或创建 `.env` 文件：
``` ```env
MONGO_URI=你的MongoDB连接字符串 # 数据库配置
MAIL_USERNAME=你的邮箱地址 MONGO_URI=mongodb://localhost:27017/infogenie
MAIL_PASSWORD=你的邮箱授权码
SECRET_KEY=你的应用密钥 # 邮件服务配置
MAIL_USERNAME=your_email@qq.com
MAIL_PASSWORD=your_email_auth_code
MAIL_SERVER=smtp.qq.com
MAIL_PORT=587
# 应用配置
SECRET_KEY=your_secret_key_here
SESSION_COOKIE_SECURE=True SESSION_COOKIE_SECURE=True
FLASK_ENV=production
# AI服务配置
DEEPSEEK_API_KEY=your_deepseek_api_key
KIMI_API_KEY=your_kimi_api_key
``` ```
4. 使用 Gunicorn 或 uWSGI 作为 WSGI 服务器启动应用： 4. 使用 Gunicorn 启动应用：
``` ```bash
gunicorn -w 4 -b 0.0.0.0:5000 "app:create_app()" gunicorn -w 4 -b 0.0.0.0:5000 "app:create_app()"
``` ```
5. 配置反向代理，将 `https://infogenie.api.shumengya.top` 反向代理到后端服务
也可以参考 `backend/deploy.bat` 脚本中的部署说明。 #### 方式二：Docker部署（推荐）
1. 进入后端目录：`cd InfoGenie-backend`
2. 构建Docker镜像：
```bash
docker build -t infogenie-backend .
```
3. 使用docker-compose启动：
```bash
docker-compose up -d
```
4. 或者直接运行构建脚本：
```bash
./build_docker.sh # Linux/Mac
# 或
build_docker.bat # Windows
```
#### 环境配置说明
- **开发环境**: 使用 `.env` 文件配置本地开发环境
- **生产环境**: 使用 `.env.production` 文件或环境变量注入
- **反向代理**: 配置Nginx将 `https://infogenie.api.shumengya.top` 反向代理到后端服务
### ⚙️ 配置说明 ### ⚙️ 配置说明
@@ -129,23 +213,37 @@ npm install
``` ```
InfoGenie/ InfoGenie/
├── backend/ # 后端Python Flask应用 ├── InfoGenie-backend/ # 后端Python Flask应用
│ ├── app.py # 主应用入口 │ ├── app.py # 主应用入口
│ ├── config.py # 配置文件 │ ├── config.py # 配置文件
│ ├── requirements.txt # Python依赖 │ ├── requirements.txt # Python依赖
│ └── modules/ # 功能模块 │ ├── Dockerfile # Docker构建文件
│ ├── auth.py # 用户认证 │ ├── docker-compose.yml # Docker编排文件
│ ├── api_60s.py # 60s API接口 │ ├── .env # 环境变量配置
│ ├── user_management.py # 用户管理 │ ├── modules/ # 功能模块
│ ├── email_service.py # 邮件服务 │ │ ├── auth.py # 用户认证
│ ├── smallgame.py # 小游戏 │ │ ├── user_management.py # 用户管理
│ └── aimodelapp.py # AI模型应用 │ │ ├── email_service.py # 邮件服务
├── frontend/ # 前端应用 │ │ └── aimodelapp.py # AI模型应用
│ ├── react-app/ # React主应用 │ ├── test/ # 测试文件
│ ├── 60sapi/ # 60s API静态页面 │ └── 后端架构文档.md # 后端架构文档
│ ├── aimodelapp/ # AI模型应用页面 ├── InfoGenie-frontend/ # 前端应用
│ └── smallgame/ # 小游戏页面 │ ├── src/ # React源码
└── README.md # 项目说明 │ │ ├── components/ # 公共组件
│ │ ├── pages/ # 页面组件
│ │ ├── contexts/ # React Context
│ │ ├── utils/ # 工具函数
│ │ └── styles/ # 全局样式
│ ├── public/ # 静态资源
│ │ ├── 60sapi/ # 60s API静态页面
│ │ ├── aimodelapp/ # AI模型应用页面
│ │ └── smallgame/ # 小游戏页面
│ ├── package.json # 前端依赖
│ ├── setting.json # 前端配置
│ └── 前端架构文档.md # 前端架构文档
├── README.md # 项目说明
├── LICENSE # 许可证
└── 项目架构说明.txt # 项目架构说明
``` ```
#### 前端依赖 #### 前端依赖
@@ -166,14 +264,14 @@ npm install
**启动后端服务** **启动后端服务**
```bash ```bash
cd backend cd InfoGenie-backend
python app.py python app.py
# 后端服务: http://localhost:5002 # 后端服务: http://localhost:5002
``` ```
**启动前端服务** **启动前端服务**
```bash ```bash
cd frontend/react-app cd InfoGenie-frontend
npm start npm start
# 前端服务: http://localhost:3000 # 前端服务: http://localhost:3000
``` ```