InfoGenie/InfoGenie-frontend/前端文档.md

万象口袋 — 前端文档

技术栈：React 18 · React Router 6 · Tailwind CSS v4 · axios · Vite 6

包名：infogenie-frontend（见 package.json）

---

命令

命令	说明
npm run dev / npm start	开发服务器（Vite，默认端口 3000）
npm run build	生产构建，输出 dist/
npm run preview	本地预览 dist/ 构建结果

---

项目结构（关键文件）

infogenie-frontend/
├── index.html            ← Vite HTML 入口（根目录，非 public/）
├── vite.config.js        ← Vite 配置（React 插件、Tailwind 插件、路径别名）
├── package.json
├── .env.development      ← 开发环境变量（VITE_*）
├── .env.production       ← 生产环境变量
├── public/               ← 静态资源（不参与构建，直接复制到 dist/）
│   ├── assets/logo.png
│   ├── icons/
│   ├── aimodelapp/       ← AI 小应用静态页
│   ├── smallgame/        ← 小游戏静态页
│   └── toolbox/          ← 工具箱静态页
└── src/
    ├── index.js          ← React 根挂载
    ├── App.js            ← 路由、布局、全局 Provider
    ├── components/       ← 公共组件（含 FullscreenEmbed、SmallGameIcons 等）
    ├── pages/            ← 页面组件（含 AdminPage、SmallGamePage）
    ├── contexts/         ← 全局 Context
    ├── hooks/            ← 自定义 Hooks（如 useFeatureCardClickStats）
    ├── utils/            ← Axios 封装、可见性过滤等
    ├── config/           ← 环境变量解析、Api60sConfig、StaticPageConfig
    └── styles/
        ├── index.css     ← Tailwind 入口 + 全局 base 样式 + 自定义动画
        └── shared.js     ← 设计系统组件（Tailwind 函数组件）

---

Vite 配置（vite.config.js）

特性	说明
@vitejs/plugin-react	React Fast Refresh + JSX 转换（含 .js 扩展名支持）
@tailwindcss/vite	Tailwind CSS v4 Vite 插件
treat-js-as-jsx	内联插件，使 .js 文件中的 JSX 正常编译
resolve.alias['@']	@/ 映射到 src/
base: '/'	部署根路径
server.port: 3000	开发服务器端口

---

环境变量（src/config/env.js）

变量名使用 Vite 规范的 VITE_ 前缀（通过 import.meta.env 访问）：

变量	作用	开发默认 / 生产默认
VITE_API_URL	万象口袋 Go 后端 根地址	dev：http://127.0.0.1:5002；prod 见 .env.production
VITE_AUTH_URL	认证中心 页面 域名	https://auth.shumengya.top
VITE_AUTH_API_URL	认证中心 API 根地址	https://auth.api.shumengya.top
VITE_DEBUG	调试开关	'true' 开启
VITE_SITE_ADMIN_GATE	管理员后台口令，须与后端 INFOGENIE_SITE_ADMIN_TOKEN 一致	本地写在 .env.development，勿提交

运行时可通过 window.ENV_CONFIG 查看解析结果（若已注入）。

迁移注意：由 CRA 迁出后，原 REACT_APP_* 已统一为 VITE_*。

---

主应用结构（src/）

路由（src/App.js）

路径	页面
/	首页
/login	登录
/auth/callback	认证回调
/60sapi · /60sapi/:itemId	60s API 列表与详情
/smallgame	休闲游戏
/toolbox	工具箱
/aimodel	AI 应用（需登录）
/profile	个人中心
/admin	管理员后台（本地 admin_token 校验）
*	重定向首页

管理员后台（src/pages/AdminPage.js）

