# MoFin — Dashboard API 参考

> 版本: v1.0 | 端口: 8899 | 入口: http://192.168.1.246:8899

---

## Tab 结构

```
MoFin Dashboard
├── Services     — 服务状态总览（MoFin API+Dashboard / 知微 Gateway / ejabberd / DB，共4项）
└── 开发原则
    ├── G 规范   — 开发规范 + Spec 文档
    └── F 健康   — 系统健康监控（Tier1/Tier2）
```

---

## API 端点清单

### 服务监控

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/services` | 所有注册服务状态（含健康检查结果） |
| GET | `/api/expected` | 期望状态矩阵（含实际状态对比） |
| GET | `/api/monitor` | 聚合监控数据（tasks + Tier1 + Tier2） |
| GET | `/api/health` | Dashboard 自身健康检查 |

### 知识管理

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/module-spec/<module>` | 读取 `specs/{module}.json`（?§ 按钮后端） |

### 响应格式

**GET /api/services**:
```json
{
  "services": [
    {
      "name": "mofin_api",
      "label": "MoFin API",
      "port": 8899,
      "type": "http",
      "layer": "核心服务",
      "critical": true,
      "health": {"ok": true},
      "detail": "HTTP 200"
    }
  ],
  "summary": {"ok": 4, "total": 4}
}
```

**GET /api/monitor**:
```json
{
  "tasks": [
    {"name": "agents-health-check", "status": "cron_ok"},
    {"name": "agents-daily-health", "status": "not_deployed"},
    {"name": "dashboard", "status": "running", "detail": "services: 4/4"}
  ],
  "tier1": {"summary": {"ok": 4, "total": 4}, "services": [...]},
  "tier2": {"summary": {"ok": 0, "total": 0}, "services": []},
  "generated_at": "2026-07-19 10:00:00"
}
```

> 注：实际服务 4 项（mofin_api / zhiwei_gateway / ejabberd / mofin_db）。Dashboard 服务已并入 mofin_api（:8899 一体）。

---

## 前端架构

- 纯 HTML/CSS/JS（无框架）
- 深色主题（GitHub Dark 风格）
- 5 秒自动轮询（Services Tab）
- ?§ Spec 系统（human_help + ai_spec）

### Spec 系统（?§ 按钮）

每个有 spec 的模块在 UI 上显示两个按钮：
- `?` → 读取 `human_help` → 人类可读的帮助文档
- `§` → 读取 `ai_spec` → AI 可用的接口/约束/依赖

**Spec 文件位置**: `specs/{module}.json`
**API 端点**: `GET /api/module-spec/{module}`

---

## 数据流

```
crontab (每 5 分钟)
  └── agents_health_check.py → last_health_check.json

Dashboard (:8899)
  ├── /api/services ← 实时 TCP/HTTP 检测
  ├── /api/monitor ← 聚合读取 health check JSON
  └── /api/module-spec/<module> ← 读取 specs/

前端 (dashboard.html)
  ├── 5s 轮询 /api/services
  └── 按需请求 /api/monitor（F Tab 打开时）
```