# 前端系统架构 **本文档引用的文件** - [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) ## 更新摘要 **所做变更** - 新增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
根布局与全局样式"] --> B["components/providers.tsx
SessionProvider"] A --> C["app/(auth)/layout.tsx
认证页容器"] A --> D["app/(dashboard)/layout.tsx
仪表盘容器"] C --> F["app/(auth)/login/page.tsx
登录页"] C --> G["app/(auth)/register/page.tsx
注册页"] C --> H["app/(auth)/forgot-password/page.tsx
忘记密码页"] C --> I["app/(auth)/reset-password/page.tsx
重置密码页"] C --> J["app/(auth)/verify-email/page.tsx
邮箱验证页"] D --> K["app/(dashboard)/dashboard/page.tsx
仪表盘页"] D --> L["app/(dashboard)/dashboard/admin/page.tsx
管理员仪表板"] D --> M["app/(dashboard)/dashboard/settings/page.tsx
设置页"] B --> N["app/api/auth/[...nextauth]/route.ts
NextAuth 路由处理器"] A --> O["tailwind.config.ts
Tailwind 配置"] A --> P["next.config.mjs
Next 配置"] Q["components/layout/sidebar.tsx
侧边栏导航"] --> D R["components/ui/tabs.tsx
标签页组件"] --> M S["e2e/ 目录
E2E测试框架"] --> T["playwright.config.ts
测试配置"] S --> U["e2e/tests/ 目录
测试用例"] S --> V["e2e/pages/ 目录
页面对象"] W["components/business/ 目录
业务组件库"] --> X["agent-status-card.tsx
代理状态卡片"] W --> Y["alert-card.tsx
告警卡片"] W --> Z["metric-card.tsx
指标卡片"] ``` **图表来源** - [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["用户界面
客户端组件"] end subgraph "Next.js 应用" RL["根布局
app/layout.tsx"] PR["会话提供者
components/providers.tsx"] AL["认证布局
app/(auth)/layout.tsx"] DL["仪表盘布局
app/(dashboard)/layout.tsx"] LOGIN["登录页
app/(auth)/login/page.tsx"] REGISTER["注册页
app/(auth)/register/page.tsx"] FP["忘记密码页
app/(auth)/forgot-password/page.tsx"] RP["重置密码页
app/(auth)/reset-password/page.tsx"] VE["邮箱验证页
app/(auth)/verify-email/page.tsx"] DB["仪表盘页
app/(dashboard)/dashboard/page.tsx"] ADMIN["管理员仪表板
app/(dashboard)/dashboard/admin/page.tsx"] SETTINGS["设置页
app/(dashboard)/dashboard/settings/page.tsx"] AH["NextAuth 路由
app/api/auth/[...nextauth]/route.ts"] UI["UI 组件库
components/ui/*"] LH["头部组件
components/layout/header.tsx"] LS["侧边栏组件
components/layout/sidebar.tsx"] BC["业务组件库
components/business/*"] DP["Dashboard组件
components/dashboard/*"] end subgraph "认证服务" NA["NextAuth 服务
lib/auth.ts"] end subgraph "后端 API" API["业务 API 客户端
lib/api.ts"] BE["后端服务
backend/app/*"] end subgraph "E2E测试框架" PW["Playwright
playwright.config.ts"] DS["Dashboard测试
e2e/tests/dashboard-health.spec.ts"] LSpec["登录测试
e2e/tests/login.spec.ts"] DPg["Dashboard页面
e2e/pages/dashboard.page.ts"] LPg["Login页面
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 "注册页
app/(auth)/register/page.tsx" participant LOGIN as "登录页
app/(auth)/login/page.tsx" participant FP as "忘记密码页
app/(auth)/forgot-password/page.tsx" participant RP as "重置密码页
app/(auth)/reset-password/page.tsx" participant VE as "邮箱验证页
app/(auth)/verify-email/page.tsx" participant AH as "NextAuth 路由
app/api/auth/[...nextauth]/route.ts" participant NA as "NextAuth 配置
lib/auth.ts" participant BE as "后端服务
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 } class PasswordTab { +oldPassword : string +newPassword : string +confirmPassword : string +loading : boolean +error : string +success : boolean +handleSubmit() : Promise } class SubscriptionTab { +plans : PlanDetail[] +currentSub : SubscriptionData +loading : boolean +error : string +success : string +loadData() : Promise } 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 "服务器组件
app/(dashboard)/layout.tsx" participant C as "客户端组件
app/(dashboard)/dashboard/page.tsx" participant P as "Providers
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 { <> +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测试流程，确保跨浏览器兼容性。 - **新增**：文档化业务组件使用规范，提升团队协作效率。 - **新增**：实施测试驱动开发，提高代码质量和稳定性。