Files

2025-09-17 21:15:24 +08:00

15 KiB

Executable File

Raw Permalink Blame History

InfoGenie 前端架构文档

项目概述

InfoGenie 是一个基于前后端分离架构的全栈 Web 应用，前端采用 React 单页应用（SPA）架构，结合静态 HTML 页面实现丰富的功能模块。后端提供 RESTful API 接口，支持用户认证、数据获取等核心功能。项目实现了移动优先的响应式设计，通过统一的组件系统和数据流管理，提供了包括API数据展示、小游戏、AI工具等多样化功能模块。

技术栈

核心框架

React 18.2.0: 前端 UI 框架，使用函数式组件和 Hooks
React Router DOM 6.15.0: 客户端路由管理
Axios 1.5.0: HTTP 客户端，用于后端 API 调用

样式和 UI

styled-components 6.0.7: CSS-in-JS 样式解决方案
react-icons 4.11.0: 图标库
react-hot-toast 2.4.1: 通知提示组件

开发工具

Create React App: 项目脚手架
ESLint: 代码规范检查
Service Worker: PWA 支持

架构设计

整体架构

前端应用
├── React SPA (主要页面)
│   ├── 用户认证系统
│   ├── 导航和布局
│   ├── 页面路由
│   └── 用户管理
└── 静态 HTML 页面
    ├── API 数据展示页面
    ├── 小游戏页面
    └── AI 模型工具页面

文件结构

src/
├── components/          # 公共组件
│   ├── Header.js       # 顶部导航栏
│   ├── Navigation.js   # 底部导航栏（移动端）
│   └── Footer.js       # 页脚
├── pages/              # 页面组件
│   ├── HomePage.js     # 首页
│   ├── LoginPage.js    # 登录页面
│   ├── Api60sPage.js   # API 60s 页面
│   ├── SmallGamePage.js # 小游戏页面
│   ├── AiModelPage.js  # AI 模型页面
│   └── UserProfilePage.js # 用户资料页面
├── contexts/           # React Context
│   └── UserContext.js  # 用户状态管理
├── config/             # 配置文件
│   └── StaticPageConfig.js # 静态页面配置
├── utils/              # 工具函数
│   └── api.js          # API 调用封装
└── styles/             # 全局样式

API 接口设计

基础配置

Base URL: https://infogenie.api.shumengya.top (这是生产环境)(可通过环境变量 REACT_APP_API_URL 配置测试环境)
认证方式: JWT Bearer Token
请求格式: JSON
响应格式: JSON
超时时间: 10秒

认证相关接口

发送验证码

POST /api/auth/send-verification
Content-Type: application/json

{
  "email": "user@example.com"
}

验证验证码

POST /api/auth/verify-code
Content-Type: application/json

{
  "email": "user@example.com",
  "code": "123456"
}

用户登录

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password"
}

用户注册

POST /api/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password",
  "verification_code": "123456"
}

用户登出

POST /api/auth/logout
Authorization: Bearer <token>

检查登录状态

GET /api/auth/check
Authorization: Bearer <token>

用户管理接口

获取用户资料

GET /api/user/profile
Authorization: Bearer <token>

修改密码

POST /api/user/change-password
Authorization: Bearer <token>
Content-Type: application/json

{
  "old_password": "old_password",
  "new_password": "new_password"
}

获取用户统计

GET /api/user/stats
Authorization: Bearer <token>

获取游戏数据

GET /api/user/game-data
Authorization: Bearer <token>

用户签到

POST /api/user/checkin
Authorization: Bearer <token>

删除账户

POST /api/user/delete
Authorization: Bearer <token>
Content-Type: application/json

{
  "password": "password"
}

数据展示接口

前端包含大量静态页面用于展示各种 API 数据，这些页面直接调用后端提供的公开接口：

热搜榜单系列

百度实时热搜: GET /v2/baidu/realtime
百度贴吧话题榜: GET /v2/baidu/tieba
哔哩哔哩热搜榜: GET /v2/bilibili/hot
抖音热搜榜: GET /v2/douyin/hot
头条热搜榜: GET /v2/toutiao/hot
微博热搜榜: GET /v2/weibo/hot
小红书热点: GET /v2/xiaohongshu/hot
知乎热门话题: GET /v2/zhihu/hot
Hacker News 榜单: GET /v2/hackernews

日更资讯系列

必应每日壁纸: GET /v2/bing/wallpaper
历史上的今天: GET /v2/history/today
每日国际汇率: GET /v2/exchange/rates
每天60s读懂世界: GET /v2/60s/world

实用功能系列

百度百科词条: GET /v2/baike/search?keyword={keyword}
公网IP地址: GET /v2/ip/public
哈希解压压缩: POST /v2/hash/{algorithm}
链接OG信息: GET /v2/og?url={url}
密码强度检测: POST /v2/password/strength
农历信息: GET /v2/calendar/lunar?date={date}
配色方案: GET /v2/color/schemes
身体健康分析: POST /v2/health/analysis
生成二维码: POST /v2/qrcode/generate
实时天气: GET /v2/weather?location={location}
随机密码生成器: GET /v2/password/random
随机颜色: GET /v2/color/random
天气预报: GET /v2/weather/forecast?location={location}
在线翻译: POST /v2/translate
EpicGames免费游戏: GET /v2/epic/free-games

