22 KiB

Raw Permalink Blame History

页面组件设计

**本文档引用的文件** - [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)

更新摘要

变更内容

新增完整的仪表板页面组件系统实现
更新数据总览页、查询管理页、引用记录页和报告导出页的具体实现
完善图表组件的详细分析和使用说明
增强API客户端的接口文档和错误处理机制
优化页面级数据获取策略和状态管理

引言

本文件系统性梳理 GEO 平台前端页面组件的设计与实现，覆盖仪表板、查询管理、引用数据、报告导出与设置页面。内容包括页面布局与导航结构、用户体验流程、页面级数据获取策略、状态管理与错误边界处理、页面间导航逻辑与路由参数传递、页面生命周期管理、性能优化与懒加载策略、SEO 配置以及开发规范与最佳实践。

更新本次更新反映了应用的完整实现，所有页面组件均已开发完成并集成到Next.js应用架构中，包括数据总览、查询管理、引用记录、报告导出和设置页面的完整功能实现。

项目结构

前端采用 Next.js App Router 的分组路由模式，将认证相关页面置于 (auth) 分组，仪表板相关页面置于 (dashboard) 分组。根布局负责全局样式与 Provider 包装；仪表板布局负责权限校验、侧边栏与头部导航的统一渲染。

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"]

图示来源

章节来源

核心组件

布局与导航
- 根布局：定义站点元数据、字体变量与全局样式，注入 Provider。
- 仪表板布局：服务端会话校验，未登录重定向至登录页；渲染侧边栏与头部，承载主内容区域。
- 头部组件：展示用户名与登出按钮，使用客户端会话状态。
- 侧边栏组件：基于路径高亮当前菜单项，提供统一导航入口。
UI 组件库
- 表格组件：封装响应式表格容器与表头/体/行/单元格等基础结构。
- 对话框组件：基于 Radix UI 实现模态对话框，支持触发器、内容、标题与描述。
图表组件
- 趋势图组件：基于 Recharts 实现折线图，展示过去30天引用趋势。
- 平台对比图：基于 Recharts 实现柱状图，展示各平台引用率对比。
工具与常量
- 平台映射：提供平台键值到中文名称的映射与平台选项列表。
- 工具函数：类名合并工具，用于组合 Tailwind 类。
- API 客户端：统一封装鉴权头、错误处理与各模块接口（认证、查询、引用、报告）。

更新新增了图表组件的详细实现分析，包括数据结构定义、响应式容器配置和交互功能。

章节来源

架构概览

整体采用"布局层 + 页面层 + 组件层 + 工具层"的分层设计。页面层通过客户端会话获取令牌，调用 API 客户端进行数据拉取与写入；UI 组件层提供可复用的基础控件；工具层提供通用能力（类名合并、平台映射、API 封装）；图表组件独立封装，按需渲染。

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

图示来源

详细组件分析

仪表板页面（数据总览）

页面职责
- 展示用户关键指标卡片（总查询次数、总引用次数、引用率、平均引用位置）。
- 展示过去30天引用趋势折线图与平台引用率对比柱状图。
数据流
- 客户端从会话中获取访问令牌，调用引用统计接口获取聚合数据。
- 加载状态、错误状态与空数据提示分别处理。
用户体验
- 卡片式布局，响应式网格适配不同屏幕尺寸。
- 图表组件使用响应式容器，确保在小屏设备上正常显示。
错误边界
- 请求失败时显示错误提示与刷新按钮；加载中显示旋转指示器。

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

图示来源

章节来源

查询管理页面

页面职责
- 列表展示查询词，支持新增、编辑、删除与"立即查询"操作。
- 提供平台多选、频率选择、品牌别名输入等配置项。
数据流
- 客户端加载查询词列表；新增/编辑通过 PUT/POST 写入；删除通过 DELETE。
- 表单校验：关键词、目标品牌必填，至少选择一个平台。
用户体验
- 使用对话框承载表单，支持取消与保存；删除操作二次确认。
- 列表支持平台徽标展示与状态徽章。
错误边界
- 表单校验失败与网络错误分别提示；保存与删除过程禁用按钮并显示加载状态。

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

图示来源

章节来源

引用记录页面

页面职责
- 展示跨平台的引用检测结果，支持按查询词、平台、日期范围筛选。
数据流
- 客户端加载查询词下拉选项与引用记录列表；筛选条件通过查询字符串拼接。
- 支持重置筛选条件并重新加载。
用户体验
- 筛选区采用栅格布局，适配移动端；表格支持横向滚动。
- 引用状态以图标与颜色区分，引用位置与文本片段清晰展示。
错误边界
- 加载失败时显示错误提示；空列表时提供引导文案。

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 : 渲染表格

