170 lines
5.1 KiB
Markdown
170 lines
5.1 KiB
Markdown
# GEO 平台 - 前端应用
|
||
|
||
基于 Next.js 14 + React 18 构建的现代化前端应用，使用 App Router 架构。
|
||
|
||
## 环境要求
|
||
|
||
- Node.js 18+
|
||
- npm 9+（或 yarn、pnpm）
|
||
- 后端服务已启动（默认 http://localhost:8000）
|
||
|
||
## 安装步骤
|
||
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
```
|
||
|
||
## 运行命令
|
||
|
||
```bash
|
||
# 开发模式（带热重载）
|
||
npm run dev
|
||
|
||
# 生产构建
|
||
npm run build
|
||
|
||
# 启动生产服务
|
||
npm run start
|
||
|
||
# 代码检查
|
||
npm run lint
|
||
```
|
||
|
||
开发服务器启动后，访问 http://localhost:3000。
|
||
|
||
## 页面路由说明
|
||
|
||
本应用使用 Next.js App Router（`app/` 目录），路由基于文件系统自动生成。
|
||
|
||
### 认证页面（`(auth)` 路由组）
|
||
|
||
| 路径 | 功能 | 说明 |
|
||
|------|------|------|
|
||
| `/` | 首页/欢迎页 | 应用入口，未登录用户展示介绍 |
|
||
| `/login` | 用户登录 | 邮箱+密码登录，支持记住我 |
|
||
| `/register` | 用户注册 | 新用户注册，含邮箱验证流程 |
|
||
| `/forgot-password` | 忘记密码 | 发送密码重置链接到邮箱 |
|
||
| `/reset-password` | 重置密码 | 通过令牌设置新密码 |
|
||
|
||
### 仪表盘页面（`(dashboard)` 路由组）
|
||
|
||
所有仪表盘页面均需登录后才能访问，受 NextAuth 会话保护。
|
||
|
||
| 路径 | 功能 | 说明 |
|
||
|------|------|------|
|
||
| `/dashboard` | 仪表盘首页 | 数据概览、关键指标、引用趋势图 |
|
||
| `/dashboard/queries` | 查询词管理 | 查询词 CRUD、即时执行、分页列表 |
|
||
| `/dashboard/citations` | 引用数据 | 引用记录列表、按平台/日期筛选 |
|
||
| `/dashboard/reports` | 报告导出 | CSV 报告生成与下载 |
|
||
| `/dashboard/settings` | 个人设置 | 用户资料修改、密码修改 |
|
||
|
||
### API 路由
|
||
|
||
| 路径 | 功能 |
|
||
|------|------|
|
||
| `/api/auth/[...nextauth]` | NextAuth.js 认证 API 端点 |
|
||
|
||
## 组件结构说明
|
||
|
||
```
|
||
components/
|
||
├── ui/ # shadcn/ui 基础组件
|
||
│ ├── button.tsx # 按钮
|
||
│ ├── card.tsx # 卡片
|
||
│ ├── dialog.tsx # 对话框
|
||
│ ├── dropdown-menu.tsx # 下拉菜单
|
||
│ ├── input.tsx # 输入框
|
||
│ ├── label.tsx # 标签
|
||
│ ├── select.tsx # 下拉选择
|
||
│ ├── table.tsx # 表格
|
||
│ ├── tabs.tsx # 标签页
|
||
│ ├── badge.tsx # 徽标
|
||
│ └── skeleton.tsx # 骨架屏
|
||
├── charts/ # 数据可视化图表组件
|
||
│ ├── trend-chart.tsx # 引用趋势折线图
|
||
│ └── platform-chart.tsx # 平台对比柱状图/饼图
|
||
├── layout/ # 布局组件
|
||
│ ├── header.tsx # 顶部导航栏
|
||
│ └── sidebar.tsx # 侧边栏导航
|
||
└── providers.tsx # 全局 Provider 包装（NextAuth SessionProvider 等）
|
||
```
|
||
|
||
### lib 工具库
|
||
|
||
```
|
||
lib/
|
||
├── api.ts # 后端 API 客户端封装（fetch 封装）
|
||
├── auth.ts # NextAuth 配置与工具函数
|
||
├── platforms.ts # 平台名称/图标映射配置
|
||
└── utils.ts # 通用工具函数（cn 合并类等）
|
||
```
|
||
|
||
## 技术栈详情
|
||
|
||
| 类别 | 技术 |
|
||
|------|------|
|
||
| 框架 | Next.js 14 (App Router) |
|
||
| UI 库 | React 18 |
|
||
| 样式 | TailwindCSS 3.4 |
|
||
| 组件库 | shadcn/ui（基于 Radix UI） |
|
||
| 图表 | Recharts |
|
||
| 认证 | NextAuth.js 4 (Credentials Provider) |
|
||
| 字体 | Geist（本地字体） |
|
||
| 语言 | TypeScript 5 |
|
||
|
||
## 环境变量配置
|
||
|
||
前端环境变量分为两类：
|
||
|
||
### 公开环境变量（`NEXT_PUBLIC_` 前缀，客户端可用）
|
||
|
||
在 `.env.local` 中配置：
|
||
|
||
```bash
|
||
# 后端 API 地址
|
||
NEXT_PUBLIC_API_URL=http://localhost:8000
|
||
```
|
||
|
||
### 服务端环境变量（仅服务端可用）
|
||
|
||
```bash
|
||
# NextAuth 配置
|
||
NEXTAUTH_URL=http://localhost:3000
|
||
NEXTAUTH_SECRET=geo-platform-nextauth-secret-key-2026
|
||
```
|
||
|
||
> **注意**：`.env.local` 文件不会被提交到 Git 仓库。新成员需要手动创建该文件。
|
||
|
||
### 环境变量文件优先级
|
||
|
||
Next.js 按以下优先级加载环境变量（高优先级覆盖低优先级）：
|
||
|
||
1. `.env.local`（本地开发，不提交 Git）
|
||
2. `.env.development` / `.env.production`（按环境）
|
||
3. `.env`（全局默认）
|
||
|
||
## Docker 开发
|
||
|
||
项目根目录已提供 `docker-compose.yml`，前端服务会自动挂载代码并启动开发服务器：
|
||
|
||
```bash
|
||
# 在项目根目录执行
|
||
docker-compose up -d frontend
|
||
```
|
||
|
||
前端容器配置：
|
||
- 端口映射：`3000:3000`
|
||
- 代码热重载：通过 volume 挂载 `./frontend:/app`
|
||
- node_modules 持久化：独立 volume 避免覆盖
|
||
|
||
## 开发注意事项
|
||
|
||
1. **API 调用**：统一使用 `lib/api.ts` 中封装的方法，自动携带 JWT Token
|
||
2. **认证状态**：通过 `next-auth/react` 的 `useSession` Hook 获取当前登录状态
|
||
3. **服务端组件 vs 客户端组件**：
|
||
- 数据获取页面优先使用 Server Component
|
||
- 交互逻辑（表单、图表）使用 `"use client"` Client Component
|
||
4. **样式规范**：统一使用 TailwindCSS 工具类，复杂组合通过 `cn()` 工具函数处理
|
||
5. **图标**：统一使用 `lucide-react` 图标库
|