# 需求文档：监测统计模块

## 文档信息

- 创建时间：2026-07-22
- 需求来源：用户需求
- 关联模块：service_monitor/statistics

---

## 1. 背景与目标

### 1.1 背景

服务监测模块已实现：
- 目标服务器管理（本地/远程）
- 巡检报告生成与查看
- 定时任务调度
- 通知推送（钉钉/企业微信/邮件）

用户需要**统计分析和可视化**能力：
- 查看各目标服务器的健康趋势
- 分析检测项的历史变化
- 识别高频异常项
- 按模块维度查看健康度概览

### 1.2 目标

1. 新增左侧菜单"监测统计"
2. 提供可视化统计页面，支持：
   - 目标服务器筛选
   - 自定义日期范围
   - 模块健康概览（堆叠条形图）
   - 检测项趋势分析（折线图 + 状态分布饼图）
   - 高频异常项排行（水平条形图）

---

## 2. 需求详述

### 2.1 页面入口

**位置**：左侧导航菜单，在"巡检报告"之后、"定时任务"之前

**权限**：所有登录用户可查看（与报告页面一致）

**URL**：`/service-monitor/statistics`

---

### 2.2 筛选控制

#### 筛选项

| 筛选项 | 类型 | 说明 |
|--------|------|------|
| 目标服务器 | 下拉选择 | 可选择特定目标或"全部目标" |
| 开始日期 | 日期选择器 | 统计起始日期 |
| 结束日期 | 日期选择器 | 统计结束日期 |
| 查询按钮 | 按钮 | 点击后刷新统计数据 |

**默认值**：
- 目标：全部目标
- 开始日期：30 天前
- 结束日期：今天

**交互**：
- 修改筛选条件后，需点击"查询"按钮刷新
- 日期范围最大限制：90 天（防止加载过多数据）

---

### 2.3 页面布局

#### 2.3.1 概览摘要卡片（4 卡片网格）

| 卡片 | 内容 |
|------|------|
| 总报告数 | 日期范围内的巡检报告数量 |
| 异常率 | (警告+严重)/总检测项 × 100% |
| 最常异常项 | 异常次数最多的检测项名称 |
| 平均检测项 | 平均每份报告的检测项数量 |

#### 2.3.2 模块健康概览

**图表类型**：堆叠条形图（ECharts）

**维度**：
- X 轴：模块名称（按类别分组：系统模块在前，服务模块在后）
- Y 轴：检测项数量
- 系列：正常（绿色）、警告（黄色）、严重（红色）

**交互**：
- 鼠标悬停显示：模块名、正常/警告/严重数量、通过率
- 点击某模块可跳转到该模块的详细报告列表

#### 2.3.3 检测项趋势分析

**组成**：
1. **检测项选择器**：下拉菜单，列出当前筛选条件下出现过的所有检测项
2. **趋势折线图**（左侧 2/3 宽度）：
   - X 轴：时间（报告执行时间）
   - Y 轴：检测项数值
   - 阈值参考线（如有）
   - 数据点按状态着色（正常绿、警告黄、严重红）
3. **状态分布饼图**（右侧 1/3 宽度）：
   - 显示该检测项在日期范围内的状态分布
   - 正常、警告、严重占比

**特殊处理**：
- 非数值检测项（如"运行中"、"是"）：折线图不显示，仅显示饼图
- 某时间点无数据：折线图显示断点

#### 2.3.4 高频异常检测项

**图表类型**：水平堆叠条形图

**维度**：
- Y 轴：检测项名称（TOP 10）
- X 轴：异常次数
- 堆叠：警告（黄色）、严重（红色）

**交互**：
- 鼠标悬停显示：检测项名、总出现次数、异常次数、异常率
- 点击某检测项自动填充到趋势分析的选择器中

---

## 3. API 设计

