fischer
/
geo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
geo/.qoder/repowiki/zh/content/前端系统架构/前端系统架构.md

743 lines
38 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 前端系统架构
<cite>
**本文档引用的文件**
- [package.json](file://frontend/package.json)
- [next.config.mjs](file://frontend/next.config.mjs)
- [tailwind.config.ts](file://frontend/tailwind.config.ts)
- [app/layout.tsx](file://frontend/app/layout.tsx)
- [components/providers.tsx](file://frontend/components/providers.tsx)
- [app/(auth)/layout.tsx](file://frontend/app/(auth)/layout.tsx)
- [app/(dashboard)/layout.tsx](file://frontend/app/(dashboard)/layout.tsx)
- [lib/auth.ts](file://frontend/lib/auth.ts)
- [types/next-auth.d.ts](file://frontend/types/next-auth.d.ts)
- [lib/api.ts](file://frontend/lib/api.ts)
- [app/(auth)/login/page.tsx](file://frontend/app/(auth)/login/page.tsx)
- [app/(auth)/forgot-password/page.tsx](file://frontend/app/(auth)/forgot-password/page.tsx)
- [app/(auth)/reset-password/page.tsx](file://frontend/app/(auth)/reset-password/page.tsx)
- [app/(auth)/verify-email/page.tsx](file://frontend/app/(auth)/verify-email/page.tsx)
- [app/(auth)/register/page.tsx](file://frontend/app/(auth)/register/page.tsx)
- [app/(dashboard)/dashboard/page.tsx](file://frontend/app/(dashboard)/dashboard/page.tsx)
- [app/(dashboard)/dashboard/admin/page.tsx](file://frontend/app/(dashboard)/dashboard/admin/page.tsx)
- [app/(dashboard)/dashboard/settings/page.tsx](file://frontend/app/(dashboard)/dashboard/settings/page.tsx)
- [components/ui/button.tsx](file://frontend/components/ui/button.tsx)
- [components/layout/header.tsx](file://frontend/components/layout/header.tsx)
- [components/layout/sidebar.tsx](file://frontend/components/layout/sidebar.tsx)
- [components/ui/tabs.tsx](file://frontend/components/ui/tabs.tsx)
- [app/api/auth/[...nextauth]/route.ts](file://frontend/app/api/auth/[...nextauth]/route.ts)
- [playwright.config.ts](file://frontend/playwright.config.ts)
- [e2e/tests/dashboard-health.spec.ts](file://frontend/e2e/tests/dashboard-health.spec.ts)
- [e2e/tests/login.spec.ts](file://frontend/e2e/tests/login.spec.ts)
- [e2e/pages/dashboard.page.ts](file://frontend/e2e/pages/dashboard.page.ts)
- [e2e/pages/login.page.ts](file://frontend/e2e/pages/login.page.ts)
- [components/business/index.ts](file://frontend/components/business/index.ts)
- [components/business/agent-status-card.tsx](file://frontend/components/business/agent-status-card.tsx)
- [components/business/alert-card.tsx](file://frontend/components/business/alert-card.tsx)
- [components/dashboard/index.ts](file://frontend/components/dashboard/index.ts)
</cite>
## 更新摘要
**所做变更**
- 新增E2E测试框架：引入Playwright测试套件，包含登录页面测试、健康状态Dashboard测试、响应式设计测试
- 新增业务组件库：扩展GEO特定业务组件，包括Agent状态卡片、告警卡片、指标卡片等
- 新增仪表板布局重构：改进侧边导航结构，支持固定侧边栏和头部导航
- 新增测试脚本：添加E2E测试命令，支持多浏览器测试和并行执行
- 新增业务组件索引：提供统一的业务组件导出接口
## 目录
1. [引言](#引言)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [E2E测试框架](#e2e测试框架)
7. [业务组件库](#业务组件库)
8. [依赖分析](#依赖分析)
9. [性能考虑](#性能考虑)
10. [故障排除指南](#故障排除指南)
11. [结论](#结论)
12. [附录](#附录)
## 引言
本文件为 GEO 前端系统的架构文档，聚焦于基于 Next.js 14 的应用架构设计，涵盖 App Router 页面组织、服务器组件与客户端组件的混合使用模式；认证系统（NextAuth.js 集成、会话管理与路由保护）；UI 组件库设计理念与复用策略；数据获取与状态管理；错误处理机制；以及响应式设计、可访问性与性能优化等最佳实践。
**更新** 新增E2E测试框架集成、业务组件库扩展、仪表板布局重构等前端架构变化。
## 项目结构
前端采用 Next.js 14 App Router 结构，页面按功能域分组（通过路由组 `(auth)` 和 `(dashboard)` 实现），根布局统一注入全局样式与 Provider，认证相关 API 路由集中于 `/api/auth/[...nextauth]`。系统现已扩展为完整的认证体系，包含登录、注册、忘记密码、重置密码、邮箱验证等页面，以及管理员仪表板和设置页面。
```mermaid
graph TB
A["app/layout.tsx<br/>根布局与全局样式"] --> B["components/providers.tsx<br/>SessionProvider"]
A --> C["app/(auth)/layout.tsx<br/>认证页容器"]
A --> D["app/(dashboard)/layout.tsx<br/>仪表盘容器"]
C --> F["app/(auth)/login/page.tsx<br/>登录页"]
C --> G["app/(auth)/register/page.tsx<br/>注册页"]
C --> H["app/(auth)/forgot-password/page.tsx<br/>忘记密码页"]
C --> I["app/(auth)/reset-password/page.tsx<br/>重置密码页"]
C --> J["app/(auth)/verify-email/page.tsx<br/>邮箱验证页"]
D --> K["app/(dashboard)/dashboard/page.tsx<br/>仪表盘页"]
D --> L["app/(dashboard)/dashboard/admin/page.tsx<br/>管理员仪表板"]
D --> M["app/(dashboard)/dashboard/settings/page.tsx<br/>设置页"]
B --> N["app/api/auth/[...nextauth]/route.ts<br/>NextAuth 路由处理器"]
A --> O["tailwind.config.ts<br/>Tailwind 配置"]
A --> P["next.config.mjs<br/>Next 配置"]
Q["components/layout/sidebar.tsx<br/>侧边栏导航"] --> D
R["components/ui/tabs.tsx<br/>标签页组件"] --> M
S["e2e/ 目录<br/>E2E测试框架"] --> T["playwright.config.ts<br/>测试配置"]
S --> U["e2e/tests/ 目录<br/>测试用例"]
S --> V["e2e/pages/ 目录<br/>页面对象"]
W["components/business/ 目录<br/>业务组件库"] --> X["agent-status-card.tsx<br/>代理状态卡片"]
W --> Y["alert-card.tsx<br/>告警卡片"]
W --> Z["metric-card.tsx<br/>指标卡片"]
```
**图表来源**
- [app/layout.tsx:1-37](file://frontend/app/layout.tsx#L1-L37)
- [components/providers.tsx:1-9](file://frontend/components/providers.tsx#L1-L9)
- [app/(auth)/layout.tsx](file://frontend/app/(auth)/layout.tsx#L1-L12)
- [app/(dashboard)/layout.tsx:1-146](file://frontend/app/(dashboard)/layout.tsx#L1-L146)
- [app/(auth)/login/page.tsx](file://frontend/app/(auth)/login/page.tsx#L1-L93)
- [app/(auth)/register/page.tsx](file://frontend/app/(auth)/register/page.tsx#L1-L128)
- [app/(auth)/forgot-password/page.tsx](file://frontend/app/(auth)/forgot-password/page.tsx#L1-L101)
- [app/(auth)/reset-password/page.tsx](file://frontend/app/(auth)/reset-password/page.tsx#L1-L148)
- [app/(auth)/verify-email/page.tsx](file://frontend/app/(auth)/verify-email/page.tsx#L1-L155)
- [app/(dashboard)/dashboard/page.tsx](file://frontend/app/(dashboard)/dashboard/page.tsx#L1-L227)
- [app/(dashboard)/dashboard/admin/page.tsx](file://frontend/app/(dashboard)/dashboard/admin/page.tsx#L1-L435)
- [app/(dashboard)/dashboard/settings/page.tsx](file://frontend/app/(dashboard)/dashboard/settings/page.tsx#L1-L445)
- [components/layout/sidebar.tsx:1-63](file://frontend/components/layout/sidebar.tsx#L1-L63)
- [components/ui/tabs.tsx:1-56](file://frontend/components/ui/tabs.tsx#L1-L56)
- [app/api/auth/[...nextauth]/route.ts](file://frontend/app/api/auth/[...nextauth]/route.ts#L1-L7)
- [tailwind.config.ts:1-121](file://frontend/tailwind.config.ts#L1-L121)
- [next.config.mjs:1-5](file://frontend/next.config.mjs#L1-L5)
- [playwright.config.ts:1-39](file://frontend/playwright.config.ts#L1-L39)
- [components/business/index.ts:1-29](file://frontend/components/business/index.ts#L1-L29)
**章节来源**
- [app/layout.tsx:1-37](file://frontend/app/layout.tsx#L1-L37)
- [components/providers.tsx:1-9](file://frontend/components/providers.tsx#L1-L9)
- [app/(auth)/layout.tsx](file://frontend/app/(auth)/layout.tsx#L1-L12)
- [app/(dashboard)/layout.tsx:1-146](file://frontend/app/(dashboard)/layout.tsx#L1-L146)
- [tailwind.config.ts:1-121](file://frontend/tailwind.config.ts#L1-L121)
- [next.config.mjs:1-5](file://frontend/next.config.mjs#L1-L5)
## 核心组件
- 根布局与全局样式：定义站点元数据、字体变量与全局样式入口，并包裹应用上下文 Provider。
- 会话提供者：在客户端注入 SessionProvider，使整个应用可访问 NextAuth 会话状态。
- 认证路由组：提供登录/注册/忘记密码/重置密码/邮箱验证等认证页面的统一容器样式。
- 仪表盘路由组：提供侧边栏与头部导航，支持固定布局和活动状态跟踪，未登录则重定向至登录页。
- 认证配置：NextAuth 选项，使用凭据提供者对接后端认证接口，JWT 会话策略，回调处理 token 与 session 映射，支持管理员权限。
- 类型扩展：为 NextAuth 的 Session 与 JWT 扩展自定义字段，确保类型安全，包含管理员标识。
- API 客户端：封装带鉴权头的通用请求方法，统一错误处理与响应解析，支持完整认证端点。
- UI 组件库：基于 Radix UI 与 Tailwind，使用 class-variance-authority 提供变体与尺寸控制，新增 Tabs 组件支持标签页布局。
- 头部组件：展示当前用户信息与登出按钮，触发 NextAuth 的 signOut 流程。
- 侧边栏组件：根据用户权限动态显示导航项，支持管理员专用的管理后台入口。
**章节来源**
- [app/layout.tsx:1-37](file://frontend/app/layout.tsx#L1-L37)
- [components/providers.tsx:1-9](file://frontend/components/providers.tsx#L1-L9)
- [app/(auth)/layout.tsx](file://frontend/app/(auth)/layout.tsx#L1-L12)
- [app/(dashboard)/layout.tsx:1-146](file://frontend/app/(dashboard)/layout.tsx#L1-L146)
- [lib/auth.ts:1-73](file://frontend/lib/auth.ts#L1-L73)
- [types/next-auth.d.ts:1-29](file://frontend/types/next-auth.d.ts#L1-L29)
- [lib/api.ts:1-154](file://frontend/lib/api.ts#L1-L154)
- [components/ui/button.tsx:1-57](file://frontend/components/ui/button.tsx#L1-L57)
- [components/layout/header.tsx:1-30](file://frontend/components/layout/header.tsx#L1-L30)
- [components/layout/sidebar.tsx:1-63](file://frontend/components/layout/sidebar.tsx#L1-L63)
- [components/ui/tabs.tsx:1-56](file://frontend/components/ui/tabs.tsx#L1-L56)
## 架构总览
下图展示了从浏览器到认证服务与业务 API 的整体调用链路，以及客户端组件与服务器组件的职责边界。系统现已支持完整的认证流程和管理功能。
```mermaid
graph TB
subgraph "浏览器"
U["用户界面<br/>客户端组件"]
end
subgraph "Next.js 应用"
RL["根布局<br/>app/layout.tsx"]
PR["会话提供者<br/>components/providers.tsx"]
AL["认证布局<br/>app/(auth)/layout.tsx"]
DL["仪表盘布局<br/>app/(dashboard)/layout.tsx"]
LOGIN["登录页<br/>app/(auth)/login/page.tsx"]
REGISTER["注册页<br/>app/(auth)/register/page.tsx"]
FP["忘记密码页<br/>app/(auth)/forgot-password/page.tsx"]
RP["重置密码页<br/>app/(auth)/reset-password/page.tsx"]
VE["邮箱验证页<br/>app/(auth)/verify-email/page.tsx"]
DB["仪表盘页<br/>app/(dashboard)/dashboard/page.tsx"]
ADMIN["管理员仪表板<br/>app/(dashboard)/dashboard/admin/page.tsx"]
SETTINGS["设置页<br/>app/(dashboard)/dashboard/settings/page.tsx"]
AH["NextAuth 路由<br/>app/api/auth/[...nextauth]/route.ts"]
UI["UI 组件库<br/>components/ui/*"]
LH["头部组件<br/>components/layout/header.tsx"]
LS["侧边栏组件<br/>components/layout/sidebar.tsx"]
BC["业务组件库<br/>components/business/*"]
DP["Dashboard组件<br/>components/dashboard/*"]
end
subgraph "认证服务"
NA["NextAuth 服务<br/>lib/auth.ts"]
end
subgraph "后端 API"
API["业务 API 客户端<br/>lib/api.ts"]
BE["后端服务<br/>backend/app/*"]
end
subgraph "E2E测试框架"
PW["Playwright<br/>playwright.config.ts"]
DS["Dashboard测试<br/>e2e/tests/dashboard-health.spec.ts"]
LSpec["登录测试<br/>e2e/tests/login.spec.ts"]
DPg["Dashboard页面<br/>e2e/pages/dashboard.page.ts"]
LPg["Login页面<br/>e2e/pages/login.page.ts"]
end
U --> RL
RL --> PR
PR --> AL
PR --> DL
AL --> LOGIN
AL --> REGISTER
AL --> FP
AL --> RP
AL --> VE
DL --> LH
DL --> LS
DL --> DB
DL --> ADMIN
DL --> SETTINGS
LOGIN --> AH
REGISTER --> AH
AH --> NA
DB --> API
ADMIN --> API
SETTINGS --> API
NA --> BE
API --> BE
PW --> DS
PW --> LSpec
DS --> DPg
LSpec --> LPg
```
**图表来源**
- [app/layout.tsx:1-37](file://frontend/app/layout.tsx#L1-L37)
- [components/providers.tsx:1-9](file://frontend/components/providers.tsx#L1-L9)
- [app/(auth)/layout.tsx](file://frontend/app/(auth)/layout.tsx#L1-L12)
- [app/(dashboard)/layout.tsx:1-146](file://frontend/app/(dashboard)/layout.tsx#L1-L146)
- [app/(auth)/login/page.tsx](file://frontend/app/(auth)/login/page.tsx#L1-L93)
- [app/(auth)/register/page.tsx](file://frontend/app/(auth)/register/page.tsx#L1-L128)
- [app/(auth)/forgot-password/page.tsx](file://frontend/app/(auth)/forgot-password/page.tsx#L1-L101)
- [app/(auth)/reset-password/page.tsx](file://frontend/app/(auth)/reset-password/page.tsx#L1-L148)
- [app/(auth)/verify-email/page.tsx](file://frontend/app/(auth)/verify-email/page.tsx#L1-L155)
- [app/(dashboard)/dashboard/page.tsx](file://frontend/app/(dashboard)/dashboard/page.tsx#L1-L227)
- [app/(dashboard)/dashboard/admin/page.tsx](file://frontend/app/(dashboard)/dashboard/admin/page.tsx#L1-L435)
- [app/(dashboard)/dashboard/settings/page.tsx](file://frontend/app/(dashboard)/dashboard/settings/page.tsx#L1-L445)
- [components/layout/header.tsx:1-30](file://frontend/components/layout/header.tsx#L1-L30)
- [components/layout/sidebar.tsx:1-63](file://frontend/components/layout/sidebar.tsx#L1-L63)
- [app/api/auth/[...nextauth]/route.ts](file://frontend/app/api/auth/[...nextauth]/route.ts#L1-L7)
- [lib/auth.ts:1-73](file://frontend/lib/auth.ts#L1-L73)
- [lib/api.ts:1-154](file://frontend/lib/api.ts#L1-L154)
- [playwright.config.ts:1-39](file://frontend/playwright.config.ts#L1-L39)
- [e2e/tests/dashboard-health.spec.ts:1-264](file://frontend/e2e/tests/dashboard-health.spec.ts#L1-L264)
- [e2e/tests/login.spec.ts:1-126](file://frontend/e2e/tests/login.spec.ts#L1-L126)
## 详细组件分析
### 认证系统（NextAuth.js 集成）
- 凭据提供者：使用邮箱/密码进行认证，调用后端登录接口，成功后返回包含用户信息与访问令牌的对象，支持管理员权限标识。
- JWT 会话策略：在回调中将访问令牌与用户 ID 写入 JWT，并在 session 回调中回填到 session 对象，包含 is_admin 字段。
- 完整认证流程：支持注册、登录、忘记密码、重置密码、邮箱验证、密码修改、个人资料更新等完整认证生命周期。
- 路由保护：仪表盘布局在客户端通过 useSession 获取会话状态，若无会话则重定向至登录页。
- NextAuth 路由：统一暴露 GET/POST，交由 NextAuth 处理认证生命周期。
```mermaid
sequenceDiagram
participant C as "客户端浏览器"
participant REG as "注册页<br/>app/(auth)/register/page.tsx"
participant LOGIN as "登录页<br/>app/(auth)/login/page.tsx"
participant FP as "忘记密码页<br/>app/(auth)/forgot-password/page.tsx"
participant RP as "重置密码页<br/>app/(auth)/reset-password/page.tsx"
participant VE as "邮箱验证页<br/>app/(auth)/verify-email/page.tsx"
participant AH as "NextAuth 路由<br/>app/api/auth/[...nextauth]/route.ts"
participant NA as "NextAuth 配置<br/>lib/auth.ts"
participant BE as "后端服务<br/>backend/app/api/auth.py"
C->>REG : "提交注册信息"
REG->>BE : "调用注册接口"
BE-->>REG : "返回用户信息"
REG->>LOGIN : "自动登录并跳转到邮箱验证"
C->>FP : "提交邮箱地址"
FP->>BE : "发送重置链接"
C->>RP : "提交新密码"
RP->>BE : "重置密码"
C->>VE : "提交验证码"
VE->>BE : "验证邮箱"
LOGIN->>AH : "signIn('credentials')"
AH->>NA : "调用 NextAuth 处理"
NA->>BE : "调用后端登录接口"
BE-->>NA : "返回访问令牌与用户信息"
NA-->>AH : "生成 JWT 与 session"
AH-->>LOGIN : "认证结果"
LOGIN-->>C : "跳转到 /dashboard 或显示错误"
```
**图表来源**
- [app/(auth)/register/page.tsx](file://frontend/app/(auth)/register/page.tsx#L1-L128)
- [app/(auth)/login/page.tsx](file://frontend/app/(auth)/login/page.tsx#L1-L93)
- [app/(auth)/forgot-password/page.tsx](file://frontend/app/(auth)/forgot-password/page.tsx#L1-L101)
- [app/(auth)/reset-password/page.tsx](file://frontend/app/(auth)/reset-password/page.tsx#L1-L148)
- [app/(auth)/verify-email/page.tsx](file://frontend/app/(auth)/verify-email/page.tsx#L1-L155)
- [app/api/auth/[...nextauth]/route.ts](file://frontend/app/api/auth/[...nextauth]/route.ts#L1-L7)
- [lib/auth.ts:1-73](file://frontend/lib/auth.ts#L1-L73)
- [backend/app/api/auth.py](file://backend/app/api/auth.py)
**章节来源**
- [lib/auth.ts:1-73](file://frontend/lib/auth.ts#L1-L73)
- [types/next-auth.d.ts:1-29](file://frontend/types/next-auth.d.ts#L1-L29)
- [app/api/auth/[...nextauth]/route.ts](file://frontend/app/api/auth/[...nextauth]/route.ts#L1-L7)
- [app/(auth)/login/page.tsx](file://frontend/app/(auth)/login/page.tsx#L1-L93)
- [app/(auth)/register/page.tsx](file://frontend/app/(auth)/register/page.tsx#L1-L128)
- [app/(auth)/forgot-password/page.tsx](file://frontend/app/(auth)/forgot-password/page.tsx#L1-L101)
- [app/(auth)/reset-password/page.tsx](file://frontend/app/(auth)/reset-password/page.tsx#L1-L148)
- [app/(auth)/verify-email/page.tsx](file://frontend/app/(auth)/verify-email/page.tsx#L1-L155)
- [app/(dashboard)/layout.tsx:1-146](file://frontend/app/(dashboard)/layout.tsx#L1-L146)
### 管理员仪表板系统
- 用户管理：支持用户列表查看、搜索、分页，提供启用/禁用用户和修改套餐功能。
- 系统统计：展示总用户数、总查询数、总引用次数、引用率等关键指标。
- 权限控制：仅管理员可见管理后台入口，侧边栏根据用户 is_admin 字段动态显示。
- 数据管理：提供弹窗确认机制，确保敏感操作的安全性。
```mermaid
flowchart TD
Start(["进入管理员仪表板"]) --> CheckAdmin{"检查管理员权限"}
CheckAdmin --> |否| Redirect["重定向到普通仪表板"]
CheckAdmin --> |是| LoadStats["加载系统统计"]
LoadStats --> LoadUsers["加载用户列表"]
LoadUsers --> RenderUI["渲染管理界面"]
RenderUI --> Actions{"用户操作"}
Actions --> Toggle["启用/禁用用户"]
Actions --> Plan["修改用户套餐"]
Actions --> Search["搜索用户"]
Toggle --> Reload["重新加载数据"]
Plan --> Reload
Search --> Reload
Reload --> RenderUI
Redirect --> End(["结束"])
RenderUI --> End
```
**图表来源**
- [app/(dashboard)/dashboard/admin/page.tsx](file://frontend/app/(dashboard)/dashboard/admin/page.tsx#L1-L435)
- [components/layout/sidebar.tsx:1-63](file://frontend/components/layout/sidebar.tsx#L1-L63)
**章节来源**
- [app/(dashboard)/dashboard/admin/page.tsx](file://frontend/app/(dashboard)/dashboard/admin/page.tsx#L1-L435)
- [components/layout/sidebar.tsx:1-63](file://frontend/components/layout/sidebar.tsx#L1-L63)
### 设置页面重构（标签页布局）
- 个人资料管理：支持用户名修改，实时同步到会话状态。
- 密码修改：提供当前密码、新密码、确认密码输入，包含密码强度验证。
- 订阅管理：展示当前套餐状态，支持套餐升级和取消订阅。
- 标签页组件：基于 Radix UI 实现语义化标签页，支持键盘导航和无障碍访问。
```mermaid
classDiagram
class SettingsPage {
+defaultProps : defaultValue
+render() : JSX.Element
}
class ProfileTab {
+name : string
+loading : boolean
+error : string
+success : boolean
+handleSave() : Promise<void>
}
class PasswordTab {
+oldPassword : string
+newPassword : string
+confirmPassword : string
+loading : boolean
+error : string
+success : boolean
+handleSubmit() : Promise<void>
}
class SubscriptionTab {
+plans : PlanDetail[]
+currentSub : SubscriptionData
+loading : boolean
+error : string
+success : string
+loadData() : Promise<void>
}
SettingsPage --> ProfileTab : "个人资料标签"
SettingsPage --> PasswordTab : "密码修改标签"
SettingsPage --> SubscriptionTab : "订阅管理标签"
```
**图表来源**
- [app/(dashboard)/dashboard/settings/page.tsx](file://frontend/app/(dashboard)/dashboard/settings/page.tsx#L1-L445)
- [components/ui/tabs.tsx:1-56](file://frontend/components/ui/tabs.tsx#L1-L56)
**章节来源**
- [app/(dashboard)/dashboard/settings/page.tsx](file://frontend/app/(dashboard)/dashboard/settings/page.tsx#L1-L445)
- [components/ui/tabs.tsx:1-56](file://frontend/components/ui/tabs.tsx#L1-L56)
### 数据获取与状态管理
- 会话状态：仪表盘页通过 next-auth/react 的 useSession 获取当前会话，包含访问令牌和管理员标识。
- API 客户端：封装 fetchWithAuth，自动添加 Authorization 头，统一处理非 2xx 错误并抛出异常，支持 401 自动重定向。
- 仪表盘数据：在依赖会话令牌时加载统计数据，包含加载态与错误态处理，失败时提供刷新操作。
- 管理员数据：管理员仪表板支持分页加载用户列表，包含搜索和过滤功能。
- 设置数据：设置页面各标签页独立管理状态，支持表单验证和实时反馈。
```mermaid
flowchart TD
Start(["进入页面"]) --> CheckToken["检查会话令牌"]
CheckToken --> HasToken{"存在令牌?"}
HasToken --> |否| EndNoop["不执行数据加载"]
HasToken --> |是| Fetch["调用 API 客户端获取数据"]
Fetch --> Ok{"请求成功?"}
Ok --> |是| SetData["设置数据并渲染"]
Ok --> |否| ShowErr["显示错误并提供刷新按钮"]
SetData --> EndDone(["完成"])
ShowErr --> EndDone
EndNoop --> EndDone
```
**图表来源**
- [app/(dashboard)/dashboard/page.tsx](file://frontend/app/(dashboard)/dashboard/page.tsx#L1-L227)
- [app/(dashboard)/dashboard/admin/page.tsx](file://frontend/app/(dashboard)/dashboard/admin/page.tsx#L1-L435)
- [app/(dashboard)/dashboard/settings/page.tsx](file://frontend/app/(dashboard)/dashboard/settings/page.tsx#L1-L445)
- [lib/api.ts:1-154](file://frontend/lib/api.ts#L1-L154)
**章节来源**
- [app/(dashboard)/dashboard/page.tsx](file://frontend/app/(dashboard)/dashboard/page.tsx#L1-L227)
- [app/(dashboard)/dashboard/admin/page.tsx](file://frontend/app/(dashboard)/dashboard/admin/page.tsx#L1-L435)
- [app/(dashboard)/dashboard/settings/page.tsx](file://frontend/app/(dashboard)/dashboard/settings/page.tsx#L1-L445)
- [lib/api.ts:1-154](file://frontend/lib/api.ts#L1-L154)
### UI 组件库与样式系统
- 设计理念：以 Radix UI 为基础构建语义化与可访问性友好的基础控件；使用 Tailwind 实现原子化样式与主题变量。
- 变体与尺寸：通过 class-variance-authority 为组件提供多种变体（如 default、destructive、outline 等）与尺寸（default、sm、lg、icon）。
- 主题与暗色模式：Tailwind 配置启用基于 class 的深色模式，颜色与圆角通过 CSS 变量统一管理。
- 复用策略：将通用 UI 抽象为可复用组件（如 Button、Input、Card、Dialog、Tabs 等），在页面中按需组合使用。
- 标签页组件：新增 Tabs 组件，支持标签页切换、内容渲染和无障碍访问。
```mermaid
classDiagram
class Button {
+variant : "default|destructive|outline|secondary|ghost|link"
+size : "default|sm|lg|icon"
+asChild : boolean
+ref : HTMLButtonElement
}
class Tabs {
+defaultValue : string
+value : string
+onValueChange : function
}
class UIComponents {
+Card
+Input
+Label
+Select
+Dialog
+DropdownMenu
+Tabs
+TabsList
+TabsTrigger
+TabsContent
+Table
}
Button --> UIComponents : "作为基础控件被复用"
Tabs --> UIComponents : "标签页导航"
```
**图表来源**
- [components/ui/button.tsx:1-57](file://frontend/components/ui/button.tsx#L1-L57)
- [components/ui/tabs.tsx:1-56](file://frontend/components/ui/tabs.tsx#L1-L56)
- [tailwind.config.ts:1-121](file://frontend/tailwind.config.ts#L1-L121)
**章节来源**
- [components/ui/button.tsx:1-57](file://frontend/components/ui/button.tsx#L1-L57)
- [components/ui/tabs.tsx:1-56](file://frontend/components/ui/tabs.tsx#L1-L56)
- [tailwind.config.ts:1-121](file://frontend/tailwind.config.ts#L1-L121)
### 服务器组件与客户端组件的混合使用
- 服务器组件：仪表盘布局在客户端通过 useSession 校验会话并进行重定向，避免客户端渲染无意义内容。
- 客户端组件：登录页、注册页、忘记密码页、重置密码页、邮箱验证页、仪表盘页、管理员仪表板、设置页均标记为客户端组件，以便使用 hooks（如 useSession、useRouter）与交互逻辑。
- Provider 注入：根布局注入 Providers，使子树中的客户端组件可共享会话状态。
- 权限路由：侧边栏根据用户权限动态渲染，管理员用户显示额外的管理后台入口。
```mermaid
sequenceDiagram
participant S as "服务器组件<br/>app/(dashboard)/layout.tsx"
participant C as "客户端组件<br/>app/(dashboard)/dashboard/page.tsx"
participant P as "Providers<br/>components/providers.tsx"
S->>S : "getServerSession() 校验会话"
S-->>S : "无会话 -> 重定向到 /login"
S-->>P : "渲染根 Provider"
P-->>C : "向客户端组件提供会话状态"
C->>C : "useSession/useEffect 加载数据"
C->>C : "根据权限渲染侧边栏"
```
**图表来源**
- [app/(dashboard)/layout.tsx:1-146](file://frontend/app/(dashboard)/layout.tsx#L1-L146)
- [app/(dashboard)/dashboard/page.tsx](file://frontend/app/(dashboard)/dashboard/page.tsx#L1-L227)
- [components/providers.tsx:1-9](file://frontend/components/providers.tsx#L1-L9)
- [components/layout/sidebar.tsx:1-63](file://frontend/components/layout/sidebar.tsx#L1-L63)
**章节来源**
- [app/(dashboard)/layout.tsx:1-146](file://frontend/app/(dashboard)/layout.tsx#L1-L146)
- [app/(dashboard)/dashboard/page.tsx](file://frontend/app/(dashboard)/dashboard/page.tsx#L1-L227)
- [components/providers.tsx:1-9](file://frontend/components/providers.tsx#L1-L9)
- [components/layout/sidebar.tsx:1-63](file://frontend/components/layout/sidebar.tsx#L1-L63)
### 错误处理机制
- API 层：fetchWithAuth 在非 2xx 时解析错误消息并抛出异常，401 状态自动重定向到登录页，保证上层统一处理。
- 页面层：各认证页面在认证失败时显示错误提示，管理员仪表板和设置页面提供详细的错误反馈和重试机制。
- 路由保护：客户端无会话时直接重定向，避免进入受保护页面。
- 表单验证：设置页面各表单包含客户端验证，提供即时反馈。
**章节来源**
- [lib/api.ts:1-154](file://frontend/lib/api.ts#L1-L154)
- [app/(auth)/login/page.tsx](file://frontend/app/(auth)/login/page.tsx#L1-L93)
- [app/(auth)/register/page.tsx](file://frontend/app/(auth)/register/page.tsx#L1-L128)
- [app/(auth)/forgot-password/page.tsx](file://frontend/app/(auth)/forgot-password/page.tsx#L1-L101)
- [app/(auth)/reset-password/page.tsx](file://frontend/app/(auth)/reset-password/page.tsx#L1-L148)
- [app/(auth)/verify-email/page.tsx](file://frontend/app/(auth)/verify-email/page.tsx#L1-L155)
- [app/(dashboard)/dashboard/admin/page.tsx](file://frontend/app/(dashboard)/dashboard/admin/page.tsx#L1-L435)
- [app/(dashboard)/dashboard/settings/page.tsx](file://frontend/app/(dashboard)/dashboard/settings/page.tsx#L1-L445)
- [app/(dashboard)/layout.tsx:1-146](file://frontend/app/(dashboard)/layout.tsx#L1-L146)
## E2E测试框架
### Playwright测试配置
系统集成了完整的E2E测试框架，基于Playwright提供跨浏览器测试能力：
- **测试环境配置**：支持Chrome、Firefox、Safari三种浏览器并行测试
- **测试执行策略**：串行执行，失败重试2次，截图仅在失败时捕获
- **测试报告**：生成HTML格式的详细测试报告
- **自动化启动**：测试服务器自动启动，支持热重载
```mermaid
flowchart TD
Start(["开始E2E测试"]) --> Config["加载Playwright配置"]
Config --> Browser["启动浏览器实例"]
Browser --> Server["启动本地开发服务器"]
Server --> Tests["执行测试用例"]
Tests --> Report["生成测试报告"]
Report --> End(["测试完成"])
subgraph "测试用例"
Test1["登录页面测试"]
Test2["Dashboard健康状态测试"]
Test3["响应式设计测试"]
Test4["行动建议测试"]
end
subgraph "页面对象"
Page1["LoginPage对象"]
Page2["DashboardPage对象"]
end
```
**图表来源**
- [playwright.config.ts:1-39](file://frontend/playwright.config.ts#L1-L39)
- [e2e/tests/login.spec.ts:1-126](file://frontend/e2e/tests/login.spec.ts#L1-L126)
- [e2e/tests/dashboard-health.spec.ts:1-264](file://frontend/e2e/tests/dashboard-health.spec.ts#L1-L264)
### 测试用例覆盖范围
- **登录页面测试**：验证页面重定向、表单元素、HTML5验证、错误处理、链接功能
- **Dashboard健康状态测试**：验证页面标题、概览卡片、平台评分、行动建议、骨架屏
- **响应式设计测试**：验证移动端和桌面端的不同布局表现
- **颜色传达状态测试**：验证不同健康状态的颜色编码
### 页面对象模式
采用Page Object模式封装测试逻辑：
- **LoginPage**：封装登录表单的所有交互操作
- **DashboardPage**：封装Dashboard页面的元素定位和数据提取
**章节来源**
- [playwright.config.ts:1-39](file://frontend/playwright.config.ts#L1-L39)
- [e2e/tests/login.spec.ts:1-126](file://frontend/e2e/tests/login.spec.ts#L1-L126)
- [e2e/tests/dashboard-health.spec.ts:1-264](file://frontend/e2e/tests/dashboard-health.spec.ts#L1-L264)
- [e2e/pages/login.page.ts:1-36](file://frontend/e2e/pages/login.page.ts#L1-L36)
- [e2e/pages/dashboard.page.ts:1-74](file://frontend/e2e/pages/dashboard.page.ts#L1-L74)
## 业务组件库
### 组件库架构
GEO业务组件库专注于企业级业务场景，提供高度可定制化的组件解决方案：
- **组件分类**：按业务领域划分，包括代理管理、监控告警、指标展示等
- **类型安全**：完整的TypeScript类型定义，确保开发时的类型安全
- **可复用性**：模块化设计，支持单独导入和批量导出
- **主题适配**：深度集成Tailwind CSS，支持品牌色彩定制
### 核心业务组件
#### AgentStatusCard - 代理状态卡片
提供AI代理的状态可视化展示，支持多种状态指示和详细信息展示：
- **状态类型**：online（在线）、offline（离线）、busy（繁忙）、error（错误）
- **视觉反馈**：脉冲动画、颜色编码、状态徽章
- **信息维度**：代理名称、描述、当前任务、活跃时间、完成统计
- **交互设计**：悬停效果、响应式布局
#### AlertCard - 告警卡片
企业级告警管理系统，支持多级别告警状态和操作：
- **严重级别**：critical（严重）、warning（警告）、info（信息）、success（成功）
- **视觉层次**：图标、颜色、脉冲动画、状态点
- **操作功能**：告警关闭、查看详情、批量处理
- **扩展性**：自定义图标、动作按钮、时间戳
#### 其他业务组件
- **MetricCard**：指标卡片，支持趋势方向和数据点配置
- **TimelineStep**：时间轴步骤组件，支持多状态展示
- **PlatformBadge**：平台标识组件，支持配置化平台信息
- **ClientSwitcher**：客户切换器，支持多租户场景
- **StageProgress**：阶段进度组件，支持工作流状态展示
```mermaid
classDiagram
class BusinessComponents {
<<index>>
+StageProgress
+MetricCard
+AgentStatusCard
+TimelineStep
+PlatformBadge
+ClientSwitcher
+AlertCard
}
class AgentStatusCard {
+name : string
+status : AgentStatus
+currentTask? : string
+lastActiveAt? : string
+completedCount? : number
+render() : JSX.Element
}
class AlertCard {
+alerts : AlertCardItem[]
+title? : string
+onDismiss? : Function
+maxVisible? : number
+render() : JSX.Element
}
class BusinessComponentsIndex {
+exportAll() : void
+importSpecific() : void
}
BusinessComponents --> AgentStatusCard
BusinessComponents --> AlertCard
BusinessComponentsIndex --> BusinessComponents
```
**图表来源**
- [components/business/index.ts:1-29](file://frontend/components/business/index.ts#L1-L29)
- [components/business/agent-status-card.tsx:1-134](file://frontend/components/business/agent-status-card.tsx#L1-L134)
- [components/business/alert-card.tsx:1-203](file://frontend/components/business/alert-card.tsx#L1-L203)
### 组件导出策略
提供两种导出方式满足不同使用场景：
- **统一索引导出**：通过index.ts文件提供集中导出，便于批量导入
- **按需导入**：支持单独导入特定组件，优化打包体积
**章节来源**
- [components/business/index.ts:1-29](file://frontend/components/business/index.ts#L1-L29)
- [components/business/agent-status-card.tsx:1-134](file://frontend/components/business/agent-status-card.tsx#L1-L134)
- [components/business/alert-card.tsx:1-203](file://frontend/components/business/alert-card.tsx#L1-L203)
## 依赖分析
- 核心框架：Next.js 14（App Router）、React 18。
- 认证：NextAuth.js（凭据提供者、JWT 会话、回调映射、管理员权限支持）。
- UI：Radix UI（对话框、下拉菜单、标签页、选择器等）、Lucide React 图标。
- 样式：Tailwind CSS、Tailwind 插件（动画）、class-variance-authority、clsx、tailwind-merge。
- 图表：Recharts 用于可视化展示。
- 开发工具：ESLint、TypeScript、PostCSS、Tailwind。
- **新增**：Playwright（E2E测试框架）、测试工具链。
```mermaid
graph LR
N["Next.js 14"] --> R["React 18"]
N --> NA["NextAuth.js"]
NA --> AC["凭据提供者"]
NA --> ADMIN["管理员权限"]
UI["Radix UI + Lucide React"] --> TW["Tailwind CSS"]
TW --> CN["class-variance-authority"]
CN --> CL["clsx"]
CL --> TM["tailwind-merge"]
VIZ["Recharts"] --> UI
TS["TypeScript"] --> N
ESL["ESLint"] --> N
PC["PostCSS"] --> TW
TABS["Tabs 组件"] --> UI
PW["Playwright"] --> TEST["E2E测试"]
BC["Business Components"] --> UI
```
**图表来源**
- [package.json:1-45](file://frontend/package.json#L1-L45)
- [tailwind.config.ts:1-121](file://frontend/tailwind.config.ts#L1-L121)
- [components/ui/tabs.tsx:1-56](file://frontend/components/ui/tabs.tsx#L1-L56)
- [playwright.config.ts:1-39](file://frontend/playwright.config.ts#L1-L39)
**章节来源**
- [package.json:1-45](file://frontend/package.json#L1-L45)
- [tailwind.config.ts:1-121](file://frontend/tailwind.config.ts#L1-L121)
- [components/ui/tabs.tsx:1-56](file://frontend/components/ui/tabs.tsx#L1-L56)
## 性能考虑
- App Router 与服务器组件：利用服务器端渲染与路由组隔离，减少不必要的客户端渲染与网络请求。
- 客户端水合：仅在必要页面标记为客户端组件，避免过度水合。
- 缓存与重试：可在 API 客户端增加缓存策略与重试逻辑（建议项）。
- 图表渲染：对大数据集使用虚拟化或采样策略（建议项）。
- 资源优化：开启图片与静态资源优化（Next.js 默认支持），按需加载第三方库。
- 构建优化：使用生产构建与代码分割，避免打包体积过大。
- 权限控制：客户端权限检查，减少无意义的渲染。
- **新增**：E2E测试性能：并行测试执行，智能重试机制，减少测试时间。
## 故障排除指南
- 登录失败：检查凭据是否正确，确认后端认证接口可用；查看登录页错误提示与 NextAuth 回调日志。
- 会话丢失：确认 Cookie 设置、SameSite 与跨域配置；检查 NextAuth 回调是否正确写入 token。
- 仪表盘空白：确认客户端 useSession 返回有效会话；检查客户端状态管理。
- 认证页面异常：检查对应认证页面的错误状态和网络请求；确认 API 端点是否正确。
- 管理员功能不可用：确认用户 is_admin 标识；检查侧边栏权限渲染逻辑。
- 设置页面问题：检查各标签页的状态管理；确认 API 调用和表单验证逻辑。
- API 请求失败：查看 fetchWithAuth 抛出的错误信息，确认后端接口路径与鉴权头是否正确。
- 样式异常：检查 Tailwind 配置 content 路径与 CSS 变量是否生效；确认暗色模式 class 是否正确切换。
- **新增**：E2E测试失败：检查测试环境配置、页面元素定位、网络请求超时；查看测试报告详细信息。
**章节来源**
- [app/(auth)/login/page.tsx](file://frontend/app/(auth)/login/page.tsx#L1-L93)
- [app/(auth)/register/page.tsx](file://frontend/app/(auth)/register/page.tsx#L1-L128)
- [app/(auth)/forgot-password/page.tsx](file://frontend/app/(auth)/forgot-password/page.tsx#L1-L101)
- [app/(auth)/reset-password/page.tsx](file://frontend/app/(auth)/reset-password/page.tsx#L1-L148)
- [app/(auth)/verify-email/page.tsx](file://frontend/app/(auth)/verify-email/page.tsx#L1-L155)
- [app/(dashboard)/dashboard/admin/page.tsx](file://frontend/app/(dashboard)/dashboard/admin/page.tsx#L1-L435)
- [app/(dashboard)/dashboard/settings/page.tsx](file://frontend/app/(dashboard)/dashboard/settings/page.tsx#L1-L445)
- [app/(dashboard)/layout.tsx:1-146](file://frontend/app/(dashboard)/layout.tsx#L1-L146)
- [lib/api.ts:1-154](file://frontend/lib/api.ts#L1-L154)
- [tailwind.config.ts:1-121](file://frontend/tailwind.config.ts#L1-L121)
- [playwright.config.ts:1-39](file://frontend/playwright.config.ts#L1-L39)
## 结论
本架构以 Next.js 14 App Router 为核心，结合服务器组件与客户端组件的混合模式，实现了清晰的页面组织与路由保护；通过 NextAuth.js 的凭据提供者与 JWT 会话策略，完成了前后端认证协作，支持完整的认证生命周期；UI 组件库以 Radix UI 与 Tailwind 为基础，具备良好的可维护性与一致性，新增的 Tabs 组件支持复杂的多标签页界面；API 客户端统一处理鉴权与错误，配合页面层的状态与错误处理，形成完整的前端数据流。
**更新** 新增的E2E测试框架显著提升了代码质量保证能力，通过Playwright实现跨浏览器兼容性测试；业务组件库扩展了企业级应用场景的组件支持，包括代理状态管理、告警系统、指标展示等功能；仪表板布局重构提供了更好的用户体验和导航效率。建议在后续迭代中进一步完善测试覆盖率、组件文档化和性能监控，持续提升系统的稳定性和可维护性。
## 附录
- 最佳实践清单
- 使用路由组隔离功能域，保持页面组织清晰。
- 将路由保护放在客户端，优先保障用户体验。
- 仅在需要时标记客户端组件，减少水合成本。
- 统一错误处理与用户反馈，提供明确的重试与刷新能力。
- 严格类型约束，结合 TypeScript 与自定义类型扩展，降低运行时风险。
- 支持管理员权限的渐进式增强，避免过度设计。
- 使用标签页组件组织复杂设置界面，提升用户体验。
- 实施细粒度的权限控制，确保数据安全。
- 持续优化构建产物与运行时性能，关注首屏与交互延迟。
- **新增**：建立完善的E2E测试流程，确保跨浏览器兼容性。
- **新增**：文档化业务组件使用规范，提升团队协作效率。
- **新增**：实施测试驱动开发，提高代码质量和稳定性。
Reference in New Issue View Git Blame Copy Permalink