fischer
/
geo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
geo/docs/plans/2026-06-01-006-feat-geo-fro...

15 KiB
Raw Blame History

date status origin
2026-06-01 active docs/brainstorms/2026-06-01-geo-frontend-visualization-requirements.md

Summary

为 GEO 平台已有后端 API 补建前端可视化页面，分三批交付：P0 监测页面改造 + 竞品分析新建，P1 引用统计 + 健康评分 + 检测任务 + Dashboard Agent 区域，P2 导出入口 + 公开评分落地页 + Agent 配置 + 趋势/Schema 页面。可视化优先，复用 recharts + 现有 CompetitorRadarChart 组件。

Problem Frame

后端 API 完整但前端多处断裂：监测页面展示告警而非监测记录，竞品分析无前端，引用统计/健康评分/检测任务等 API 未对接。用户在 Onboarding 看到健康评分后进入 Dashboard 却找不到对应页面。

Requirements

P0 核心可视化闭环: R1–R9 P1 数据深度可视化: R10–R15 P2 体验补全: R16–R21

Full requirements in origin document.

Key Technical Decisions

KTD1. 监测页面改造为主 Tab 模式 — 监测记录为主 Tab，告警为子 Tab。替换侧边栏"数据监测"入口（原 /dashboard/analytics）指向 /dashboard/monitoring。保留现有告警逻辑不删除。

KTD2. 竞品分析独立页面 — 新建 /dashboard/competitors 页面，复用现有 CompetitorRadarChart 组件（components/charts/CompetitorRadarChart.tsx）。侧边栏新增"竞品分析"导航项。

KTD3. 复用 recharts + 现有图表组件 — 不引入新图表库。引用趋势用 trend-chart.tsx，平台分布用 platform-chart.tsx，竞品雷达图用 CompetitorRadarChart.tsx。健康评分仪表盘用 recharts PieChart 半圆实现。

KTD4. 监测任务由 Onboarding 自动创建 — 在 Onboarding Step3 创建品牌后自动调用 monitoringApi.createTask，不在监测页面提供手动创建 UI。

KTD5. API 模块复用现有模式 — 新增 lib/api/competitor.ts、lib/api/scoring.ts、lib/api/detection.ts、lib/api/trends.ts、lib/api/schema-suggestions.ts，遵循 fetchWithAuth + typed interfaces + const object export 模式。已有 monitoring.ts 和 alerts.ts 直接复用。

Implementation Units

U1. 监测页面改造

Goal: 将 monitoring 页面从纯告警改为监测记录 + 告警双 Tab，监测记录为主 Tab，对接 /api/v1/monitoring 的 5 个端点。

Requirements: R1, R2, R3, R4, R5

Dependencies: none

Files:

  • frontend/app/(dashboard)/dashboard/monitoring/page.tsx — 重写
  • frontend/app/(dashboard)/layout.tsx — 替换"数据监测"导航项 href

Approach:

  • 页面顶部使用 shadcn Tabs 组件，Tab1"监测记录"，Tab2"告警通知"
  • Tab1 调用 monitoringApi.getBrandRecords(token, brandId) 获取记录列表
  • 每条记录展示：平台、上次检测时间、变化类型 Badge（positive=绿/negative=红/neutral=灰）、变化摘要
  • 点击记录展开详情：调用 monitoringApi.getReport(token, recordId) 获取变化报告，展示指标对比和建议
  • "立即检测"按钮调用 monitoringApi.triggerCheck(token, recordId)，loading 状态后刷新列表
  • 状态切换（active/paused）调用 monitoringApi.updateStatus(token, recordId, status)
  • Tab2 保留现有告警逻辑，提取为 AlertsTab 子组件
  • 侧边栏 NAV_GROUPS 中 analytics 项的 href 从 /dashboard/analytics 改为 /dashboard/monitoring，label 改为"品牌监测"

Patterns to follow: citations/page.tsx 的 useApi + useState 模式；api-states.tsx 的 LoadingState/ErrorState/EmptyState

Test scenarios:

  • 监测记录列表加载并展示变化类型 Badge
  • 点击记录展开变化报告详情
  • 点击"立即检测"触发检测并刷新列表
  • 切换监测状态 active/paused
  • 告警 Tab 保留现有功能不受影响