| 方法 | URL | 参数 | 说明 |
|------|-----|------|------|
| GET | `/api/service-monitor/statistics/overview` | target_id, start_date, end_date | 概览摘要 |
| GET | `/api/service-monitor/statistics/modules` | target_id, start_date, end_date | 模块统计 |
| GET | `/api/service-monitor/statistics/item-trend` | target_id, item_key, start_date, end_date | 检测项趋势 |
| GET | `/api/service-monitor/statistics/abnormal-items` | target_id, start_date, end_date | 高频异常项 |
| GET | `/api/service-monitor/statistics/item-keys` | target_id, start_date, end_date | 检测项列表（用于选择器） |

**认证**：所有 API 需登录（返回 JSON 401 未登录）

---

## 4. 数据来源

### 4.1 报告数据结构

```json
{
  "id": "20260721_100000_abc123",
  "target_id": "local",
  "target_name": "本机",
  "started_at": "2026-07-21T10:00:00",
  "summary": {"正常": 42, "警告": 3, "严重": 1, "total": 46},
  "modules": [
    {
      "id": "02_cpu_check",
      "name": "CPU检测",
      "category": "system",
      "items": [
        {"key": "CPU_USAGE", "name": "CPU使用率", "value": "92%", "threshold": ">85%", "status": "严重"}
      ],
      "summary": {"正常": 5, "警告": 1, "严重": 0, "total": 6}
    }
  ]
}
```

### 4.2 聚合逻辑

| 指标 | 计算方式 |
|------|---------|
| 总报告数 | 统计日期范围内的报告数量 |
| 异常率 | sum(警告+严重) / sum(总检测项) × 100% |
| 模块健康度 | 按模块 ID 汇总正常/警告/严重计数 |
| 检测项趋势 | 扫描每份报告，提取指定 item_key 的值和状态 |
| 高频异常项 | 按 item_key 统计异常次数，降序取 TOP 10 |

---

## 5. 技术方案

### 5.1 后端

| 文件 | 改动 |
|------|------|
| `service_monitor/services/statistics_service.py` | 新增 - 统计聚合服务 |
| `service_monitor/services/__init__.py` | 导入新服务 |
| `service_monitor/routes.py` | 新增页面路由 + 5 个 API 端点 |

### 5.2 前端

| 文件 | 改动 |
|------|------|
| `templates/service_monitor/base.html` | 侧边栏添加"监测统计"菜单项 |
| `templates/service_monitor/statistics.html` | 新增 - 统计页面模板 |

### 5.3 图表库

**ECharts 5.5.1**（CDN 引入）：
- 堆叠条形图
- 折线图 + 标记点
- 饼图
- 响应式适配

---

## 6. 验收标准

| 标准 | 验证方法 |
|------|---------|
| 左侧菜单显示"监测统计" | 页面检查 |
| 页面正常加载，显示筛选栏和图表区域 | 页面检查 |
| 目标选择器列出所有目标 | 页面检查 |
| 日期选择器默认为近 30 天 | 页面检查 |
| 概览卡片显示正确数据 | 对比报告数据计算 |
| 模块健康图表正常渲染 | 检查 ECharts 图表 |
| 检测项选择器列出所有检测项 | 页面检查 |
| 选择检测项后趋势图正常显示 | 选择后检查 |
| 高频异常项图表正确显示 | 对比报告数据 |
| API 返回格式正确 | curl 测试 |
| 未登录访问 API 返回 401 | 未登录状态测试 |
| 单元测试通过 | pytest 运行 |

---

## 7. 风险评估

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| 报告数据量大时加载慢 | 页面响应时间长 | 默认 30 天范围；最大 200 份报告上限；两步加载（先摘要后详情） |
| 检测项键名不一致 | 趋势图数据缺失 | 动态扫描实际存在的键；选择器只显示有数据的项 |
| 非数值检测项无法绘图 | 折线图空白 | 跳过数值提取失败的点；饼图仍显示状态分布 |
| ECharts CDN 加载失败 | 图表不显示 | 使用稳定 CDN（jsdelivr）；本地缓存 |

---

## 8. 后续规划

1. **导出统计报告**：支持导出 PDF/图片格式的统计报告
2. **告警阈值配置**：允许用户配置统计告警阈值
3. **趋势预测**：基于历史数据进行趋势预测
4. **对比分析**：多目标对比分析