# 中能智能分析业务后台 API 设计报告

> 来源：`swagger.json`（Swagger 2.0）  
> 接口文档：`http://192.168.5.4:16880/energy-manage-analyse-service/v2/api-docs?group=2.X版本`  
> 生成时间：2026-06-04

---

## 文档概览

| 项目 | 值 |
|------|-----|
| 标题 | 中能智能分析业务后台相关接口文档 |
| 版本 | 1.0 |
| 描述 | 包含模块：异常检测和健康诊断接口 |
| 联系方 | 研发中心 |
| Host | `192.168.5.4:16880` |
| 基础路径前缀 | `/energy-manage-analyse-service` |
| 协议风格 | Swagger 2.0，统一 `ResultResp<T>` 包装响应 |

---

## 1. 所有模块（Tags）

共 **3** 个业务模块：

| # | 模块名 | 接口数 | 职责 |
|---|--------|--------|------|
| 1 | 湍流尾流接口 | 1 | 风场湍流、尾流影响分析与可视化数据 |
| 2 | 风机健康查询接口 | 3 | 风场/风机健康评分、概览、趋势 |
| 3 | 风机异常检测查询接口 | 12 | 五类检测模块 + 传感器异常统计、热力图、趋势等 |

---

## 2. 所有接口

共 **16** 个接口，**全部为 POST**。

### 2.1 湍流尾流接口（1）

| 方法 | 路径 | 摘要 | operationId | 请求参数 | 响应 data |
|------|------|------|-------------|----------|-----------|
| POST | `/wakewindfarm/getWakeWindFarm` | 风场湍流尾流的数据 | `getWakeWindFarmUsingPOST` | `datatime`(query), `fieldCode`(query,必填) | `WakeWindFarmVO` |

### 2.2 风机健康查询接口（3）

| 方法 | 路径 | 摘要 | operationId | 请求参数 | 响应 data |
|------|------|------|-------------|----------|-----------|
| POST | `/healthscores/getHealthOverview` | 风场下所有风机健康查询概览页面 | `getHealthOverviewUsingPOST` | `datatime`(query), `fieldCode`(query,必填) | `HealthOverviewVO` |
| POST | `/healthscores/getHealthscoresWindList` | 首页风场健康台数统计数据 | `getHealthscoresWindListUsingPOST` | `datatime`(query), `fieldCode`(query) | `List<HealthscoresWindVO>` |
| POST | `/healthscores/getLastDaysTrend` | 风机按天数查询趋势图 | `getLastDaysTrendUsingPOST` | `day`(query,必填), `engineId`(query,必填), `fieldId`(query,必填) | `HealthscoresTendencyVO` |

### 2.3 风机异常检测查询接口（12）

| 方法 | 路径 | 摘要 | operationId | 请求体 | 响应 data |
|------|------|------|-------------|--------|-----------|
| POST | `/anomaly/getAnomalyOverview` | 查询异常风机概览 | `getAnomalyOverviewUsingPOST` | `异常检测风场参数` | `风机异常概览` |
| POST | `/anomaly/getAnomalyModel` | 风机卡片 | `getAnomalyModelUsingPOST` | `异常检测风场参数` | `List<风机卡片返回数据>` |
| POST | `/anomaly/getAnomalyModelCount` | 查询模块异常台数（雷达图） | `getAnomalyModelCountUsingPOST` | `异常检测风场参数` | `模块统计雷达图` |
| POST | `/anomaly/getAnomalySensorCount` | 查询传感器异常台数（雷达图） | `getAnomalySensorCountUsingPOST` | `异常检测风场参数` | `传感器统计雷达图` |
| POST | `/anomaly/getBarChartStats` | 查询柱状图 | `getBarChartStatsUsingPOST` | `异常检测风场参数` | `异常检测概览页面柱状图` |
| POST | `/anomaly/getAnomalyModelMap` | 查询热力图 | `getAnomalyModelMapUsingPOST` | `异常检测风场参数` | `热力图` |
| POST | `/anomaly/getAnomalyWindpwr` | 风速功率模块 | `getAnomalyWindpwrUsingPOST` | `异常检测风场下风机基础参数` | `风速功率模块` |
| POST | `/anomaly/geAnomalyYaw` | 偏航模块 | `geAnomalyYawUsingPOST` | `异常检测风场下风机基础参数` | `偏航模块` |
| POST | `/anomaly/getAnomalyPitch` | 变桨模块 | `getAnomalyPitchUsingPOST` | `异常检测风场下风机基础参数` | `变桨模块` |
| POST | `/anomaly/getAnomalyCtrlParam` | 运行状态模块 | `getAnomalyCtrlParamUsingPOST` | `异常检测风场下风机基础参数` | `运行模块` |
| POST | `/anomaly/getAerodynamics` | 气动性能 | `getAerodynamicsUsingPOST` | `异常检测风场下风机基础参数` | `气动性能模块` |
| POST | `/anomaly/getPitchAnomalyTrend` | 模块异常趋势曲线（支持年度分表+跨年） | `getPitchAnomalyTrendUsingPOST` | `异常检测风场下风机基础参数` | `List<异常检测曲线图异常占比>` |