图示来源

章节来源

报告导出页面

页面职责
- 选择查询词后导出 CSV 报告，文件包含字段：关键词、平台、是否引用、引用位置、引用文本、竞争品牌、查询时间。
数据流
- 客户端加载查询词列表；点击导出时使用原生 fetch 下载文件并触发浏览器下载。
- 成功后显示成功提示，失败时显示错误信息。
用户体验
- 导出设置卡片与使用说明卡片并列展示，信息清晰。
- 自动命名文件，便于识别与归档。
错误边界
- 未选择查询词时阻止导出并提示；网络异常或后端错误统一捕获并展示。

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:1-200

设置页面

页面职责
- 展示用户信息与当前套餐状态；对比不同套餐的功能差异。
数据流
- 读取会话中的用户信息；根据当前计划键渲染对应套餐卡片。
用户体验
- 套餐卡片突出当前版本（MVP 阶段免费开放），提供功能清单与价格信息。
- 提供 MVP 阶段说明与后续升级提示。
错误边界
- 无网络或会话异常时，显示默认占位信息。

章节来源

frontend/app/(dashboard)/dashboard/settings/page.tsx:1-172

依赖关系分析

组件耦合
- 页面组件依赖 UI 组件库与工具函数，保持低耦合与高内聚。
- 仪表板与查询管理页面依赖 API 客户端；引用记录与报告导出页面同样依赖 API 客户端。
外部依赖
- 图表组件依赖 Recharts；对话框组件依赖 Radix UI；平台映射来自独立模块。
潜在循环依赖
- 未发现直接循环导入；布局与页面通过路由分组避免循环引用。

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

图示来源

章节来源

性能考虑

懒加载策略
- 图表组件按需引入，避免首屏额外负担；页面组件在客户端首次渲染时才初始化。
数据获取策略
- 页面在会话令牌可用时再发起请求，减少无效网络调用；查询管理与引用记录页面在筛选条件变化时才重新请求。
状态管理
- 使用 React 本地状态管理加载、错误与交互状态，避免引入重型状态库。
UI 渲染优化
- 表格组件提供横向滚动容器，避免大表格导致布局抖动；卡片与网格布局自适应不同屏幕尺寸。
SEO 配置
- 根布局提供站点元数据（标题与描述），可在后续扩展 Open Graph、结构化数据等。

章节来源

故障排除指南

登录态缺失
- 仪表板布局在服务端检查会话，未登录将重定向至登录页；客户端组件应始终检查会话令牌后再发起请求。
请求失败
- API 客户端对非 2xx 响应抛出错误，页面层捕获并显示错误提示；建议增加重试机制与更详细的错误码解析。
表单校验失败
- 查询管理页面对必填字段与平台选择进行校验，失败时显示错误提示；建议在提交前进行前端即时校验并聚焦首个错误项。
导出失败
- 报告导出页面对未选择查询词进行拦截；网络异常或后端错误统一捕获；建议在下载前预检接口可用性。

章节来源

结论

本设计以清晰的分层与职责划分实现了仪表板、查询管理、引用记录、报告导出与设置页面的组件化构建。通过统一的 API 客户端与 UI 组件库，提升了可维护性与一致性；结合会话驱动的数据获取与完善的错误边界处理，保障了用户体验与稳定性。所有页面组件均已实现并集成到Next.js应用架构中，包括数据总览、查询管理、引用记录、报告导出和设置页面的完整功能。后续可在 SEO、国际化、缓存策略与状态持久化方面进一步完善。

附录

开发规范与最佳实践
- 组件命名：使用语义化文件名与导出名称，如 queries/page.tsx。
- 状态管理：优先使用 React 本地状态；复杂场景再考虑集中式状态库。
- 错误处理：统一在页面层捕获并展示错误，避免错误冒泡到全局。
- 表单处理：在提交前进行前端校验，必要时提供实时校验反馈。
- 导航与路由：利用 Next.js 路由与分组，保持路径与页面职责一致。
- 性能：按需引入重型组件（如图表），避免首屏阻塞；合理使用加载状态与骨架屏。
- 可访问性：为按钮、对话框、表格等提供适当的 ARIA 属性与键盘导航支持。
- 样式：统一使用工具函数合并类名，遵循 Tailwind 命名约定。

22 KiB Raw Permalink Blame History Unescape Escape

页面组件设计

更新摘要

目录

引言

项目结构

核心组件

架构概览

详细组件分析

仪表板页面（数据总览）

查询管理页面

引用记录页面

报告导出页面

设置页面

依赖关系分析

性能考虑

故障排除指南

结论

附录

22 KiB

Raw Permalink Blame History