436 lines
22 KiB
Markdown
436 lines
22 KiB
Markdown
# 页面组件设计
|
||
|
||
<cite>
|
||
**本文档引用的文件**
|
||
- [frontend/app/layout.tsx](file://frontend/app/layout.tsx)
|
||
- [frontend/app/(dashboard)/layout.tsx](file://frontend/app/(dashboard)/layout.tsx)
|
||
- [frontend/components/layout/header.tsx](file://frontend/components/layout/header.tsx)
|
||
- [frontend/components/layout/sidebar.tsx](file://frontend/components/layout/sidebar.tsx)
|
||
- [frontend/lib/api.ts](file://frontend/lib/api.ts)
|
||
- [frontend/app/(dashboard)/dashboard/page.tsx](file://frontend/app/(dashboard)/dashboard/page.tsx)
|
||
- [frontend/app/(dashboard)/dashboard/queries/page.tsx](file://frontend/app/(dashboard)/dashboard/queries/page.tsx)
|
||
- [frontend/app/(dashboard)/dashboard/citations/page.tsx](file://frontend/app/(dashboard)/dashboard/citations/page.tsx)
|
||
- [frontend/app/(dashboard)/dashboard/reports/page.tsx](file://frontend/app/(dashboard)/dashboard/reports/page.tsx)
|
||
- [frontend/app/(dashboard)/dashboard/settings/page.tsx](file://frontend/app/(dashboard)/dashboard/settings/page.tsx)
|
||
- [frontend/components/ui/table.tsx](file://frontend/components/ui/table.tsx)
|
||
- [frontend/components/ui/dialog.tsx](file://frontend/components/ui/dialog.tsx)
|
||
- [frontend/lib/platforms.ts](file://frontend/lib/platforms.ts)
|
||
- [frontend/lib/utils.ts](file://frontend/lib/utils.ts)
|
||
- [frontend/components/charts/trend-chart.tsx](file://frontend/components/charts/trend-chart.tsx)
|
||
- [frontend/components/charts/platform-chart.tsx](file://frontend/components/charts/platform-chart.tsx)
|
||
</cite>
|
||
|
||
## 更新摘要
|
||
**变更内容**
|
||
- 新增完整的仪表板页面组件系统实现
|
||
- 更新数据总览页、查询管理页、引用记录页和报告导出页的具体实现
|
||
- 完善图表组件的详细分析和使用说明
|
||
- 增强API客户端的接口文档和错误处理机制
|
||
- 优化页面级数据获取策略和状态管理
|
||
|
||
## 目录
|
||
1. [引言](#引言)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构概览](#架构概览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排除指南](#故障排除指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 引言
|
||
本文件系统性梳理 GEO 平台前端页面组件的设计与实现，覆盖仪表板、查询管理、引用数据、报告导出与设置页面。内容包括页面布局与导航结构、用户体验流程、页面级数据获取策略、状态管理与错误边界处理、页面间导航逻辑与路由参数传递、页面生命周期管理、性能优化与懒加载策略、SEO 配置以及开发规范与最佳实践。
|
||
|
||
**更新** 本次更新反映了应用的完整实现，所有页面组件均已开发完成并集成到Next.js应用架构中，包括数据总览、查询管理、引用记录、报告导出和设置页面的完整功能实现。
|
||
|
||
## 项目结构
|
||
前端采用 Next.js App Router 的分组路由模式，将认证相关页面置于 `(auth)` 分组，仪表板相关页面置于 `(dashboard)` 分组。根布局负责全局样式与 Provider 包装；仪表板布局负责权限校验、侧边栏与头部导航的统一渲染。
|
||
|
||
```mermaid
|
||
graph TB
|
||
root_layout["根布局<br/>frontend/app/layout.tsx"] --> providers["Provider 包装<br/>frontend/components/providers.tsx"]
|
||
dashboard_layout["仪表板布局<br/>frontend/app/(dashboard)/layout.tsx"] --> sidebar["侧边栏<br/>frontend/components/layout/sidebar.tsx"]
|
||
dashboard_layout --> header["头部导航<br/>frontend/components/layout/header.tsx"]
|
||
dashboard_layout --> pages["仪表板页面集合<br/>frontend/app/(dashboard)/dashboard/*"]
|
||
pages --> dashboard_page["数据总览<br/>page.tsx"]
|
||
pages --> queries_page["查询管理<br/>queries/page.tsx"]
|
||
pages --> citations_page["引用记录<br/>citations/page.tsx"]
|
||
pages --> reports_page["报告导出<br/>reports/page.tsx"]
|
||
pages --> settings_page["设置<br/>settings/page.tsx"]
|
||
```
|
||
|
||
**图示来源**
|
||
- [frontend/app/layout.tsx:1-37](file://frontend/app/layout.tsx#L1-L37)
|
||
- [frontend/app/(dashboard)/layout.tsx:1-27](file://frontend/app/(dashboard)/layout.tsx#L1-L27)
|
||
- [frontend/components/layout/sidebar.tsx:1-54](file://frontend/components/layout/sidebar.tsx#L1-L54)
|
||
- [frontend/components/layout/header.tsx:1-30](file://frontend/components/layout/header.tsx#L1-L30)
|
||
|
||
**章节来源**
|
||
- [frontend/app/layout.tsx:1-37](file://frontend/app/layout.tsx#L1-L37)
|
||
- [frontend/app/(dashboard)/layout.tsx:1-27](file://frontend/app/(dashboard)/layout.tsx#L1-L27)
|
||
|
||
## 核心组件
|
||
- 布局与导航
|
||
- 根布局：定义站点元数据、字体变量与全局样式，注入 Provider。
|
||
- 仪表板布局：服务端会话校验，未登录重定向至登录页；渲染侧边栏与头部，承载主内容区域。
|
||
- 头部组件：展示用户名与登出按钮，使用客户端会话状态。
|
||
- 侧边栏组件：基于路径高亮当前菜单项，提供统一导航入口。
|
||
- UI 组件库
|
||
- 表格组件：封装响应式表格容器与表头/体/行/单元格等基础结构。
|
||
- 对话框组件：基于 Radix UI 实现模态对话框，支持触发器、内容、标题与描述。
|
||
- 图表组件
|
||
- 趋势图组件：基于 Recharts 实现折线图，展示过去30天引用趋势。
|
||
- 平台对比图：基于 Recharts 实现柱状图，展示各平台引用率对比。
|
||
- 工具与常量
|
||
- 平台映射：提供平台键值到中文名称的映射与平台选项列表。
|
||
- 工具函数：类名合并工具，用于组合 Tailwind 类。
|
||
- API 客户端：统一封装鉴权头、错误处理与各模块接口（认证、查询、引用、报告）。
|
||
|
||
**更新** 新增了图表组件的详细实现分析，包括数据结构定义、响应式容器配置和交互功能。
|
||
|
||
**章节来源**
|
||
- [frontend/components/layout/header.tsx:1-30](file://frontend/components/layout/header.tsx#L1-L30)
|
||
- [frontend/components/layout/sidebar.tsx:1-54](file://frontend/components/layout/sidebar.tsx#L1-L54)
|
||
- [frontend/components/ui/table.tsx:1-118](file://frontend/components/ui/table.tsx#L1-L118)
|
||
- [frontend/components/ui/dialog.tsx:1-123](file://frontend/components/ui/dialog.tsx#L1-L123)
|
||
- [frontend/components/charts/trend-chart.tsx:1-60](file://frontend/components/charts/trend-chart.tsx#L1-L60)
|
||
- [frontend/components/charts/platform-chart.tsx:1-68](file://frontend/components/charts/platform-chart.tsx#L1-L68)
|
||
- [frontend/lib/platforms.ts:1-18](file://frontend/lib/platforms.ts#L1-L18)
|
||
- [frontend/lib/utils.ts:1-7](file://frontend/lib/utils.ts#L1-L7)
|
||
- [frontend/lib/api.ts:1-79](file://frontend/lib/api.ts#L1-L79)
|
||
|
||
## 架构概览
|
||
整体采用"布局层 + 页面层 + 组件层 + 工具层"的分层设计。页面层通过客户端会话获取令牌，调用 API 客户端进行数据拉取与写入；UI 组件层提供可复用的基础控件；工具层提供通用能力（类名合并、平台映射、API 封装）；图表组件独立封装，按需渲染。
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "布局层"
|
||
root_layout["根布局"]
|
||
dashboard_layout["仪表板布局"]
|
||
header["头部"]
|
||
sidebar["侧边栏"]
|
||
end
|
||
subgraph "页面层"
|
||
dashboard_page["数据总览页"]
|
||
queries_page["查询管理页"]
|
||
citations_page["引用记录页"]
|
||
reports_page["报告导出页"]
|
||
settings_page["设置页"]
|
||
end
|
||
subgraph "组件层"
|
||
table["表格组件"]
|
||
dialog["对话框组件"]
|
||
trend_chart["趋势图组件"]
|
||
platform_chart["平台对比图组件"]
|
||
end
|
||
subgraph "工具层"
|
||
utils["工具函数"]
|
||
platforms["平台映射"]
|
||
api_client["API 客户端"]
|
||
end
|
||
root_layout --> dashboard_layout
|
||
dashboard_layout --> header
|
||
dashboard_layout --> sidebar
|
||
dashboard_layout --> dashboard_page
|
||
dashboard_layout --> queries_page
|
||
dashboard_layout --> citations_page
|
||
dashboard_layout --> reports_page
|
||
dashboard_layout --> settings_page
|
||
dashboard_page --> trend_chart
|
||
dashboard_page --> platform_chart
|
||
queries_page --> table
|
||
queries_page --> dialog
|
||
citations_page --> table
|
||
reports_page --> api_client
|
||
settings_page --> utils
|
||
settings_page --> platforms
|
||
api_client --> utils
|
||
table --> utils
|
||
dialog --> utils
|
||
trend_chart --> utils
|
||
platform_chart --> utils
|
||
```
|
||
|
||
**图示来源**
|
||
- [frontend/app/layout.tsx:1-37](file://frontend/app/layout.tsx#L1-L37)
|
||
- [frontend/app/(dashboard)/layout.tsx:1-27](file://frontend/app/(dashboard)/layout.tsx#L1-L27)
|
||
- [frontend/components/layout/header.tsx:1-30](file://frontend/components/layout/header.tsx#L1-L30)
|
||
- [frontend/components/layout/sidebar.tsx:1-54](file://frontend/components/layout/sidebar.tsx#L1-L54)
|
||
- [frontend/app/(dashboard)/dashboard/page.tsx:1-227](file://frontend/app/(dashboard)/dashboard/page.tsx#L1-L227)
|
||
- [frontend/app/(dashboard)/dashboard/queries/page.tsx:1-526](file://frontend/app/(dashboard)/dashboard/queries/page.tsx#L1-L526)
|
||
- [frontend/app/(dashboard)/dashboard/citations/page.tsx:1-294](file://frontend/app/(dashboard)/dashboard/citations/page.tsx#L1-L294)
|
||
- [frontend/app/(dashboard)/dashboard/reports/page.tsx:1-200](file://frontend/app/(dashboard)/dashboard/reports/page.tsx#L1-L200)
|
||
- [frontend/app/(dashboard)/dashboard/settings/page.tsx:1-172](file://frontend/app/(dashboard)/dashboard/settings/page.tsx#L1-L172)
|
||
- [frontend/components/ui/table.tsx:1-118](file://frontend/components/ui/table.tsx#L1-L118)
|
||
- [frontend/components/ui/dialog.tsx:1-123](file://frontend/components/ui/dialog.tsx#L1-L123)
|
||
- [frontend/components/charts/trend-chart.tsx:1-60](file://frontend/components/charts/trend-chart.tsx#L1-L60)
|
||
- [frontend/components/charts/platform-chart.tsx:1-68](file://frontend/components/charts/platform-chart.tsx#L1-L68)
|
||
- [frontend/lib/utils.ts:1-7](file://frontend/lib/utils.ts#L1-L7)
|
||
- [frontend/lib/platforms.ts:1-18](file://frontend/lib/platforms.ts#L1-L18)
|
||
- [frontend/lib/api.ts:1-79](file://frontend/lib/api.ts#L1-L79)
|
||
|
||
## 详细组件分析
|
||
|
||
### 仪表板页面（数据总览）
|
||
- 页面职责
|
||
- 展示用户关键指标卡片（总查询次数、总引用次数、引用率、平均引用位置）。
|
||
- 展示过去30天引用趋势折线图与平台引用率对比柱状图。
|
||
- 数据流
|
||
- 客户端从会话中获取访问令牌，调用引用统计接口获取聚合数据。
|
||
- 加载状态、错误状态与空数据提示分别处理。
|
||
- 用户体验
|
||
- 卡片式布局，响应式网格适配不同屏幕尺寸。
|
||
- 图表组件使用响应式容器，确保在小屏设备上正常显示。
|
||
- 错误边界
|
||
- 请求失败时显示错误提示与刷新按钮；加载中显示旋转指示器。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant U as "用户"
|
||
participant P as "仪表板页面"
|
||
participant S as "会话状态"
|
||
participant A as "API 客户端"
|
||
participant B as "后端"
|
||
U->>P : 进入页面
|
||
P->>S : 读取 accessToken
|
||
alt 有令牌
|
||
P->>A : 调用引用统计接口
|
||
A->>B : 发起带授权头的请求
|
||
B-->>A : 返回统计数据
|
||
A-->>P : 解析并返回数据
|
||
P-->>U : 渲染指标卡片与图表
|
||
else 无令牌
|
||
P-->>U : 显示加载占位
|
||
end
|
||
```
|
||
|
||
**图示来源**
|
||
- [frontend/app/(dashboard)/dashboard/page.tsx:29-47](file://frontend/app/(dashboard)/dashboard/page.tsx#L29-L47)
|
||
- [frontend/lib/api.ts:67-70](file://frontend/lib/api.ts#L67-L70)
|
||
|
||
**章节来源**
|
||
- [frontend/app/(dashboard)/dashboard/page.tsx:1-227](file://frontend/app/(dashboard)/dashboard/page.tsx#L1-L227)
|
||
- [frontend/components/charts/trend-chart.tsx:1-60](file://frontend/components/charts/trend-chart.tsx#L1-L60)
|
||
- [frontend/components/charts/platform-chart.tsx:1-68](file://frontend/components/charts/platform-chart.tsx#L1-L68)
|
||
|
||
### 查询管理页面
|
||
- 页面职责
|
||
- 列表展示查询词，支持新增、编辑、删除与"立即查询"操作。
|
||
- 提供平台多选、频率选择、品牌别名输入等配置项。
|
||
- 数据流
|
||
- 客户端加载查询词列表；新增/编辑通过 PUT/POST 写入；删除通过 DELETE。
|
||
- 表单校验：关键词、目标品牌必填，至少选择一个平台。
|
||
- 用户体验
|
||
- 使用对话框承载表单，支持取消与保存；删除操作二次确认。
|
||
- 列表支持平台徽标展示与状态徽章。
|
||
- 错误边界
|
||
- 表单校验失败与网络错误分别提示；保存与删除过程禁用按钮并显示加载状态。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start(["进入查询管理页"]) --> Load["加载查询词列表"]
|
||
Load --> View{"列表为空？"}
|
||
View --> |是| Empty["显示空状态与添加按钮"]
|
||
View --> |否| List["渲染查询词表格"]
|
||
AddEdit["打开新增/编辑对话框"] --> Form["填写表单关键词/品牌/平台/频率"]
|
||
Form --> Validate{"校验通过？"}
|
||
Validate --> |否| ShowError["显示错误提示"]
|
||
Validate --> |是| Save["调用保存接口"]
|
||
Save --> Refresh["刷新列表并关闭对话框"]
|
||
Delete["打开删除确认"] --> Confirm{"确认删除？"}
|
||
Confirm --> |否| Cancel["取消"]
|
||
Confirm --> |是| Remove["调用删除接口"] --> Refresh
|
||
Empty --> AddEdit
|
||
```
|
||
|
||
**图示来源**
|
||
- [frontend/app/(dashboard)/dashboard/queries/page.tsx:143-156](file://frontend/app/(dashboard)/dashboard/queries/page.tsx#L143-L156)
|
||
- [frontend/lib/api.ts:56-66](file://frontend/lib/api.ts#L56-L66)
|
||
|
||
**章节来源**
|
||
- [frontend/app/(dashboard)/dashboard/queries/page.tsx:1-526](file://frontend/app/(dashboard)/dashboard/queries/page.tsx#L1-L526)
|
||
- [frontend/components/ui/dialog.tsx:1-123](file://frontend/components/ui/dialog.tsx#L1-L123)
|
||
- [frontend/lib/platforms.ts:1-18](file://frontend/lib/platforms.ts#L1-L18)
|
||
|
||
### 引用记录页面
|
||
- 页面职责
|
||
- 展示跨平台的引用检测结果，支持按查询词、平台、日期范围筛选。
|
||
- 数据流
|
||
- 客户端加载查询词下拉选项与引用记录列表；筛选条件通过查询字符串拼接。
|
||
- 支持重置筛选条件并重新加载。
|
||
- 用户体验
|
||
- 筛选区采用栅格布局，适配移动端；表格支持横向滚动。
|
||
- 引用状态以图标与颜色区分，引用位置与文本片段清晰展示。
|
||
- 错误边界
|
||
- 加载失败时显示错误提示；空列表时提供引导文案。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant U as "用户"
|
||
participant P as "引用记录页"
|
||
participant A as "API 客户端"
|
||
participant B as "后端"
|
||
U->>P : 打开页面
|
||
P->>A : 获取查询词列表
|
||
A->>B : 发起请求
|
||
B-->>A : 返回查询词数组
|
||
A-->>P : 设置查询词选项
|
||
U->>P : 设置筛选条件
|
||
P->>A : 拼接查询参数并请求引用记录
|
||
A->>B : 发起带参数的请求
|
||
B-->>A : 返回引用记录数组
|
||
A-->>P : 渲染表格
|
||
```
|
||
|
||
**图示来源**
|
||
- [frontend/app/(dashboard)/dashboard/citations/page.tsx:75-105](file://frontend/app/(dashboard)/dashboard/citations/page.tsx#L75-L105)
|
||
- [frontend/lib/api.ts:67-70](file://frontend/lib/api.ts#L67-L70)
|
||
|
||
**章节来源**
|
||
- [frontend/app/(dashboard)/dashboard/citations/page.tsx:1-294](file://frontend/app/(dashboard)/dashboard/citations/page.tsx#L1-L294)
|
||
- [frontend/components/ui/table.tsx:1-118](file://frontend/components/ui/table.tsx#L1-L118)
|
||
|
||
### 报告导出页面
|
||
- 页面职责
|
||
- 选择查询词后导出 CSV 报告，文件包含字段：关键词、平台、是否引用、引用位置、引用文本、竞争品牌、查询时间。
|
||
- 数据流
|
||
- 客户端加载查询词列表；点击导出时使用原生 fetch 下载文件并触发浏览器下载。
|
||
- 成功后显示成功提示，失败时显示错误信息。
|
||
- 用户体验
|
||
- 导出设置卡片与使用说明卡片并列展示，信息清晰。
|
||
- 自动命名文件，便于识别与归档。
|
||
- 错误边界
|
||
- 未选择查询词时阻止导出并提示；网络异常或后端错误统一捕获并展示。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant U as "用户"
|
||
participant P as "报告导出页"
|
||
participant A as "API 客户端"
|
||
participant B as "后端"
|
||
U->>P : 选择查询词并点击导出
|
||
alt 未选择查询词
|
||
P-->>U : 显示错误提示
|
||
else 已选择
|
||
P->>A : 调用导出接口携带令牌
|
||
A->>B : 发起带授权头的请求
|
||
B-->>A : 返回二进制文件
|
||
A-->>P : 触发浏览器下载
|
||
P-->>U : 显示成功提示
|
||
end
|
||
```
|
||
|
||
**图示来源**
|
||
- [frontend/app/(dashboard)/dashboard/reports/page.tsx:50-94](file://frontend/app/(dashboard)/dashboard/reports/page.tsx#L50-L94)
|
||
- [frontend/lib/api.ts:72-77](file://frontend/lib/api.ts#L72-L77)
|
||
|
||
**章节来源**
|
||
- [frontend/app/(dashboard)/dashboard/reports/page.tsx:1-200](file://frontend/app/(dashboard)/dashboard/reports/page.tsx#L1-L200)
|
||
|
||
### 设置页面
|
||
- 页面职责
|
||
- 展示用户信息与当前套餐状态；对比不同套餐的功能差异。
|
||
- 数据流
|
||
- 读取会话中的用户信息；根据当前计划键渲染对应套餐卡片。
|
||
- 用户体验
|
||
- 套餐卡片突出当前版本（MVP 阶段免费开放），提供功能清单与价格信息。
|
||
- 提供 MVP 阶段说明与后续升级提示。
|
||
- 错误边界
|
||
- 无网络或会话异常时，显示默认占位信息。
|
||
|
||
**章节来源**
|
||
- [frontend/app/(dashboard)/dashboard/settings/page.tsx:1-172](file://frontend/app/(dashboard)/dashboard/settings/page.tsx#L1-L172)
|
||
|
||
## 依赖关系分析
|
||
- 组件耦合
|
||
- 页面组件依赖 UI 组件库与工具函数，保持低耦合与高内聚。
|
||
- 仪表板与查询管理页面依赖 API 客户端；引用记录与报告导出页面同样依赖 API 客户端。
|
||
- 外部依赖
|
||
- 图表组件依赖 Recharts；对话框组件依赖 Radix UI；平台映射来自独立模块。
|
||
- 潜在循环依赖
|
||
- 未发现直接循环导入；布局与页面通过路由分组避免循环引用。
|
||
|
||
```mermaid
|
||
graph LR
|
||
api["API 客户端"] --> dashboard_page["仪表板页面"]
|
||
api --> queries_page["查询管理页面"]
|
||
api --> citations_page["引用记录页面"]
|
||
api --> reports_page["报告导出页面"]
|
||
table["表格组件"] --> queries_page
|
||
table --> citations_page
|
||
dialog["对话框组件"] --> queries_page
|
||
utils["工具函数"] --> api
|
||
utils --> table
|
||
utils --> dialog
|
||
platforms["平台映射"] --> queries_page
|
||
platforms --> citations_page
|
||
trend_chart["趋势图组件"] --> dashboard_page
|
||
platform_chart["平台对比图组件"] --> dashboard_page
|
||
```
|
||
|
||
**图示来源**
|
||
- [frontend/lib/api.ts:1-79](file://frontend/lib/api.ts#L1-L79)
|
||
- [frontend/app/(dashboard)/dashboard/page.tsx:1-227](file://frontend/app/(dashboard)/dashboard/page.tsx#L1-L227)
|
||
- [frontend/app/(dashboard)/dashboard/queries/page.tsx:1-526](file://frontend/app/(dashboard)/dashboard/queries/page.tsx#L1-L526)
|
||
- [frontend/app/(dashboard)/dashboard/citations/page.tsx:1-294](file://frontend/app/(dashboard)/dashboard/citations/page.tsx#L1-L294)
|
||
- [frontend/app/(dashboard)/dashboard/reports/page.tsx:1-200](file://frontend/app/(dashboard)/dashboard/reports/page.tsx#L1-L200)
|
||
- [frontend/components/ui/table.tsx:1-118](file://frontend/components/ui/table.tsx#L1-L118)
|
||
- [frontend/components/ui/dialog.tsx:1-123](file://frontend/components/ui/dialog.tsx#L1-L123)
|
||
- [frontend/lib/utils.ts:1-7](file://frontend/lib/utils.ts#L1-L7)
|
||
- [frontend/lib/platforms.ts:1-18](file://frontend/lib/platforms.ts#L1-L18)
|
||
- [frontend/components/charts/trend-chart.tsx:1-60](file://frontend/components/charts/trend-chart.tsx#L1-L60)
|
||
- [frontend/components/charts/platform-chart.tsx:1-68](file://frontend/components/charts/platform-chart.tsx#L1-L68)
|
||
|
||
**章节来源**
|
||
- [frontend/lib/api.ts:1-79](file://frontend/lib/api.ts#L1-L79)
|
||
- [frontend/lib/utils.ts:1-7](file://frontend/lib/utils.ts#L1-L7)
|
||
- [frontend/lib/platforms.ts:1-18](file://frontend/lib/platforms.ts#L1-L18)
|
||
|
||
## 性能考虑
|
||
- 懒加载策略
|
||
- 图表组件按需引入，避免首屏额外负担；页面组件在客户端首次渲染时才初始化。
|
||
- 数据获取策略
|
||
- 页面在会话令牌可用时再发起请求，减少无效网络调用；查询管理与引用记录页面在筛选条件变化时才重新请求。
|
||
- 状态管理
|
||
- 使用 React 本地状态管理加载、错误与交互状态，避免引入重型状态库。
|
||
- UI 渲染优化
|
||
- 表格组件提供横向滚动容器，避免大表格导致布局抖动；卡片与网格布局自适应不同屏幕尺寸。
|
||
- SEO 配置
|
||
- 根布局提供站点元数据（标题与描述），可在后续扩展 Open Graph、结构化数据等。
|
||
|
||
**章节来源**
|
||
- [frontend/app/layout.tsx:17-20](file://frontend/app/layout.tsx#L17-L20)
|
||
- [frontend/app/(dashboard)/dashboard/queries/page.tsx:104-121](file://frontend/app/(dashboard)/dashboard/queries/page.tsx#L104-L121)
|
||
- [frontend/app/(dashboard)/dashboard/citations/page.tsx:65-73](file://frontend/app/(dashboard)/dashboard/citations/page.tsx#L65-L73)
|
||
|
||
## 故障排除指南
|
||
- 登录态缺失
|
||
- 仪表板布局在服务端检查会话，未登录将重定向至登录页；客户端组件应始终检查会话令牌后再发起请求。
|
||
- 请求失败
|
||
- API 客户端对非 2xx 响应抛出错误，页面层捕获并显示错误提示；建议增加重试机制与更详细的错误码解析。
|
||
- 表单校验失败
|
||
- 查询管理页面对必填字段与平台选择进行校验，失败时显示错误提示；建议在提交前进行前端即时校验并聚焦首个错误项。
|
||
- 导出失败
|
||
- 报告导出页面对未选择查询词进行拦截；网络异常或后端错误统一捕获；建议在下载前预检接口可用性。
|
||
|
||
**章节来源**
|
||
- [frontend/app/(dashboard)/layout.tsx:12-15](file://frontend/app/(dashboard)/layout.tsx#L12-L15)
|
||
- [frontend/lib/api.ts:3-40](file://frontend/lib/api.ts#L3-L40)
|
||
- [frontend/app/(dashboard)/dashboard/queries/page.tsx:143-156](file://frontend/app/(dashboard)/dashboard/queries/page.tsx#L143-L156)
|
||
- [frontend/app/(dashboard)/dashboard/reports/page.tsx:50-94](file://frontend/app/(dashboard)/dashboard/reports/page.tsx#L50-L94)
|
||
|
||
## 结论
|
||
本设计以清晰的分层与职责划分实现了仪表板、查询管理、引用记录、报告导出与设置页面的组件化构建。通过统一的 API 客户端与 UI 组件库，提升了可维护性与一致性；结合会话驱动的数据获取与完善的错误边界处理，保障了用户体验与稳定性。所有页面组件均已实现并集成到Next.js应用架构中，包括数据总览、查询管理、引用记录、报告导出和设置页面的完整功能。后续可在 SEO、国际化、缓存策略与状态持久化方面进一步完善。
|
||
|
||
## 附录
|
||
- 开发规范与最佳实践
|
||
- 组件命名：使用语义化文件名与导出名称，如 `queries/page.tsx`。
|
||
- 状态管理：优先使用 React 本地状态；复杂场景再考虑集中式状态库。
|
||
- 错误处理：统一在页面层捕获并展示错误，避免错误冒泡到全局。
|
||
- 表单处理：在提交前进行前端校验，必要时提供实时校验反馈。
|
||
- 导航与路由：利用 Next.js 路由与分组，保持路径与页面职责一致。
|
||
- 性能：按需引入重型组件（如图表），避免首屏阻塞；合理使用加载状态与骨架屏。
|
||
- 可访问性：为按钮、对话框、表格等提供适当的 ARIA 属性与键盘导航支持。
|
||
- 样式：统一使用工具函数合并类名，遵循 Tailwind 命名约定。 |