73 lines
4.3 KiB
JSON
73 lines
4.3 KiB
JSON
{
|
|
"module": "health",
|
|
"version": "1.0",
|
|
"purpose": "Dashboard 'F 健康' tab 展示系统整体健康状态，三層結構：系统概览 → 异常服务 → 全部服务(按功能分层)。",
|
|
"ui_location": "Principles 菜单 → F 健康 tab",
|
|
|
|
"human_help": {
|
|
"title": "F 健康 — 系统健康",
|
|
"description": [
|
|
"本 tab 展示系统全部服务的运行健康状态，采用三層結構方便快速定位问题：",
|
|
"第一層「系统概览」：整体状态信号（正常/部分异常/严重异常）+ 数字摘要",
|
|
"第二層「异常服务」：只高亮显示有问题的服务，附带影响描述",
|
|
"第三層「全部服务」：按功能分层列出所有服务及其运行状态",
|
|
"底部「定时任务」区域展示 Windows Scheduled Tasks 状态。"
|
|
],
|
|
"usage": [
|
|
"1. 先看顶部概览信号（绿色=正常，黄色=部分异常，红色=严重异常）",
|
|
"2. 如果概览显示异常，直接看「异常服务」区域了解具体哪个服务挂了及影响范围",
|
|
"3. 需要查看全部服务状态时，展开「全部服务」按层浏览",
|
|
"4. 底部定时任务区域检查计划任务是否正常运行"
|
|
],
|
|
"troubleshooting": [
|
|
"如果无法加载数据：检查 dashboard.py (5803) 是否运行",
|
|
"如果部分服务显示 down 但实际在运行：检查该服务的 health check 端点",
|
|
"如果定时任务都显示 not_deployed：这些任务是 Windows 端配置的，246 上无法检测"
|
|
],
|
|
"related": "K 测试 tab 有各模块的细化测试结果，G 规范定义服务应满足的规范要求"
|
|
},
|
|
|
|
"ai_spec": {
|
|
"apis": [
|
|
{"method": "GET", "path": "/api/services", "returns": "{ok, services[{name,type,port,health{ok},watchdog,depends_on}]} — 运行服务列表含健康检查"},
|
|
{"method": "GET", "path": "/api/expected", "returns": "{expected[{name,port,expected,critical}], actual{name:status}} — 期望状态矩阵"},
|
|
{"method": "GET", "path": "/api/monitor", "returns": "{tier1{summary{ok,total}}, tier2{summary{ok,total}}, tasks[{name,status}]} — 监控聚合"}
|
|
],
|
|
"dependencies": [
|
|
"/api/services 依赖各个服务的 HTTP health check 端点",
|
|
"/api/expected 依赖 port_open()、schtasks、pgrep 等检测方法",
|
|
"/api/monitor 源自 dashboard.py 定时执行的健康检查任务"
|
|
],
|
|
"architecture": {
|
|
"three_layer_design": "Layer1=summary cards(status+nums), Layer2=issues only(highlight with impact text), Layer3=all services grouped by layer(通信层/AI网关/辅助服务/定时任务)"
|
|
},
|
|
"constraints": [
|
|
"services 和 expected 数据源有重叠但不完全一致 — 代码用 added{} 去重合并",
|
|
"ejabberd 和 gateway 服务只出现在 /api/services，不在 /api/expected 中",
|
|
"watchdog 和定时任务只出现在 /api/expected，不在 /api/services",
|
|
"tier1 监控可能不存在 — 代码做空值检查 (if mD.tier1 && mD.tier1.summary)",
|
|
"所有服务名通过 M{} 元数据映射到中文 label/layer/impact"
|
|
],
|
|
"must_not": [
|
|
"不要移除 added{} 去重机制 — 否则 expected 和 services 重叠的服务会重复显示",
|
|
"不要在 fHealth() 里用 fill('health',...) 外的渲染方式 — 标准 fill pattern",
|
|
"不要移除 M{} 元数据映射 — 它是中文展示和分层的核心"
|
|
],
|
|
"tests": [
|
|
{"id": "H01", "name": "/api/services 返回服务列表", "endpoint": "GET /api/services"},
|
|
{"id": "H02", "name": "/api/expected 返回期望矩阵", "endpoint": "GET /api/expected"},
|
|
{"id": "H03", "name": "/api/monitor 返回监控数据", "endpoint": "GET /api/monitor"},
|
|
{"id": "H04", "name": "三層結構正确渲染 (summary + issues + grouped)", "endpoint": "n/a (frontend check)"}
|
|
],
|
|
"known_issues": [
|
|
"scheduled tasks 在 Linux 246 上无法检测 Windows 计划任务状态，统一显示 not_deployed",
|
|
"部分服务的 HTTP health check 端点可能返回 Connection refused（如 xmpp_bot 在 5807 仅 Windows 端监听）"
|
|
],
|
|
"related_files": [
|
|
"gateway/scripts/templates/dashboard.html — fHealth() 渲染函数",
|
|
"gateway/scripts/dashboard.py — /api/services, /api/expected, /api/monitor",
|
|
"gateway/scripts/specs/health.json — 本 spec 文件"
|
|
]
|
|
}
|
|
}
|