geo/frontend

GEO 平台 - 前端应用

基于 Next.js 14 + React 18 构建的现代化前端应用，使用 App Router 架构。

环境要求

• Node.js 18+
• npm 9+（或 yarn、pnpm）
• 后端服务已启动（默认 http://localhost:8000）

安装步骤

cd frontend
npm install

运行命令

# 开发模式（带热重载）
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 中配置：

# 后端 API 地址
NEXT_PUBLIC_API_URL=http://localhost:8000

服务端环境变量（仅服务端可用）

# 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，前端服务会自动挂载代码并启动开发服务器：

# 在项目根目录执行
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 图标库