娱乐消遣系列

随机唱歌音频: GET /v2/entertainment/random-song
随机发病文学: GET /v2/entertainment/random-meme
随机搞笑段子: GET /v2/entertainment/random-joke
随机冷笑话: GET /v2/entertainment/random-pun
随机一言: GET /v2/entertainment/random-quote
随机运势: GET /v2/entertainment/random-fortune
随机JavaScript趣味题: GET /v2/entertainment/random-js-quiz
随机KFC文案: GET /v2/entertainment/random-kfc

状态管理

用户状态管理

使用 React Context 进行全局状态管理：

const UserContext = createContext();

export const UserProvider = ({ children }) => {
  const [user, setUser] = useState(null);
  const [isLoading, setIsLoading] = useState(true);
  const [isLoggedIn, setIsLoggedIn] = useState(false);

  // 用户登录、登出、状态检查等方法
};

本地存储

用户信息和 Token 存储在 localStorage 中
页面刷新后自动恢复用户状态

路由设计

const App = () => {
  return (
    <Router>
      <Routes>
        <Route path="/" element={<HomePage />} />
        <Route path="/login" element={<LoginPage />} />
        <Route path="/60sapi" element={<Api60sPage />} />
        <Route path="/smallgame" element={<SmallGamePage />} />
        <Route path="/aimodel" element={<AiModelPage />} />
        <Route path="/profile" element={<UserProfilePage />} />
        <Route path="*" element={<Navigate to="/" replace />} />
      </Routes>
    </Router>
  );
};

响应式设计

移动优先设计理念
使用 CSS Grid 和 Flexbox 实现响应式布局
媒体查询适配不同屏幕尺寸
移动端使用底部导航栏，桌面端使用顶部导航

安全考虑

前端安全措施

JWT Token 自动过期和刷新
XSS 防护：使用 React 自动转义
CSRF 防护：使用 SameSite Cookie
输入验证：前端表单验证

API 安全要求

所有敏感接口需要 JWT 认证
Token 存储在 localStorage，需要后端验证
密码等敏感信息前端不存储明文
API 请求包含 CORS 配置

部署和构建

构建命令

npm run build  # 生产环境构建
npm start      # 开发环境启动

环境变量

REACT_APP_API_URL: 后端 API 基础地址
支持 .env 文件配置不同环境的变量

PWA 支持

注册 Service Worker 实现离线缓存
Web App Manifest 支持安装到桌面

与后端协作要点

API 接口约定: 遵循 RESTful 设计原则，统一响应格式
错误处理: 后端返回统一的错误格式，前端统一处理
认证流程: JWT Token 的生成、验证和刷新机制
数据格式: 前后端约定清晰的数据结构
跨域配置: 后端需要配置 CORS 允许前端域名
API 版本管理: 使用 /v2/ 前缀进行版本控制
性能优化: 考虑 API 响应时间和前端缓存策略

萌芽币消费系统

系统概述

萌芽币是平台内部的虚拟货币，用于限制和管理用户对AI功能的使用频率。每次调用AI功能需消耗100萌芽币，当用户萌芽币不足时，无法使用AI功能。

技术实现

萌芽币管理器: /public/aimodelapp/coin-manager.js
- 管理用户萌芽币余额和使用记录
- 提供UI组件显示萌芽币信息
- 实现API调用前的余额检查
API集成:
- 在 /src/utils/api.js 中添加萌芽币查询接口
- 所有AI功能API调用必须添加JWT Token认证
- API调用后自动刷新萌芽币余额显示
用户体验:
- 在页面右上角显示萌芽币余额和使用记录
- 当萌芽币不足时，提供友好的提示
- 引导用户通过签到等方式获取更多萌芽币

接口设计

GET /api/aimodelapp/coins
Authorization: Bearer <token>

响应:
{
  "success": true,
  "data": {
    "coins": 200,
    "ai_cost": 100,
    "can_use_ai": true,
    "username": "用户名",
    "usage_count": 5,
    "recent_usage": [
      {
        "api_type": "chat",
        "cost": 100,
        "timestamp": "2025-09-16T11:15:47.285720"
      },
      ...
    ]
  },
  "message": "当前萌芽币余额: 200"
}

页面集成流程

引入萌芽币管理器 JavaScript 文件
在API调用前检查萌芽币余额
处理API响应中的萌芽币相关错误
API调用后刷新萌芽币信息

详细集成步骤请参考前端萌芽币消费系统集成文档

技术架构亮点

1. 混合SPA与静态页面的创新架构

InfoGenie 采用了创新的混合架构设计，将 React SPA 与大量静态 HTML 页面无缝集成，充分发挥两者的优势：

