hive-manage-v3/docs/superpowers/plans/phase-2-spec.md

在 /home/enzo/projects/hive-manage-v3/ 实现 Dashboard 增强（P0-3）。后端 API + 前端页面。

后端: Dashboard API

创建 backend/app/api/dashboard.py，所有路由需 require_auth。

1. GET /api/v1/dashboard/summary

返回聚合统计数据:

{
  "online_count": 12,
  "offline_count": 46,
  "total_profiles": 58,
  "running_tasks": 3,
  "cron_failures_today": 1,
  "updated_at": "2026-07-22T16:00:00"
}

数据来源: hermes CLI (hermes gateway status 解析) + Kanban 聚合 + Cron 统计。如需真实数据可先返回 Mock 数据（标注 TODO: replace with CLI）。

2. GET /api/v1/dashboard/health-distribution

返回健康分四级分布:

{
  "A": 22, "B": 18, "C": 10, "D": 8, "total": 58,
  "d_profiles": ["ops-engineer", "monitor", "visualizer", "hebo", "..."]
}

暂用占位数据，Phase 4 实现真实计算。

3. GET /api/v1/dashboard/gateway-trend

返回最近 24h Gateway 异常事件按小时聚合:

[
  {"hour": "2026-07-22T08:00", "restarts": 2, "feishu_disconnects": 1, "heartbeat_timeouts": 0},
  ...
]

暂用占位数据。

4. GET /api/v1/dashboard/kanban-summary

返回活跃看板概览:

[
  {"board": "europe-briefing", "running": "S4", "ready": "S5"},
  {"board": "tech-weekly", "running": "S1", "ready": null}
]

暂用占位数据。

5. GET /api/v1/dashboard/cron-recent

返回最近 Cron 执行记录:

[
  {"job": "taiwan-briefing", "status": "success", "time": "07:15"},
  {"job": "hindsight", "status": "failure", "time": "21:13"},
  {"job": "guangxi-donation", "status": "paused"}
]

暂用占位数据。

6. GET /api/v1/search?q=keyword

全局搜索: 搜索 Profile 名、任务名、Cron 名、事件关键词。返回分组结果:

{
  "profiles": [{"name": "gateway-monitor", "status": "online"}],
  "kanban_tasks": [{"title": "...", "column": "RUNNING"}],
  "cron_jobs": [{"job": "...", "status": "active"}],
  "events": [{"title": "...", "status": "active"}]
}

暂用占位数据，含模糊匹配逻辑。

前端: Dashboard 页面

修改 frontend/src/pages/DashboardPage.tsx:

统计卡片行 (4 列 grid)

• 在线 Gateway (绿色数值 + "↑ N vs 昨天")
• 离线 Gateway (红色数值 + "↓ N vs 昨天")
• 运行中任务 (蓝色数值)
• 今日 Cron 失败 (红色数值，失败>3 标红)

左侧: 蜂群健康分布

• 使用 Card 组件 + 自定义柱状图 (CSS bar chart)
• A(绿) B(蓝) C(黄) D(红) 四柱
• 点击柱跳转 /health?filter=X

右侧: Gateway 异常趋势 (24h)

• 使用 Timeline 组件，展示 24h 内事件点分布
• 图例: 🟢正常 🔴心跳超时 🟠飞书断连

底部: Kanban 概览 + Cron 最近执行

• 两列并排
• Kanban 概览: 看板名 + RUNNING 任务 + READY 任务
• Cron 最近: Job 名 + 状态(✅/❌/⏸) + 时间

搜索框

• 已在 Header 中通过 SearchBox 组件实现
• 输入关键词 → 调 /api/v1/search → 下拉面板分组展示
• 点击结果跳转对应页面

四态覆盖

• Loading: Skeleton (card 形状)
• Empty: "暂无数据"
• Error: 错误提示 + 重试按钮
• Normal: 数据正常展示

注册路由: 在 main.py 添加 from app.api import dashboard; app.include_router(dashboard.router, prefix="/api/v1")

完成后提交:

cd /home/enzo/projects/hive-manage-v3 && git add backend/app/api/dashboard.py backend/app/main.py frontend/src/pages/DashboardPage.tsx frontend/src/components/layout/Header.tsx && git commit -m "feat: Dashboard with summary cards, health distribution, gateway trend, global search"