geo/2026-06-01-geo-frontend-visualization-requirements.md at main

7.4 KiB

Raw Permalink Blame History

date	topic
2026-06-01	geo-frontend-visualization

Summary

为 GEO 平台已有的完整后端 API 补建前端可视化页面，分三批交付：P0 修复监测页面 + 新建竞品分析页面，P1 引用统计可视化 + 健康评分页面 + 检测任务管理 UI，P2 报告导出入口 + 公开评分落地页 + Agent 配置 UI + 趋势/Schema 页面。可视化优先——先让用户看到数据价值，再补操作闭环。

Problem Frame

GEO 平台后端 API 已基本完整（8 个 Agent、5 大服务模块、30+ 端点），但前端存在多处功能断裂：监测页面展示的是告警而非监测记录（5 个监测 API 端点完全未被使用），竞品分析后端完整（5 种分析类型 + LLM 推荐 + 差距评分）却无前端页面，引用统计、健康评分、检测任务等 API 也缺乏前端对接。用户在 onboarding 流程中看到健康评分，进入 Dashboard 后却找不到对应页面，核心价值无法被感知。

Key Decisions

可视化优先于操作 — 先让用户看到品牌监测数据、竞品对比图表、引用统计趋势，证明数据价值；触发检测、创建任务等操作能力后续补全。这降低了首批交付的复杂度，同时验证用户是否真的需要这些数据。

监测页面修复而非新建 — 当前 monitoring 页面展示告警，但告警功能本身有独立价值。将监测记录作为 monitoring 页面的主 Tab，告警作为子 Tab，避免功能割裂。

复用现有图表库 — 前端已有 recharts 依赖（Dashboard 页面使用），竞品雷达图、引用趋势图等复用 recharts 而非引入新库。

Requirements

P0: 核心可视化闭环

R1. 监测页面展示品牌监测记录列表，调用 /api/v1/monitoring/brand/{brand_id} 获取数据，每条记录显示监测平台、上次检测时间、变化类型（positive/negative/neutral）、变化摘要

R2. 监测记录详情展示变化报告，调用 /{record_id}/report 获取，包含变化指标对比（引用量、情感、排名）和 AI 建议

R3. 监测页面支持手动触发检测，调用 /{record_id}/check，触发后显示检测进度状态

R4. 监测状态管理（active/paused/completed），调用 /{record_id}/status 更新

R5. 告警功能保留为 monitoring 页面的子 Tab，不删除现有告警逻辑

R6. 竞品分析独立页面，展示品牌竞品列表，调用 /{brand_id}/competitors/ 获取，支持添加（上限 5 个）和删除

R7. 竞品对比可视化，调用 /competitor/analyze 执行分析，以雷达图展示品牌与竞品在 5 个维度的差距

R8. 竞品差距评分汇总，调用 /competitor/brand/{brand_id}/gap-summary 获取，以评分卡片形式展示

R9. 竞品推荐功能，调用 /{brand_id}/competitors/recommendations/ 获取 LLM 推荐的竞品列表

P1: 数据深度可视化

R10. 引用统计可视化，调用 /api/v1/citations/stats 获取数据，展示引用率、平均位置、平台分布饼图、30 天趋势折线图

R11. 健康评分独立页面，调用 /{brand_id}/score/ 获取 V2 五维度评分，以仪表盘 + 维度卡片形式展示

R12. 品牌与竞品对比，调用 /{brand_id}/compare/ 获取雷达图数据，在健康评分页面中展示

R13. 评分历史趋势，调用 /{brand_id}/score/history/ 获取，以折线图展示评分变化

R14. 检测任务管理 UI，调用 /api/v1/detection/tasks CRUD，展示任务列表、创建/编辑/删除任务、手动触发检测

R15. Dashboard 主页 Agent 活动区域替换占位内容，展示最近 Agent 执行记录摘要

P2: 体验补全