React SPA 核心层：处理用户认证、全局状态管理和主要导航逻辑，确保一致的用户体验
静态 HTML 模块：大量功能模块（API数据展示、小游戏、AI工具）使用原生HTML/CSS/JS实现，降低加载时间和资源消耗
通信机制：通过 postMessage API 和共享环境配置实现 SPA 与静态页面的数据交换和状态同步

2. 前端性能优化策略

项目实现了全面的性能优化，确保在各种设备上的流畅体验：

代码分割：基于路由的动态导入，减少首屏加载时间
资源预加载：关键资源预加载与懒加载策略结合
缓存策略：通过 Service Worker 实现静态资源和API响应的智能缓存
性能监控：页面加载性能关键指标（FCP、LCP、CLS）的实时监控与分析

3. 模块化与组件设计

采用高度模块化的组件设计模式，提升代码可维护性和扩展性：

原子设计系统：从原子级别组件到页面级别的多层组件设计体系
状态与UI分离：清晰的关注点分离，提高组件复用性
统一样式系统：基于 styled-components 的主题化设计系统
组件文档化：关键组件的详细使用说明和示例代码

4. 安全与用户体验融合

通过创新的用户体验设计，在保证安全性的同时提供流畅体验：

无感刷新认证：JWT Token 自动刷新机制，避免频繁登录
智能错误处理：集中式的错误处理系统，提供用户友好的错误提示
渐进式数据加载：重要数据优先加载，提升感知性能
离线访问支持：关键功能支持离线访问，增强用户体验

后续扩展建议

状态管理升级: 可考虑引入 Redux 或 Zustand 进行更复杂的状态管理
组件库: 可引入 Ant Design 或 Material-UI 统一 UI 组件
测试覆盖: 添加单元测试和集成测试，提高代码质量和可靠性
- Jest 与 React Testing Library 进行组件测试
- Cypress 进行端到端测试
- MSW 进行 API 模拟测试
性能监控: 集成 Lighthouse CI 和 Web Vitals 进行性能监控
国际化: 使用 i18next 支持多语言切换功能
萌芽币系统扩展:
- 实现萌芽币充值功能
- 针对不同AI功能设置差异化定价
- 添加萌芽币消费统计和分析功能
微前端架构: 考虑将大型功能模块转换为微前端架构，提高扩展性和团队协作效率
构建优化: 实施更先进的构建优化策略，如 Tree Shaking、代码分割、资源压缩等
渐进式Web应用升级: 强化PWA能力，增强离线使用体验和桌面安装功能

技术债务与优化建议

1. 代码质量与一致性

当前项目在开发过程中出现了一些不一致的编码风格和实践，需要通过以下措施进行标准化：

代码规范统一: 引入 ESLint + Prettier 强制执行统一的代码风格
类型安全增强: 考虑引入 TypeScript 或 PropTypes 进行类型检查，降低运行时错误
代码审查流程: 建立明确的代码审查规范和流程，确保代码质量
文档完善: 补充关键功能模块和核心组件的详细文档

2. 架构优化与重构

以下是需要关注的架构层面优化点：

API 层抽象: 当前的 API 调用过于分散，建议引入统一的 API 请求层和数据模型层
组件结构优化: 部分组件承担过多职责，应按照单一职责原则进行拆分
状态管理重构: 当前 Context API 的使用在大型应用中可能导致过度渲染，考虑引入更高效的状态管理方案
静态资源优化: 优化图像、字体等静态资源的加载策略，减少页面加载时间

3. 前端基础设施升级

为提高开发效率和项目可维护性，建议升级以下基础设施：

现代化构建工具: 考虑从 Create React App 迁移至 Vite，提升开发和构建速度
自动化测试框架: 建立单元测试、集成测试和 E2E 测试的完整体系
CI/CD 流程: 优化持续集成和部署流程，实现更敏捷的开发和发布
前端监控系统: 引入错误跟踪和性能监控系统，主动发现并解决问题

前端技术栈演进路线

近期优化（0-3个月）

架构文档完善: 补充架构决策记录(ADR)和技术选型依据
代码质量工具集成: ESLint、Prettier、Husky 配置统一
性能优化第一阶段: 首屏加载优化、资源懒加载实现
核心组件库重构: 提取可复用组件，建立组件文档

中期规划（3-6个月）

TypeScript 迁移: 核心模块向 TypeScript 迁移
状态管理升级: 评估并引入更适合的状态管理方案
自动化测试覆盖: 关键功能的单元测试和集成测试实现
微前端架构设计: 设计微前端架构方案，逐步迁移大型功能模块

长期展望（6-12个月）

新技术栈评估与升级: 评估 React 18+ 新特性应用
前端国际化支持: 实现多语言和本地化支持
无障碍访问标准实现: 符合 WCAG 2.1 AA 级标准
性能指标达成: 优化应用性能，使所有关键指标达到业界标准

15 KiB Executable File Raw Permalink Blame History Unescape Escape