> 完整 URL = `http://{host}/energy-manage-analyse-service` + 上表路径

---

## 3. 所有 DTO（Definitions）

共 **50** 个模型，按职责分组如下。

### 3.1 统一响应包装（15）

所有业务接口 HTTP 200 均返回 `ResultResp<T>`：

```text
ResultResp<T> {
  code: integer
  data: T
  msg: string
  status: boolean
}
```

具体类型：`ResultResp«HealthOverviewVO»`、`ResultResp«List«风机卡片返回数据»»` 等共 15 种泛型包装。

### 3.2 请求 DTO（2）

| DTO | 字段 | 说明 |
|-----|------|------|
| **异常检测风场参数** | `datatime`, `fieldCode` | 风场级查询（概览、卡片、雷达图、柱状图、热力图） |
| **异常检测风场下风机基础参数** | `datatime`, `engineId`, `fieldId`, `timeRange` | 单机/模块级查询；`timeRange` 为曲线天数 7/30 |

> Swagger 参数名 `anomalyDTO` / `anomalyModelDTO` 实际引用上述两个 definition。

### 3.3 健康诊断 VO（4）

| DTO | 用途 |
|-----|------|
| `HealthOverviewVO` | 健康概览页：风机列表 + 风场汇总 |
| `HealthOverviewListVO` | 单台风机各子系统/部件评分 |
| `HealthscoresWindVO` | 风场健康台数统计（优/良/中/差） |
| `HealthscoresTendencyVO` | 按天趋势的多维度评分序列 |

### 3.4 湍流尾流 VO（2）

| DTO | 用途 |
|-----|------|
| `WakeWindFarmVO` | 风场尾流：图表路径、风机列表 |
| `WakeTurbineVO` | 单风机：湍流强度、速度亏损、是否受尾流影响 |

### 3.5 异常检测 — 聚合/展示 VO（10）

| DTO | 用途 |
|-----|------|
| `风机异常概览` | 检测器/传感器/总异常数 |
| `风机卡片返回数据` | 单台风机五模块 + 传感器明细（字段最多） |
| `模块统计雷达图` | 五模块异常台数 |
| `传感器统计雷达图` | 七类传感器异常台数 |
| `异常检测概览页面柱状图` | 偏航/变桨/风速功率/运行 四类计数 |
| `异常检测曲线图异常占比` | 按时间的五模块异常占比趋势 |
| `热力图` | `anomalyChartMap`、`anomalySensorMap` |
| `检测器热力图` | 风机名、是否异常、异常比例 |
| `风速功率模块` / `偏航模块` / `变桨模块` / `运行模块` / `气动性能模块` | 各模块下挂对应 `Anomaly*PO` 检测器 |

### 3.6 异常检测 — 持久化 PO（13）

各 PO 结构一致，记录检测器/传感器异常统计与文件路径：

`AnomalyCabletwistPO`、`AnomalyStaticyawPO`、`AnomalyMinpitchPO`、`AnomalyPitchcoordPO`、`AnomalyPitchregulationPO`、`AnomalyPowercurvePO`、`AnomalyScatterPO`、`AnomalySimulinkPO`、`AnomalyOperationPO`、`AnomalyPowerqualityPO`、`AnomalyCpPO`、`AnomalyCpTsrPO`、`AnomalyTsrPO`

公共字段：`id`, `fieldId`, `engineId`, `anomalyModelName`, `detectorIsAnomaly`, `detectorAnomalyCount`, `detectorNormallyCount`, `sensorIsAnomaly`, `sensorAnomalyCount`, `sensorNormallyCount`, `sensorAnomalyType`, `filePath`, `graphPath`, `sourceDatetime`, `createTime`

---

## 4. API 设计报告

### 4.1 领域模型

```mermaid
graph TB
    subgraph 风场维度
        F[fieldCode / fieldId]
    end
    subgraph 风机维度
        E[engineId]
    end
    subgraph 健康诊断
        H1[HealthOverview]
        H2[HealthscoresWind]
        H3[HealthscoresTendency]
    end
    subgraph 异常检测
        A1[概览/卡片/雷达/柱状/热力]
        A2[五模块详情]
        A3[趋势曲线]
    end
    subgraph 湍流尾流
        W[WakeWindFarm]
    end
    F --> H1 & H2 & A1 & W
    F --> E
    E --> H3 & A2 & A3
```

### 4.2 设计特点

1. **模块划分清晰**：健康、异常、尾流三条业务线，Swagger tag 与 URL 前缀一致（`/healthscores`、`/anomaly`、`/wakewindfarm`）。
2. **统一响应体**：`ResultResp` + `code/msg/status/data`，便于前端统一拦截。
3. **异常检测五模块模型**：
   - Model1：风速功率（功率曲线、散点、simulink）
   - Model2：偏航（扭缆、静态偏航）
   - Model3：变桨（最小桨距、协调、调节）
   - Model4：运行状态（机械运行、电气功率、降载）
   - Model5：气动性能（Cp、Cp-TSR、TSR）