Verification: 页面加载显示监测记录 Tab 为默认，告警 Tab 可切换，监测 API 被正确调用

U2. 竞品分析页面

Goal: 新建竞品分析页面，展示竞品列表、雷达图对比、差距评分、LLM 推荐。

Requirements: R6, R7, R8, R9

Dependencies: none

Files:

  • frontend/app/(dashboard)/dashboard/competitors/page.tsx — 新建
  • frontend/lib/api/competitor.ts — 新建
  • frontend/app/(dashboard)/layout.tsx — 新增"竞品分析"导航项
  • frontend/lib/api/index.ts — 添加 competitor 导出

Approach:

  • 新建 lib/api/competitor.ts，封装 6 个端点：竞品 CRUD、推荐、分析、差距评分、洞察详情
  • 页面布局：顶部竞品列表卡片 + 添加竞品按钮，中部雷达图对比区，底部差距评分卡片
  • 竞品列表调用 GET /{brand_id}/competitors/，添加调用 POST /{brand_id}/competitors/（上限 5 个）
  • 添加竞品时展示推荐列表：调用 GET /{brand_id}/competitors/recommendations/
  • 雷达图复用 CompetitorRadarChart 组件，数据来自 POST /competitor/analyze
  • 差距评分调用 GET /competitor/brand/{brand_id}/gap-summary
  • 侧边栏新增导航项：{ id: "competitors", label: "竞品分析", href: "/dashboard/competitors", icon: <Swords /> }

Patterns to follow: CompetitorRadarChart.tsx 已有雷达图实现；citations/page.tsx 的列表 + 详情模式

Test scenarios:

  • 竞品列表加载并展示
  • 添加竞品（从推荐列表选择 + 手动输入）
  • 删除竞品（上限 5 个校验）
  • 执行竞品分析并展示雷达图
  • 差距评分卡片展示

Verification: 页面加载显示竞品列表，雷达图可交互，差距评分正确展示

U3. Onboarding 自动创建监测任务

Goal: 在 Onboarding Step3 创建品牌后自动调用 monitoringApi.createTask 创建监测任务。

Requirements: KTD4

Dependencies: U1

Files:

  • frontend/app/(dashboard)/onboarding/page.tsx — 修改 handleStep3Next/handleStep3Skip
  • frontend/lib/hooks/use-onboarding-data.ts — 添加 createMonitoringTask 方法

Approach:

  • 在 useOnboardingData hook 中添加 createMonitoringTask 方法，调用 monitoringApi.createTask
  • 在 handleStep3Next 和 handleStep3Skip 中，品牌创建成功后立即调用 createMonitoringTask
  • 传入品牌 ID 和选择的平台列表，频率使用用户选择的 frequency
  • 监测任务创建失败不阻塞 onboarding 流程（静默失败，console.warn 级别）

Patterns to follow: useOnboardingData hook 的 createBrand 模式

Test scenarios:

  • Onboarding Step3 完成后自动创建监测任务
  • 监测任务创建失败不阻塞 onboarding

Verification: 完成 onboarding 后在监测页面能看到自动创建的监测记录

U4. 引用统计可视化

Goal: 在引用页面添加统计图表区域，展示引用率、平台分布、30 天趋势。

Requirements: R10

Dependencies: none

Files:

  • frontend/app/(dashboard)/dashboard/citations/page.tsx — 修改
  • frontend/lib/api/citations.ts — 新建或扩展

Approach:

  • 新建 lib/api/citations.ts，封装 getCitationStats 端点
  • 在引用页面顶部添加统计区域（3 个统计卡片 + 2 个图表）
  • 统计卡片：引用率、平均位置、总引用数
  • 图表 1：平台分布饼图（recharts PieChart），复用 analytics 页面的饼图模式
  • 图表 2：30 天趋势折线图，复用 trend-chart.tsx 组件
  • 统计数据调用 GET /api/v1/citations/stats

Patterns to follow: trend-chart.tsx 折线图；usage/page.tsx 饼图模式；api-states.tsx 加载状态

