{
  "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 文件"
    ]
  }
}
