# 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秒

### 认证相关接口

#### 发送验证码
```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. 混合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 自动刷新机制，避免频繁登录
- **智能错误处理**：集中式的错误处理系统，提供用户友好的错误提示
- **渐进式数据加载**：重要数据优先加载，提升感知性能
- **离线访问支持**：关键功能支持离线访问，增强用户体验

## 后续扩展建议

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

## 技术债务与优化建议

### 1. 代码质量与一致性

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

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

### 2. 架构优化与重构

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

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

### 3. 前端基础设施升级

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

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

## 前端技术栈演进路线

### 近期优化（0-3个月）

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

### 中期规划（3-6个月）

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

### 长期展望（6-12个月）

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