R16. 引用页面添加 CSV/PDF 导出按钮，调用后端已有导出端点

R17. 报告页面导出按钮，调用 /api/v1/reports/export/csv 和 /pdf

R18. 公开健康评分落地页，调用 /api/v1/public/health-score，作为营销获客入口，无需登录即可查看品牌 3 维度评分

R19. Agent 配置管理 UI，调用 /{agent_name}/config GET/PUT，展示和修改 Agent 参数

R20. 趋势洞察页面，调用 /api/v1/trends 获取趋势分析和洞察列表

R21. Schema 建议页面，调用 /api/v1/schema 获取和管理 Schema 建议

Key Flows

F1. 监测记录查看与检测

Trigger: 用户进入监测页面

页面加载品牌监测记录列表（R1）
用户点击某条记录 → 展开变化报告详情（R2）
用户点击"立即检测" → 触发检测（R3）→ 按钮变为 loading → 检测完成后刷新记录
用户切换监测状态 active/paused（R4）

Covers R1, R2, R3, R4.

F2. 竞品分析

Trigger: 用户进入竞品分析页面

页面加载品牌竞品列表（R6）
用户点击"添加竞品" → 搜索或从推荐列表选择（R9）→ 添加成功
用户点击"开始分析" → 选择分析类型 → 执行分析（R7）→ 展示雷达图 + 差距评分（R8）
用户点击"重新分析" → 刷新分析结果

Covers R6, R7, R8, R9.

F3. 健康评分查看

Trigger: 用户进入健康评分页面

页面加载 V2 五维度评分仪表盘（R11）
用户点击"竞品对比" → 展示雷达图（R12）
用户点击"历史趋势" → 展示评分折线图（R13）

Covers R11, R12, R13.

Scope Boundaries

Deferred for later:

监测任务创建 UI（当前仅展示已有记录和手动触发，创建新监测任务的操作能力后续补全）
Agent 手动创建任务 UI（当前仅展示执行记录和配置，手动创建任务的操作能力后续补全）
内容编辑器深度优化和版本对比
国际化（i18n）改造

Outside this product's identity:

后端 API 新增或修改（后端已完整，本次仅做前端对接）
实时数据推送（WebSocket）——当前使用轮询刷新即可
移动端适配——当前仅考虑桌面端

Dependencies / Assumptions

后端 API 端点已完整且可用（基于代码扫描确认，未做运行时验证）
前端 recharts 库已安装，可复用于所有图表
前端 fetchWithAuth 统一 API 客户端已就绪，所有新页面使用该客户端
Docker 服务已部署且数据库已迁移（Plan 005 已完成）
各 API 返回的数据结构与前端类型定义一致

Outstanding Questions

Resolve Before Planning:

监测记录的"创建监测任务"入口放在哪里？Onboarding Step3 已创建品牌并选择平台，是否在品牌创建后自动创建监测任务？

Deferred to Planning:

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

Sources / Research

backend/app/api/v1/monitoring.py — 5 个监测端点
backend/app/api/v1/competitors.py + backend/app/api/v1/competitor.py — 竞品管理 + 分析端点
backend/app/api/v1/citations.py — 引用记录 + 统计端点
backend/app/api/v1/scoring.py — V2 五维度评分 + 竞品对比 + 历史趋势
backend/app/api/v1/detection.py — 检测任务 CRUD + 触发
backend/app/api/v1/agents.py — Agent 配置 + 任务管理
backend/app/api/v1/trends.py — 趋势洞察
backend/app/api/v1/schema_suggestions.py — Schema 建议
frontend/app/(dashboard)/dashboard/monitoring/page.tsx — 当前告警页面（需改造）
frontend/app/(dashboard)/dashboard/citations/page.tsx — 引用列表页面（需增加统计）
frontend/lib/api/client.ts — 统一 API 客户端

7.4 KiB Raw Permalink Blame History Unescape Escape