Test scenarios:

  • 统计卡片正确展示引用率、平均位置、总数
  • 平台分布饼图按平台着色
  • 30 天趋势折线图展示变化曲线
  • 无数据时展示空状态

Verification: 引用页面顶部展示统计图表，数据与后端 API 一致

U5. 健康评分页面

Goal: 新建健康评分页面，展示 V2 五维度评分仪表盘、竞品对比雷达图、评分历史趋势。

Requirements: R11, R12, R13

Dependencies: U2（复用 CompetitorRadarChart）

Files:

  • frontend/app/(dashboard)/dashboard/health-score/page.tsx — 新建
  • frontend/lib/api/scoring.ts — 新建
  • frontend/app/(dashboard)/layout.tsx — 新增"健康评分"导航项
  • frontend/lib/api/index.ts — 添加 scoring 导出

Approach:

  • 新建 lib/api/scoring.ts，封装 4 个端点：V2 评分、V1 兼容、历史趋势、竞品对比
  • 页面布局：顶部总评分仪表盘（recharts PieChart 半圆），中部 5 维度评分卡片，底部 Tab 切换（竞品对比 / 历史趋势）
  • 总评分仪表盘：recharts PieChart 两个弧形（已得分 + 剩余），中心显示分数
  • 5 维度卡片：提及率、推荐排名、情感倾向、引用质量、竞品对比，每项显示分数 + 进度条
  • 竞品对比 Tab：复用 CompetitorRadarChart，数据来自 GET /{brand_id}/compare/
  • 历史趋势 Tab：复用 trend-chart.tsx，数据来自 GET /{brand_id}/score/history/
  • 侧边栏新增导航项：{ id: "health-score", label: "健康评分", href: "/dashboard/health-score", icon: <Heart /> }

Patterns to follow: CompetitorRadarChart.tsx；trend-chart.tsx；onboarding/Step0HealthScore.tsx 的评分展示模式

Test scenarios:

  • 总评分仪表盘正确显示分数和弧形
  • 5 维度卡片展示各维度分数和进度条
  • 竞品对比雷达图展示品牌与竞品对比
  • 历史趋势折线图展示评分变化
  • 无品牌时展示空状态引导

Verification: 页面加载展示完整评分仪表盘，图表交互正常

U6. 检测任务管理 + Dashboard Agent 区域

Goal: 新建检测任务管理页面，替换 Dashboard 主页 Agent 活动占位内容。

Requirements: R14, R15

Dependencies: none

Files:

  • frontend/app/(dashboard)/dashboard/detection/page.tsx — 新建
  • frontend/lib/api/detection.ts — 新建
  • frontend/app/(dashboard)/dashboard/page.tsx — 修改 Agent 活动区域
  • frontend/app/(dashboard)/layout.tsx — 新增"检测任务"导航项
  • frontend/lib/api/index.ts — 添加 detection 导出

Approach:

  • 新建 lib/api/detection.ts，封装检测任务 CRUD + 触发端点
  • 检测任务页面：任务列表（Table）+ 创建任务 Dialog + 手动触发按钮
  • 任务列表展示：查询词、平台、频率、状态、上次运行时间、下次运行时间
  • 创建任务 Dialog：选择查询词、平台、频率
  • 手动触发调用 POST /tasks/{task_id}/trigger
  • Dashboard 主页 Agent 活动区域：调用 agentsApi.listTasks(token, {limit: 5}) 获取最近 5 条执行记录，展示为紧凑列表（任务类型 + 状态 Badge + 耗时 + 时间）
  • 侧边栏新增导航项：{ id: "detection", label: "检测任务", href: "/dashboard/detection", icon: <ScanSearch /> }

Patterns to follow: queries/page.tsx 的 CRUD 模式；agents/page.tsx 的任务列表模式

Test scenarios:

  • 检测任务列表加载并展示
  • 创建新检测任务
  • 手动触发检测
  • 删除检测任务
  • Dashboard Agent 区域展示最近执行记录

Verification: 检测任务页面 CRUD 正常，Dashboard Agent 区域不再显示"功能开发中"

U7. P2 体验补全

Goal: 添加导出入口、公开评分落地页、Agent 配置 UI、趋势/Schema 页面。