• 浏览器 localStorage.admin_token 与内置口令一致方可进入（与后端 INFOGENIE_SITE_ADMIN_TOKEN 用于接口时是同一套站点管理员概念）。
• 功能分区（左侧）：概览、状态监控、AI 上游、60s 数据源、60s 前台展示、AI 前台展示。
• 状态监控：
  • 并行请求 GET /api/health（MySQL / 60s 上游 / Redis Ping）与 GET /api/admin/site/diagnostics（进程监听、MySQL/Redis 连接目标、库名/用户、SMTP、认证中心 URL 等；不含密码）。
  • 请求诊断接口时携带头 X-Site-Admin-Token: <admin_token>。
  • 「刷新探测与配置」会同时刷新上述两个数据源。

休闲游戏页（src/pages/SmallGamePage.js）

• 游戏列表来自 src/config/StaticPageConfig.js 的 SMALL_GAMES。
• 卡片图标由 src/components/SmallGameIcons.js 按 game.id 渲染 Emoji（如 2048→🔢、俄罗斯方块→🧱 等），嵌入在 FeatureCardIcon 内。

其他关键组件

• RandomSiteBackground：全站随机背景，毛玻璃模糊，会话级缓存。
• Header / Footer / Navigation：导航与布局。
• FullscreenEmbed：全屏 iframe（游戏、工具箱、AI 静态页），支持注入 token、加载超时提示。
• ParticleEffect：全局点击粒子动画。

---

样式系统（src/styles/）

Tailwind CSS v4

• 入口：src/styles/index.css，顶部 @import "tailwindcss"
• 配置：Tailwind v4 CSS-first，无独立 tailwind.config.js，自定义动画通过 @theme 块定义

自定义动画（可直接在 className 中使用）：

类名	效果	用途
animate-page-enter	opacity: 0→1, translateY: 20px→0, 0.8s	页面进入
animate-fade-up	opacity: 0→1, translateY: 12px→0, 0.35s	卡片网格出现

设计系统（src/styles/shared.js）

所有组件均为 React 函数组件，接受 className prop（可与 Tailwind 类合并）：

• PageWrapper、Container、FeatureGrid、CatalogCard、FeatureCard
• FeatureCardUseCount：卡片右上角点击次数角标
• ModuleCard：首页大模块卡片（Link）
• accentFromGradient：从 gradient 字符串提取首色

---

HTTP（src/utils/api.js）

• axios 实例默认 baseURL = ENV_CONFIG.API_URL，请求头自动带 Bearer token
• import.meta.env.DEV 控制仅开发环境打印 URL
• 支持 skipErrorToast: true，用于静默失败场景（如点击统计）

---

静态资源（public/）

与 Vite 主站并列的大量免构建页面：

• public/aimodelapp/<应用名>/：AI 小应用（HTML + script.js + 可选 env.js）。
  • 统一聊天入口：public/aimodelapp/shared/ai-chat.js。
  • 优先请求 POST /api/aimodelapp/chat/stream（SSE），失败或无内容时回退 POST /api/aimodelapp/chat。
• public/smallgame/、public/toolbox/：独立页，由 FullscreenEmbed 打开。

各 aimodelapp 子目录的 env.js / API_CONFIG 需指向与主站一致的 Go 后端地址（通常与 VITE_API_URL 同源或同网段）。

---

与后端协作要点

1. 登录：token 存 localStorage，AI 与受保护接口依赖 JWT（萌芽认证中心签发）。
2. AI：静态页通过配置的 API 调 Go 的 /api/aimodelapp/*；流式为 text/event-stream。
3. 站点开关：60s / AI 应用显隐由 GET /api/site/*-disabled 等驱动。
4. 卡片统计：列表页 CatalogCard 与 feature-card-clicks 接口对接；可选 Redis 缓存由后端控制。
5. 管理员：写配置类接口需后端配置 INFOGENIE_SITE_ADMIN_TOKEN，与前端管理员口令一致。

---

其他文档

• Go 后端 API、Redis、健康与诊断：infogenie-backend-go/后端文档.md
• 仓库总览与多模块说明：../README.md