# 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` 图标库