147 lines
7.4 KiB
Markdown
147 lines
7.4 KiB
Markdown
---
|
||
date: 2026-06-01
|
||
topic: 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:** 用户进入监测页面
|
||
1. 页面加载品牌监测记录列表（R1）
|
||
2. 用户点击某条记录 → 展开变化报告详情（R2）
|
||
3. 用户点击"立即检测" → 触发检测（R3）→ 按钮变为 loading → 检测完成后刷新记录
|
||
4. 用户切换监测状态 active/paused（R4）
|
||
|
||
**Covers R1, R2, R3, R4.**
|
||
|
||
### F2. 竞品分析
|
||
|
||
**Trigger:** 用户进入竞品分析页面
|
||
1. 页面加载品牌竞品列表（R6）
|
||
2. 用户点击"添加竞品" → 搜索或从推荐列表选择（R9）→ 添加成功
|
||
3. 用户点击"开始分析" → 选择分析类型 → 执行分析（R7）→ 展示雷达图 + 差距评分（R8）
|
||
4. 用户点击"重新分析" → 刷新分析结果
|
||
|
||
**Covers R6, R7, R8, R9.**
|
||
|
||
### F3. 健康评分查看
|
||
|
||
**Trigger:** 用户进入健康评分页面
|
||
1. 页面加载 V2 五维度评分仪表盘（R11）
|
||
2. 用户点击"竞品对比" → 展示雷达图（R12）
|
||
3. 用户点击"历史趋势" → 展示评分折线图（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 客户端
|