shumengya/InfoGenie

Fork 0

Files

shumengya 17691af8d1 继续完善

2025-09-16 12:57:36 +08:00

9.1 KiB

Executable File

Raw Blame History

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             # 检查登录状态

数据流程:

前端发送注册/登录请求
后端验证邮箱格式（仅支持QQ邮箱）
发送验证码邮件到用户邮箱
用户输入验证码完成验证
验证成功后生成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           # 删除账户

数据结构:

{
  "邮箱": "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功能:

AI聊天接口 (/api/aimodelapp/chat)
姓名分析 (/api/aimodelapp/name-analysis)
变量命名助手 (/api/aimodelapp/variable-naming)
AI写诗助手 (/api/aimodelapp/poetry)
AI语言翻译 (/api/aimodelapp/translation)
现代文转文言文 (/api/aimodelapp/classical_conversion)
AI表情制作器 (/api/aimodelapp/expression-maker)
Linux命令生成 (/api/aimodelapp/linux-command)
获取可用模型 (/api/aimodelapp/models)

AI配置:

{
  "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"]
  }
}

调用流程:

前端发送AI请求（包含消息、模型提供商等参数）
后端加载AI配置文件
调用对应AI API（带重试机制）
返回AI响应给前端

API设计规范

请求/响应格式

成功响应:

{
  "success": true,
  "data": {...},
  "message": "操作成功",
  "timestamp": "2025-01-01T00:00:00"
}

错误响应:

{
  "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

启动方式

开发环境:

python app.py

生产环境:

支持Docker部署
提供docker-compose配置
支持Gunicorn WSGI服务器

静态文件服务

支持的前端资源:

/60sapi/*: 60秒API相关文件
/smallgame/*: 小游戏相关文件
/aimodelapp/*: AI模型应用相关文件

安全考虑

数据安全

密码哈希存储
JWT Token安全传输
输入数据验证和过滤

API安全

CORS配置（生产环境限制域名）
API限流保护
请求日志记录

部署安全

环境变量管理敏感信息
HTTPS证书配置
防火墙和访问控制

前后端协作指南

前端调用示例

用户登录:

// 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:

fetch('/api/user/profile', {
  method: 'GET',
  headers: { 
    'Authorization': `Bearer ${localStorage.getItem('token')}` 
  }
});

数据约定

前端发送数据格式:

所有请求使用JSON格式
必填字段验证
参数命名使用snake_case

后端返回数据格式:

统一响应格式
时间戳使用ISO格式
错误信息清晰明确

开发协作流程

API设计阶段:
- 后端定义API接口规范
- 前端根据规范开发调用代码
- 约定数据格式和错误处理
联调阶段:
- 使用统一的测试数据
- 验证各种边界情况
- 确认错误处理逻辑
部署阶段:
- 后端部署API服务
- 前端配置API基础URL
- 验证跨域和认证配置

新功能添加

1. AI功能萌芽币消费系统

功能描述:

用户每次调用AI模型应用（aimodelapp）需消耗100萌芽币
当用户萌芽币余额不足时，无法使用AI功能
记录用户的AI使用历史

API端点:

GET  /api/aimodelapp/coins         # 查询用户萌芽币余额和使用历史

技术实现:

使用装饰器模式实现请求前验证和扣除萌芽币
在MongoDB中记录用户AI使用历史
通过JWT Token验证用户身份

业务逻辑:

当用户请求AI功能时，首先验证JWT Token
检查用户萌芽币余额是否≥100
如余额充足，先扣除萌芽币，然后再调用AI服务
记录使用历史，包括API类型、时间和消费萌芽币数量
返回AI服务结果给用户

响应示例（查询萌芽币余额）:

{
  "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使用记录和萌芽币消费情况

9.1 KiB Executable File Raw Blame History Unescape Escape

InfoGenie 后端架构文档

项目概述

技术栈

核心框架

辅助工具

架构设计原则

前后端分离

模块化设计

核心模块详解

1. 认证模块 (auth.py)

2. 用户管理模块 (user_management.py)

3. 邮件服务模块 (email_service.py)

4. AI模型应用模块 (aimodelapp.py)

API设计规范

请求/响应格式

认证方式

错误处理

数据库设计

MongoDB集合

数据关系

部署和配置

环境配置

启动方式

静态文件服务

安全考虑

数据安全

API安全

部署安全

前后端协作指南

前端调用示例

数据约定

开发协作流程

新功能添加

1. AI功能萌芽币消费系统

9.1 KiB

Executable File

Raw Blame History