Requirements: R16, R17, R18, R19, R20, R21

Dependencies: U4, U5

Files:

  • frontend/app/(dashboard)/dashboard/citations/page.tsx — 添加导出按钮
  • frontend/app/(dashboard)/dashboard/reports/page.tsx — 添加导出按钮
  • frontend/app/(public)/health-score/page.tsx — 新建
  • frontend/app/(dashboard)/dashboard/agents/page.tsx — 添加配置面板
  • frontend/app/(dashboard)/dashboard/trends/page.tsx — 新建
  • frontend/app/(dashboard)/dashboard/schema/page.tsx — 新建
  • frontend/lib/api/trends.ts — 新建
  • frontend/lib/api/schema-suggestions.ts — 新建
  • frontend/app/(dashboard)/layout.tsx — 添加新导航项
  • frontend/lib/api/index.ts — 添加新模块导出

Approach:

  • 引用页面添加"导出 CSV"和"导出 PDF"按钮，调用 fetchWithAuth blob 模式
  • 报告页面添加导出按钮（已有逻辑，确认按钮存在且可用）
  • 公开健康评分落地页：无需登录，输入品牌名调用 /api/v1/public/health-score，展示 3 维度评分 + "注册查看完整报告" CTA
  • Agent 配置面板：在 agents 页面添加配置 Dialog，调用 GET/PUT /{agent_name}/config
  • 趋势洞察页面：调用 /api/v1/trends 获取洞察列表和趋势摘要
  • Schema 建议页面：调用 /api/v1/schema 获取和管理建议

Patterns to follow: reports.ts 的 blob 导出模式；Step0HealthScore.tsx 的公开评分展示

Test scenarios:

  • 引用页面 CSV/PDF 导出按钮可用
  • 公开评分页面无需登录即可查看
  • Agent 配置 Dialog 展示和修改配置
  • 趋势洞察页面展示洞察列表
  • Schema 建议页面展示建议列表

Verification: 所有 P2 功能页面可访问且 API 对接正确

Scope Boundaries

Deferred for later:

  • 监测任务手动创建 UI（Onboarding 自动创建已覆盖）
  • Agent 手动创建任务 UI
  • 内容编辑器深度优化和版本对比
  • 国际化（i18n）改造
  • 实时数据推送（WebSocket）

Outside this product's identity:

  • 后端 API 新增或修改
  • 移动端适配

Open Questions

Deferred to implementation:

  • 竞品雷达图的具体维度映射（后端 5 种分析类型如何映射到雷达图轴）
  • 公开健康评分落地页的 URL 路由和 SEO 策略
  • Dashboard Agent 区域的数据刷新策略

Risks & Dependencies

  • 后端 API 数据格式未验证 — 计划基于代码扫描，未做运行时验证。实现时可能需要适配实际响应格式
  • 品牌 ID 获取 — 多个页面需要当前用户的品牌 ID，需确认获取方式（useApi 调用 brands 端点 or useUserStore）
  • recharts 雷达图数据格式 — CompetitorRadarChart 已有实现，但竞品分析 API 返回格式可能需要适配

Sources & Research

  • frontend/app/(dashboard)/dashboard/citations/page.tsx — 页面模式参考
  • frontend/lib/api/client.ts — fetchWithAuth 统一客户端
  • frontend/lib/api/monitoring.ts — 已有监测 API 模块（完全未使用）
  • frontend/lib/api/alerts.ts — 告警 API 模块
  • frontend/components/charts/CompetitorRadarChart.tsx — 已有雷达图组件
  • frontend/components/charts/trend-chart.tsx — 已有趋势图组件
  • frontend/components/charts/platform-chart.tsx — 已有平台分布图组件
  • frontend/components/ui/api-states.tsx — 共享加载/错误/空状态组件
  • frontend/app/(dashboard)/layout.tsx — 侧边栏导航配置
  • backend/app/api/v1/monitoring.py — 监测端点
  • backend/app/api/v1/competitors.py + backend/app/api/v1/competitor.py — 竞品端点
  • backend/app/api/v1/citations.py — 引用统计端点
  • backend/app/api/v1/scoring.py — 评分端点
  • backend/app/api/v1/detection.py — 检测任务端点