performance-test/docs/API_DESIGN_REPORT_energy-manage-analyse.md

中能智能分析业务后台 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>：

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 领域模型

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 接口依赖关系（前端页面建议）

异常检测概览页
├── 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