4. **传感器维度独立**：风速、功率、转速、转矩、变桨及逻辑组合（风速-功率、转速-扭矩）与检测器维度并行统计。
5. **图表资源路径型响应**：尾流、部分异常结果通过 `*Path` 字符串返回 MinIO/文件服务路径，前端需二次加载图片或 JSON。

### 4.3 请求设计模式

| 模式 | 使用场景 | 示例 |
|------|----------|------|
| Query 参数 | 健康、尾流简单查询 | `fieldCode`, `datatime`, `day` |
| JSON Body | 异常检测全部接口 | `异常检测风场参数` / `异常检测风场下风机基础参数` |

**不一致点**：健康/尾流用 query，异常用 body；同一业务（风场+日期）存在 `fieldCode` 与 `fieldId` 两种命名，对接时需做字段映射。

### 4.4 接口依赖关系（前端页面建议）

```text
异常检测概览页
├── getAnomalyOverview      → 顶部统计
├── getBarChartStats        → 柱状图
├── getAnomalyModelCount    → 模块雷达图
├── getAnomalySensorCount   → 传感器雷达图
├── getAnomalyModelMap      → 热力图
└── getAnomalyModel         → 风机卡片列表

风机详情 / 模块下钻
├── getAnomalyWindpwr / geAnomalyYaw / getAnomalyPitch
├── getAnomalyCtrlParam / getAerodynamics
└── getPitchAnomalyTrend    → 趋势（需 engineId + timeRange）

健康首页
├── getHealthscoresWindList → 风场列表统计
├── getHealthOverview       → 概览
└── getLastDaysTrend        → 单机趋势

湍流尾流页
└── getWakeWindFarm
```

### 4.5 数据质量与规范建议

| 项 | 现状 | 建议 |
|----|------|------|
| HTTP 方法 | 查询类接口全部 POST | 只读接口可逐步改为 GET，利于缓存 |
| 命名 | `geAnomalyYaw` 拼写错误 | 保留旧路径，新增别名或文档标注 |
| 字段命名 | `fieldCode` vs `fieldId` | 文档明确二者等价关系 |
| 作废字段 | `model1WindpwrSimulink`、`model3PitchMinpitch` 标注作废 | 前端勿再展示 |
| 类型 | `热力图` 中 map 为 `object` | 补充具体 key 结构或示例 JSON |
| 安全 | 文档未描述鉴权 | 对接时确认 Token/网关头 |

### 4.6 与前端项目集成要点

1. 在 `src/api/` 新增 `energyAnalyse.js`（或按模块拆分），baseURL 指向 `energy-manage-analyse-service`。
2. 复用 `src/utils/request.js`，判断 `code === 200` 且 `status === true` 后取 `data`。
3. 风机卡片 `风机卡片返回数据` 字段众多，建议封装为表格列配置或按模块折叠展示。
4. 趋势接口 `getPitchAnomalyTrend` 注明支持年度分表，跨年查询需传完整 `datatime`/`timeRange`。
5. 图表类 `*Path` 字段需拼接文件服务域名或与现有 MinIO 下载逻辑复用。

### 4.7 统计摘要

| 维度 | 数量 |
|------|------|
| 业务模块 | 3 |
| API 接口 | 16 |
| DTO 模型 | 50 |
| 请求 DTO | 2 |
| 响应包装类型 | 15 |
| Anomaly PO | 13 |
| 检测模块 | 5 |
| 传感器类型 | 7 |

---

## 附录：完整接口路径清单

```
POST /energy-manage-analyse-service/wakewindfarm/getWakeWindFarm
POST /energy-manage-analyse-service/healthscores/getHealthOverview
POST /energy-manage-analyse-service/healthscores/getHealthscoresWindList
POST /energy-manage-analyse-service/healthscores/getLastDaysTrend
POST /energy-manage-analyse-service/anomaly/getAnomalyOverview
POST /energy-manage-analyse-service/anomaly/getAnomalyModel
POST /energy-manage-analyse-service/anomaly/getAnomalyModelCount
POST /energy-manage-analyse-service/anomaly/getAnomalySensorCount
POST /energy-manage-analyse-service/anomaly/getBarChartStats
POST /energy-manage-analyse-service/anomaly/getAnomalyModelMap
POST /energy-manage-analyse-service/anomaly/getAnomalyWindpwr
POST /energy-manage-analyse-service/anomaly/geAnomalyYaw
POST /energy-manage-analyse-service/anomaly/getAnomalyPitch
POST /energy-manage-analyse-service/anomaly/getAnomalyCtrlParam
POST /energy-manage-analyse-service/anomaly/getAerodynamics
POST /energy-manage-analyse-service/anomaly/getPitchAnomalyTrend
```