381 lines
10 KiB
Markdown
Executable File
381 lines
10 KiB
Markdown
Executable File
# 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 <token>
|
||
```
|
||
|
||
#### 检查登录状态
|
||
```http
|
||
GET /api/auth/check
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
### 用户管理接口
|
||
|
||
#### 获取用户资料
|
||
```http
|
||
GET /api/user/profile
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
#### 修改密码
|
||
```http
|
||
POST /api/user/change-password
|
||
Authorization: Bearer <token>
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"old_password": "old_password",
|
||
"new_password": "new_password"
|
||
}
|
||
```
|
||
|
||
#### 获取用户统计
|
||
```http
|
||
GET /api/user/stats
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
#### 获取游戏数据
|
||
```http
|
||
GET /api/user/game-data
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
#### 用户签到
|
||
```http
|
||
POST /api/user/checkin
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
#### 删除账户
|
||
```http
|
||
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 进行全局状态管理：
|
||
|
||
```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 (
|
||
<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 配置
|
||
|
||
## 部署和构建
|
||
|
||
### 构建命令
|
||
```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 <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"
|
||
}
|
||
```
|
||
|
||
### 页面集成流程
|
||
1. 引入萌芽币管理器 JavaScript 文件
|
||
2. 在API调用前检查萌芽币余额
|
||
3. 处理API响应中的萌芽币相关错误
|
||
4. API调用后刷新萌芽币信息
|
||
|
||
详细集成步骤请参考 [前端萌芽币消费系统集成文档](/前端萌芽币消费系统集成文档.md)
|
||
|
||
## 后续扩展建议
|
||
|
||
1. **状态管理升级**: 可考虑引入 Redux 或 Zustand 进行更复杂的状态管理
|
||
2. **组件库**: 可引入 Ant Design 或 Material-UI 统一 UI 组件
|
||
3. **测试覆盖**: 添加单元测试和集成测试
|
||
4. **性能监控**: 集成前端性能监控工具
|
||
5. **国际化**: 支持多语言切换功能
|
||
6. **萌芽币系统扩展**:
|
||
- 实现萌芽币充值功能
|
||
- 针对不同AI功能设置差异化定价
|
||
- 添加萌芽币消费统计和分析功能 |