feat: 更新项目代码
This commit is contained in:
612
README.md
612
README.md
@@ -1,248 +1,472 @@
|
||||
# InfoGenie 万象口袋
|
||||
|
||||
> 跨平台多功能聚合 Web 应用：资讯榜单、工具箱、小游戏、AI 工具等。
|
||||
# InfoGenie 前端架构文档
|
||||
|
||||
## 项目概述
|
||||
|
||||
InfoGenie 采用**前后端分离**架构：
|
||||
InfoGenie 是一个基于前后端分离架构的全栈 Web 应用，前端采用 React 单页应用（SPA）架构，结合静态 HTML 页面实现丰富的功能模块。后端提供 RESTful API 接口，支持用户认证、数据获取等核心功能。项目实现了移动优先的响应式设计，通过统一的组件系统和数据流管理，提供了包括API数据展示、小游戏、AI工具等多样化功能模块。
|
||||
|
||||
- **前端**：React 18（CRA）+ React Router + Styled Components，PWA；核心导航在 SPA 内，大量能力以 `public/` 下**静态 HTML** 嵌入（`FullscreenEmbed`）。
|
||||
- **后端**：**Go + Gin + GORM + MySQL**，提供健康检查、AI 代理等 REST 接口；用户登录与资料以**萌芽账户统一认证中心（Sprout Gate）**为准，详见仓库根目录 `SPROUT_GATE_API_DOCS.md`。
|
||||
- **个人中心**：仅**只读展示**认证中心同步的资料与统计；**每日签到、改资料、领萌芽币**请在认证中心完成，本站不提供签到按钮。
|
||||
## 技术栈
|
||||
|
||||
### 部署环境（示例）
|
||||
### 核心框架
|
||||
- **React 18.2.0**: 前端 UI 框架，使用函数式组件和 Hooks
|
||||
- **React Router DOM 6.15.0**: 客户端路由管理
|
||||
- **Axios 1.5.0**: HTTP 客户端，用于后端 API 调用
|
||||
|
||||
| 环境 | 地址 |
|
||||
|------|------|
|
||||
| 前端 | https://infogenie.shumengya.top |
|
||||
| 后端 API | https://infogenie.api.shumengya.top |
|
||||
| 认证中心 | 见前端 `REACT_APP_AUTH_URL` 配置 |
|
||||
### 样式和 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 18、React Router 6 | UI 与路由 |
|
||||
| Styled Components | 组件样式 |
|
||||
| Axios | 请求封装（业务 API + 认证中心 API） |
|
||||
| react-hot-toast | 提示 |
|
||||
| Service Worker | PWA 离线缓存 |
|
||||
|
||||
### 后端（`InfoGenie-go-backend/`）
|
||||
|
||||
| 技术 | 用途 |
|
||||
|------|------|
|
||||
| Go、Gin | HTTP 服务 |
|
||||
| GORM | MySQL ORM |
|
||||
| JWT（与 Sprout Gate 颁发令牌配合） | 鉴权相关逻辑以实际代码为准 |
|
||||
| godotenv | 环境变量 |
|
||||
|
||||
### 数据库
|
||||
|
||||
- **MySQL**：业务数据（如 AI 使用记录等），具体表结构见 Go 迁移/模型。
|
||||
|
||||
### 架构特点
|
||||
|
||||
- **混合前端**：列表页在 React（如 `Api60sPage`、`ToolboxPage`），详情以 iframe 全屏嵌入静态页，统一走 `FullscreenEmbed`。
|
||||
- **60s API 静态页**：`public/60sapi/**.html`；路由 **`/60sapi/:itemId`**（`Api60sItemPage`）通过 `Api60sConfig.js` 中 **`API_ITEM_STATIC_HTML`** 映射到对应 HTML。内嵌时加载 **`public/60sapi/ig-embed.js`**，在 iframe 内隐藏静态页自带顶栏，避免与外层重复。
|
||||
- **模块化**：前端 `components/`、`pages/`、`config/`；后端 `internal/handler`、`internal/service` 等分层。
|
||||
|
||||
---
|
||||
|
||||
## 功能模块（摘要）
|
||||
|
||||
- **60s API**：周期资讯、热门榜单、实用功能、娱乐消遣等；配置见 `infogenie-frontend/src/config/Api60sConfig.js`。
|
||||
- **工具箱**：`public/toolbox/` 下分 **`图片处理` / `实用工具` / `网页小玩具` / `学习工具`** 四类，入口 `ToolboxPage`（分类标签 + 卡片），点击嵌入；配置项 `offlineOk` 为真的工具在卡片上标 **「可离线」**（PWA 缓存后页面可本地加载，调用外网 API 或网络流仍要联网）。**`个人主页模板` 目录仅作临时资源，不参与工具箱配置与展示**，上线前可整体从 `public/` 剔除以减小体积。
|
||||
- **AI 应用**：入口 `AiModelPage`，静态页在 `public/aimodelapp/`；提示词集中在 **`public/aimodelapp/shared/ai-prompts.js`**，统一请求 **`/api/aimodelapp/chat`**。上游 **API Base / Key / 默认模型** 可由管理员在 `/admin` 写入 MySQL 表 **`site_ai_runtime`**（`GET/PUT /api/admin/site/ai-runtime`），优先于 `ai_config.json`。
|
||||
- **休闲游戏**：`public/smallgame/`。
|
||||
- **AI 工具**：`public/aimodelapp/` 等，消耗萌芽币策略以后端与认证中心对接为准。
|
||||
- **管理入口**：连续点击 Header **Logo 5 次** 输入管理员令牌进入 `/admin`（详见前端实现）。
|
||||
- **60s 功能展示开关**：条目定义仍在前端 `Api60sConfig.js`；**是否展示**由后端 MySQL 表 `site_60s_disabled` 控制。公开接口 `GET /api/site/60s-disabled` 返回 `{ "disabled": ["itemId", ...] }`；管理保存 `PUT /api/admin/site/60s-disabled`（请求头 `X-Site-Admin-Token`）需与后端环境变量 **`INFOGENIE_SITE_ADMIN_TOKEN`** 一致（开发环境可与管理员口令相同，见 `InfoGenie-go-backend/.env.development`）。
|
||||
- **60s 上游节点**：由表 **`site_60s_upstream`**（`source_id`: `self` | `official`）决定；`GET /api/site/60s-source` 供前端静默拉取（**不在** `/60sapi` 列表页展示域名）；管理员 `PUT /api/admin/site/60s-source`。静态页用 `sixty-runtime.js` + URL 参数 `sixty_base`，由 `Api60sItemPage` 注入 iframe。
|
||||
|
||||
---
|
||||
|
||||
## 项目结构（当前）
|
||||
## 架构设计
|
||||
|
||||
### 整体架构
|
||||
```
|
||||
InfoGenie/
|
||||
├── InfoGenie-go-backend/ # Go + Gin 后端
|
||||
│ ├── cmd/server/ # 入口 main
|
||||
│ ├── internal/ # handler / service / model / router 等
|
||||
│ └── go.mod
|
||||
├── infogenie-frontend/
|
||||
│ ├── public/
|
||||
│ │ ├── 60sapi/ # 60s 类静态页 + ig-embed.js
|
||||
│ │ ├── toolbox/
|
||||
│ │ ├── smallgame/
|
||||
│ │ ├── aimodelapp/
|
||||
│ │ ├── index.html # 入口与 PWA 启动屏
|
||||
│ │ └── manifest.json
|
||||
│ ├── scripts/
|
||||
│ │ └── inject-ig-embed.js # 批量为 60s 静态页注入 ig-embed（可选）
|
||||
│ ├── src/
|
||||
│ │ ├── App.js # 路由
|
||||
│ │ ├── components/ # Header、FullscreenEmbed、…
|
||||
│ │ ├── pages/ # 含 Api60sPage、Api60sItemPage、UserProfilePage、AdminPage…
|
||||
│ │ ├── contexts/UserContext.js
|
||||
│ │ ├── config/ # env.js、Api60sConfig.js、StaticPageConfig.js
|
||||
│ │ └── utils/api.js
|
||||
│ └── package.json
|
||||
├── SPROUT_GATE_API_DOCS.md # 萌芽统一认证接入说明（若在本仓库）
|
||||
└── README.md # 本文件
|
||||
前端应用
|
||||
├── 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 端点（Go 后端，常见前缀 `/api`）
|
||||
## API 接口设计
|
||||
|
||||
具体以 `InfoGenie-go-backend/internal/router` 为准，常见包括：
|
||||
### 基础配置
|
||||
- **Base URL**: `https://infogenie.api.shumengya.top` (这是生产环境)(可通过环境变量 `REACT_APP_API_URL` 配置测试环境)
|
||||
- **认证方式**: JWT Bearer Token
|
||||
- **请求格式**: JSON
|
||||
- **响应格式**: JSON
|
||||
- **超时时间**: 10秒
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| GET | `/` | 服务信息 |
|
||||
| GET | `/api/health` | 健康检查 |
|
||||
| GET | `/api/auth/check` 等 | 与历史兼容的鉴权检查（若仍保留） |
|
||||
| POST | `/api/aimodelapp/*` | 各类 AI 能力代理 |
|
||||
| GET | `/api/aimodelapp/coins` | 与 AI 消耗相关的查询 |
|
||||
### 认证相关接口
|
||||
|
||||
用户资料、签到等以 **认证中心 OpenAPI** 为准（前端通过 `REACT_APP_AUTH_API_URL` 访问）。
|
||||
#### 发送验证码
|
||||
```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"
|
||||
}
|
||||
```
|
||||
|
||||
- **Go** 1.21+（以后端 `go.mod` 为准）
|
||||
- **Node.js** 16+、npm
|
||||
- **MySQL**（开发/测试库连接串见后端 `.env` 或文档）
|
||||
#### 用户登录
|
||||
```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
|
||||
cd InfoGenie-go-backend
|
||||
# 配置 .env 中数据库、密钥、认证中心等
|
||||
go run ./cmd/server
|
||||
# 默认示例端口见 main 或配置，常见为 :5002
|
||||
npm run build # 生产环境构建
|
||||
npm start # 开发环境启动
|
||||
```
|
||||
|
||||
### 后端 Docker 部署（可选）
|
||||
### 环境变量
|
||||
- `REACT_APP_API_URL`: 后端 API 基础地址
|
||||
- 支持 `.env` 文件配置不同环境的变量
|
||||
|
||||
在 `InfoGenie-go-backend/` 目录：
|
||||
### PWA 支持
|
||||
- 注册 Service Worker 实现离线缓存
|
||||
- Web App Manifest 支持安装到桌面
|
||||
|
||||
1. 准备 **`.env.production`**（数据库、邮件、`INFOGENIE_SITE_ADMIN_TOKEN` 等），**不要**将其提交到仓库；镜像内不包含该文件。
|
||||
2. 构建并启动（**宿主机端口 `12364` → 容器内 `5002`**，容器名 **`infogenie-backend-go`**）：
|
||||
## 与后端协作要点
|
||||
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
```
|
||||
1. **API 接口约定**: 遵循 RESTful 设计原则，统一响应格式
|
||||
2. **错误处理**: 后端返回统一的错误格式，前端统一处理
|
||||
3. **认证流程**: JWT Token 的生成、验证和刷新机制
|
||||
4. **数据格式**: 前后端约定清晰的数据结构
|
||||
5. **跨域配置**: 后端需要配置 CORS 允许前端域名
|
||||
6. **API 版本管理**: 使用 `/v2/` 前缀进行版本控制
|
||||
7. **性能优化**: 考虑 API 响应时间和前端缓存策略
|
||||
|
||||
3. 健康检查：`http://<服务器IP>:12364/api/health`（或经反向代理后的域名）。
|
||||
4. 前端 `REACT_APP_API_URL` 应指向对外的 API 地址（例如经 Nginx 反代到 `127.0.0.1:12364` 的 `https://infogenie.api.shumengya.top`）。
|
||||
## 萌芽币消费系统
|
||||
|
||||
详见该目录下 `Dockerfile`、`docker-compose.yml`。
|
||||
### 系统概述
|
||||
萌芽币是平台内部的虚拟货币，用于限制和管理用户对AI功能的使用频率。每次调用AI功能需消耗100萌芽币，当用户萌芽币不足时，无法使用AI功能。
|
||||
|
||||
### 前端
|
||||
### 技术实现
|
||||
1. **萌芽币管理器**: `/public/aimodelapp/coin-manager.js`
|
||||
- 管理用户萌芽币余额和使用记录
|
||||
- 提供UI组件显示萌芽币信息
|
||||
- 实现API调用前的余额检查
|
||||
|
||||
```bash
|
||||
cd infogenie-frontend
|
||||
npm install
|
||||
npm start
|
||||
# http://localhost:3000
|
||||
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调用后刷新萌芽币信息
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
详细集成步骤请参考 [前端萌芽币消费系统集成文档](/前端萌芽币消费系统集成文档.md)
|
||||
|
||||
### 前端环境变量（示例）
|
||||
## 技术架构亮点
|
||||
|
||||
| 变量 | 说明 |
|
||||
|------|------|
|
||||
| `REACT_APP_API_URL` | 万象口袋 Go 后端根地址 |
|
||||
| `REACT_APP_AUTH_URL` | 认证中心前端地址 |
|
||||
| `REACT_APP_AUTH_API_URL` | 认证中心 API 根地址 |
|
||||
### 1. 混合SPA与静态页面的创新架构
|
||||
|
||||
以上变量在 **构建时** 写入前端包（Create React App）。修改后需重新执行 `npm run build`。
|
||||
InfoGenie 采用了创新的混合架构设计，将 React SPA 与大量静态 HTML 页面无缝集成，充分发挥两者的优势：
|
||||
- **React SPA 核心层**：处理用户认证、全局状态管理和主要导航逻辑，确保一致的用户体验
|
||||
- **静态 HTML 模块**：大量功能模块（API数据展示、小游戏、AI工具）使用原生HTML/CSS/JS实现，降低加载时间和资源消耗
|
||||
- **通信机制**：通过 postMessage API 和共享环境配置实现 SPA 与静态页面的数据交换和状态同步
|
||||
|
||||
---
|
||||
### 2. 前端性能优化策略
|
||||
|
||||
## 生产部署（前端）
|
||||
项目实现了全面的性能优化，确保在各种设备上的流畅体验：
|
||||
- **代码分割**：基于路由的动态导入，减少首屏加载时间
|
||||
- **资源预加载**：关键资源预加载与懒加载策略结合
|
||||
- **缓存策略**：通过 Service Worker 实现静态资源和API响应的智能缓存
|
||||
- **性能监控**：页面加载性能关键指标（FCP、LCP、CLS）的实时监控与分析
|
||||
|
||||
1. **安装与构建**（在 `infogenie-frontend/` 目录）
|
||||
```bash
|
||||
npm ci
|
||||
npm run build
|
||||
```
|
||||
产物为 `build/`：静态资源 + 单页 `index.html`。
|
||||
### 3. 模块化与组件设计
|
||||
|
||||
2. **构建前设置环境变量**（按线上域名填写，勿提交含密钥的 `.env` 到仓库）：
|
||||
- Linux/macOS：`REACT_APP_API_URL=https://你的后端域名 npm run build`
|
||||
- 或复制 `infogenie-frontend/.env.production.example` 为 `.env.production` 后执行 `npm run build`。
|
||||
采用高度模块化的组件设计模式，提升代码可维护性和扩展性：
|
||||
- **原子设计系统**：从原子级别组件到页面级别的多层组件设计体系
|
||||
- **状态与UI分离**：清晰的关注点分离，提高组件复用性
|
||||
- **统一样式系统**：基于 styled-components 的主题化设计系统
|
||||
- **组件文档化**：关键组件的详细使用说明和示例代码
|
||||
|
||||
3. **Web 服务器**
|
||||
- 将 `build/` 内全部文件部署到站点根目录（或子路径；若子路径需设置 CRA 的 `homepage` 并确认 `PUBLIC_URL`）。
|
||||
- **必须配置 SPA 回退**：所有未命中静态文件的路径应返回 `index.html`，否则刷新 `/toolbox`、`/60sapi/xxx` 等会 404。
|
||||
- **Nginx 示例**（站点根部署）：
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl;
|
||||
server_name infogenie.example.com;
|
||||
root /var/www/infogenie/build;
|
||||
index index.html;
|
||||
location / {
|
||||
try_files $uri $uri/ /index.html;
|
||||
}
|
||||
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
|
||||
expires 7d;
|
||||
add_header Cache-Control "public, immutable";
|
||||
}
|
||||
}
|
||||
```
|
||||
### 4. 安全与用户体验融合
|
||||
|
||||
4. **HTTPS**
|
||||
- 全站建议 HTTPS；OAuth 回调域名须与认证中心登记一致。
|
||||
通过创新的用户体验设计，在保证安全性的同时提供流畅体验：
|
||||
- **无感刷新认证**：JWT Token 自动刷新机制，避免频繁登录
|
||||
- **智能错误处理**：集中式的错误处理系统，提供用户友好的错误提示
|
||||
- **渐进式数据加载**：重要数据优先加载，提升感知性能
|
||||
- **离线访问支持**：关键功能支持离线访问，增强用户体验
|
||||
|
||||
5. **PWA**
|
||||
- 生产环境会注册 Service Worker（见 `src/index.js`）。更新前端后用户可能需刷新或等待 SW 更新；大版本升级可 bump `public/manifest.json` 的 `version` / `name` 便于识别。
|
||||
## 后续扩展建议
|
||||
|
||||
6. **后端**
|
||||
- 单独部署 `InfoGenie-go-backend`（示例：`https://infogenie.api.shumengya.top`），与前端站点（示例：`https://infogenie.shumengya.top`）分域时，前端构建需设置 `REACT_APP_API_URL` 为后端根地址。
|
||||
- **CORS**：后端中间件 `internal/middleware/cors.go` 为**宽松策略**（放行任意 Origin 并回显），便于跨域；若需收紧可改为白名单。
|
||||
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. 代码质量与一致性
|
||||
|
||||
| 路径 | 说明 |
|
||||
|------|------|
|
||||
| `/` | 首页 |
|
||||
| `/login` | 跳转统一登录 |
|
||||
| `/auth/callback` | OAuth 回调 |
|
||||
| `/60sapi` | 60s API 分类列表 |
|
||||
| `/60sapi/:itemId` | 嵌入对应静态 HTML |
|
||||
| `/toolbox` | 工具箱列表 |
|
||||
| `/smallgame` | 小游戏 |
|
||||
| `/aimodel` | AI 应用 |
|
||||
| `/profile` | 个人中心（只读） |
|
||||
| `/admin` | 管理员后台（令牌） |
|
||||
| `*` | 未匹配 → 首页 |
|
||||
当前项目在开发过程中出现了一些不一致的编码风格和实践，需要通过以下措施进行标准化：
|
||||
|
||||
---
|
||||
- **代码规范统一**: 引入 ESLint + Prettier 强制执行统一的代码风格
|
||||
- **类型安全增强**: 考虑引入 TypeScript 或 PropTypes 进行类型检查，降低运行时错误
|
||||
- **代码审查流程**: 建立明确的代码审查规范和流程，确保代码质量
|
||||
- **文档完善**: 补充关键功能模块和核心组件的详细文档
|
||||
|
||||
## 联系方式与许可
|
||||
### 2. 架构优化与重构
|
||||
|
||||
- **演示**：https://infogenie.shumengya.top
|
||||
- **ICP**：蜀ICP备2025151694号（以实际页脚为准）
|
||||
- **许可证**：Apache License 2.0 — 见 [LICENSE](LICENSE)
|
||||
以下是需要关注的架构层面优化点：
|
||||
|
||||
---
|
||||
- **API 层抽象**: 当前的 API 调用过于分散，建议引入统一的 API 请求层和数据模型层
|
||||
- **组件结构优化**: 部分组件承担过多职责，应按照单一职责原则进行拆分
|
||||
- **状态管理重构**: 当前 Context API 的使用在大型应用中可能导致过度渲染，考虑引入更高效的状态管理方案
|
||||
- **静态资源优化**: 优化图像、字体等静态资源的加载策略，减少页面加载时间
|
||||
|
||||
<div align="center"><strong>万象口袋</strong> · 多功能聚合应用</div>
|
||||
### 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. **性能指标达成**: 优化应用性能，使所有关键指标达到业界标准
|
||||
Reference in New Issue
Block a user