# InfoGenie 前端架构文档 ## 项目概述 InfoGenie 是一个基于前后端分离架构的全栈 Web 应用，前端采用 React 单页应用（SPA）架构，结合静态 HTML 页面实现丰富的功能模块。后端提供 RESTful API 接口，支持用户认证、数据获取等核心功能。 ## 技术栈 ### 核心框架 - **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秒 ### 认证相关接口 #### 发送验证码 ```http POST /api/auth/send-verification Content-Type: application/json { "email": "user@example.com" } ``` #### 验证验证码 ```http POST /api/auth/verify-code Content-Type: application/json { "email": "user@example.com", "code": "123456" } ``` #### 用户登录 ```http POST /api/auth/login Content-Type: application/json { "email": "user@example.com", "password": "password" } ``` #### 用户注册 ```http POST /api/auth/register Content-Type: application/json { "email": "user@example.com", "password": "password", "verification_code": "123456" } ``` #### 用户登出 ```http POST /api/auth/logout Authorization: Bearer ``` #### 检查登录状态 ```http GET /api/auth/check Authorization: Bearer ``` ### 用户管理接口 #### 获取用户资料 ```http GET /api/user/profile Authorization: Bearer ``` #### 修改密码 ```http POST /api/user/change-password Authorization: Bearer Content-Type: application/json { "old_password": "old_password", "new_password": "new_password" } ``` #### 获取用户统计 ```http GET /api/user/stats Authorization: Bearer ``` #### 获取游戏数据 ```http GET /api/user/game-data Authorization: Bearer ``` #### 用户签到 ```http POST /api/user/checkin Authorization: Bearer ``` #### 删除账户 ```http POST /api/user/delete Authorization: Bearer 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 进行全局状态管理： ```javascript const UserContext = createContext(); export const UserProvider = ({ children }) => { const [user, setUser] = useState(null); const [isLoading, setIsLoading] = useState(true); const [isLoggedIn, setIsLoggedIn] = useState(false); // 用户登录、登出、状态检查等方法 }; ``` ### 本地存储 - 用户信息和 Token 存储在 localStorage 中 - 页面刷新后自动恢复用户状态 ## 路由设计 ```javascript const App = () => { return ( } /> } /> } /> } /> } /> } /> } /> ); }; ``` ## 响应式设计 - 移动优先设计理念 - 使用 CSS Grid 和 Flexbox 实现响应式布局 - 媒体查询适配不同屏幕尺寸 - 移动端使用底部导航栏，桌面端使用顶部导航 ## 安全考虑 ### 前端安全措施 - JWT Token 自动过期和刷新 - XSS 防护：使用 React 自动转义 - CSRF 防护：使用 SameSite Cookie - 输入验证：前端表单验证 ### API 安全要求 - 所有敏感接口需要 JWT 认证 - Token 存储在 localStorage，需要后端验证 - 密码等敏感信息前端不存储明文 - API 请求包含 CORS 配置 ## 部署和构建 ### 构建命令 ```bash npm run build # 生产环境构建 npm start # 开发环境启动 ``` ### 环境变量 - `REACT_APP_API_URL`: 后端 API 基础地址 - 支持 `.env` 文件配置不同环境的变量 ### PWA 支持 - 注册 Service Worker 实现离线缓存 - Web App Manifest 支持安装到桌面 ## 与后端协作要点 1. **API 接口约定**: 遵循 RESTful 设计原则，统一响应格式 2. **错误处理**: 后端返回统一的错误格式，前端统一处理 3. **认证流程**: JWT Token 的生成、验证和刷新机制 4. **数据格式**: 前后端约定清晰的数据结构 5. **跨域配置**: 后端需要配置 CORS 允许前端域名 6. **API 版本管理**: 使用 `/v2/` 前缀进行版本控制 7. **性能优化**: 考虑 API 响应时间和前端缓存策略 ## 萌芽币消费系统 ### 系统概述 萌芽币是平台内部的虚拟货币，用于限制和管理用户对AI功能的使用频率。每次调用AI功能需消耗100萌芽币，当用户萌芽币不足时，无法使用AI功能。 ### 技术实现 1. **萌芽币管理器**: `/public/aimodelapp/coin-manager.js` - 管理用户萌芽币余额和使用记录 - 提供UI组件显示萌芽币信息 - 实现API调用前的余额检查 2. **API集成**: - 在 `/src/utils/api.js` 中添加萌芽币查询接口 - 所有AI功能API调用必须添加JWT Token认证 - API调用后自动刷新萌芽币余额显示 3. **用户体验**: - 在页面右上角显示萌芽币余额和使用记录 - 当萌芽币不足时，提供友好的提示 - 引导用户通过签到等方式获取更多萌芽币 ### 接口设计 ```http GET /api/aimodelapp/coins Authorization: Bearer 响应: { "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" } ``` ### 页面集成流程 1. 引入萌芽币管理器 JavaScript 文件 2. 在API调用前检查萌芽币余额 3. 处理API响应中的萌芽币相关错误 4. API调用后刷新萌芽币信息 详细集成步骤请参考 [前端萌芽币消费系统集成文档](/前端萌芽币消费系统集成文档.md) ## 后续扩展建议 1. **状态管理升级**: 可考虑引入 Redux 或 Zustand 进行更复杂的状态管理 2. **组件库**: 可引入 Ant Design 或 Material-UI 统一 UI 组件 3. **测试覆盖**: 添加单元测试和集成测试 4. **性能监控**: 集成前端性能监控工具 5. **国际化**: 支持多语言切换功能 6. **萌芽币系统扩展**: - 实现萌芽币充值功能 - 针对不同AI功能设置差异化定价 - 添加萌芽币消费统计和分析功能