波形解析相关

2026-04-16 08:18:22 +08:00
parent 47d103918f
commit 7fc8996bdf
21 changed files with 2330 additions and 0 deletions
--- a/tools/wave-tool/PARSE_COMTRADE_API.md
+++ b/tools/wave-tool/PARSE_COMTRADE_API.md
@@ -0,0 +1,266 @@
+# parseComtrade API 文档
+
+## 1. 接口概述
+
+- 接口名称：解析 COMTRADE 波形文件
+- Controller：[WaveController.java](D:/Work/SourceCode/CN_Tool/tools/wave-tool/src/main/java/com/njcn/gather/tool/wave/controller/WaveController.java)
+- 方法：`parseComtrade`
+- 请求路径：`POST /wave/parseComtrade`
+- Content-Type：`multipart/form-data`
+- 返回类型：`HttpResult<WaveComtradeResultVO>`
+
+用途说明：
+
+- 上传一组 COMTRADE `cfg/dat` 文件
+- 解析原始波形数据
+- 按请求决定是否补充 RMS 数据、前端查看明细和特征值结果
+
+## 2. 请求参数
+
+### 2.1 文件参数
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `cfgFile` | file | 是 | COMTRADE 配置文件 `.cfg` |
+| `datFile` | file | 是 | COMTRADE 数据文件 `.dat` |
+
+### 2.2 表单参数
+
+参数定义来源：[WaveComtradeParseParam.java](D:/Work/SourceCode/CN_Tool/tools/wave-tool/src/main/java/com/njcn/gather/tool/wave/pojo/param/WaveComtradeParseParam.java)
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| `parseType` | integer | 否 | `1` | 解析类型：`0` 高级算法采样率 32-128，`1` 普通展示，`2` App 抽点，`3` 原始波形 |
+| `ptType` | integer | 否 | `0` | PT 接线方式：`0` 星形，`1` 三角，`2` 开口三角 |
+| `pt` | number | 否 | `1` | PT 变比 |
+| `ct` | number | 否 | `1` | CT 变比 |
+| `monitorName` | string | 否 | `未命名测点` | 测点名称 |
+| `calculateRms` | boolean | 否 | `true` | 是否计算 RMS |
+| `buildDetails` | boolean | 否 | `true` | 是否构建前端查看明细 |
+| `calculateEigenvalue` | boolean | 否 | `false` | 是否计算特征值 |
+| `dynamicThreshold` | boolean | 否 | `true` | 特征值是否使用浮动门槛 |
+
+## 3. 请求示例
+
+```bash
+curl -X POST "http://localhost:8080/wave/parseComtrade" \
+  -F "cfgFile=@D:/00-B7-8D-00-E4-09/1_20260321_201458_748.CFG" \
+  -F "datFile=@D:/00-B7-8D-00-E4-09/1_20260321_201458_748.DAT" \
+  -F "parseType=1" \
+  -F "ptType=0" \
+  -F "pt=1" \
+  -F "ct=1" \
+  -F "monitorName=监测点1" \
+  -F "calculateRms=true" \
+  -F "buildDetails=true" \
+  -F "calculateEigenvalue=true" \
+  -F "dynamicThreshold=true"
+```
+
+## 4. 响应结构
+
+### 4.1 外层响应
+
+Controller 返回的是 `HttpResult<WaveComtradeResultVO>`。当前仓库内未展开 `HttpResult` 类型源码，本接口文档只对业务 `data` 部分做精确定义。
+
+业务数据类型来源：[WaveComtradeResultVO.java](D:/Work/SourceCode/CN_Tool/tools/wave-tool/src/main/java/com/njcn/gather/tool/wave/pojo/vo/WaveComtradeResultVO.java)
+
+### 4.2 data 字段定义
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `waveData` | object | 波形基础数据 |
+| `waveDataDetails` | array | 前端查看明细，`buildDetails=true` 时返回 |
+| `eigenvalues` | array | 特征值结果，`calculateEigenvalue=true` 时返回 |
+
+## 5. 业务对象说明
+
+### 5.1 waveData
+
+定义来源：[WaveDataDTO.java](D:/Work/SourceCode/CN_Tool/tools/wave-tool/src/main/java/com/njcn/gather/tool/wave/pojo/dto/WaveDataDTO.java)
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `comtradeCfgDTO` | object | CFG 解析结果 |
+| `waveTitle` | array<string> | 波形标题，例如 `["Time","UA相","UB相"]` |
+| `channelNames` | array<string> | 通道名称列表 |
+| `listWaveData` | array<array<number>> | 原始波形数据，首列为时间，后续列为相电压/电流值 |
+| `listRmsData` | array<array<number>> | RMS 波形数据，`calculateRms=true` 时可用 |
+| `listRmsMinData` | array<array<number>> | RMS 最小值摘要 |
+| `iPhasic` | integer | 相别数量 |
+| `ptType` | integer | PT 接线方式 |
+| `pt` | number | PT 变比 |
+| `ct` | number | CT 变比 |
+| `time` | string | 事件发生时刻 |
+| `monitorName` | string | 测点名称 |
+
+### 5.2 comtradeCfgDTO
+
+定义来源：[ComtradeCfgDTO.java](D:/Work/SourceCode/CN_Tool/tools/wave-tool/src/main/java/com/njcn/gather/tool/wave/pojo/dto/ComtradeCfgDTO.java)
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `nChannelNum` | integer | 通道总数 |
+| `nPhasic` | integer | 相别数量 |
+| `nAnalogNum` | integer | 模拟量通道数 |
+| `nDigitalNum` | integer | 开关量通道数 |
+| `timeStart` | string/date | 录波开始时间 |
+| `timeTrige` | string/date | 触发时间 |
+| `lstAnalogDTO` | array | 模拟量通道配置 |
+| `lstDigitalDTO` | array | 开关量通道配置 |
+| `nRates` | integer | 采样率分段数 |
+| `lstRate` | array | 采样率分段配置 |
+| `firstTime` | string/date | 首个触发时间对象 |
+| `firstMs` | integer | 首个触发毫秒值 |
+| `nPush` | integer | 触发前推点数 |
+| `finalSampleRate` | integer | 最终采样率 |
+| `nAllWaveNum` | integer | 总周波数 |
+| `strBinType` | string | 文件编码类型，例如 `BINARY` |
+
+### 5.3 waveDataDetails
+
+定义来源：[WaveDataDetail.java](D:/Work/SourceCode/CN_Tool/tools/wave-tool/src/main/java/com/njcn/gather/tool/wave/pojo/bo/WaveDataDetail.java)
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `instantData` | object | 瞬时波形数据 |
+| `rmsData` | object | RMS 波形数据 |
+| `a` | string | A 相名称 |
+| `b` | string | B 相名称 |
+| `c` | string | C 相名称 |
+| `channelName` | string | 通道名称 |
+| `unit` | string | 单位 |
+| `isOpen` | boolean | 是否开口三角模式 |
+| `title` | string | 当前图标题 |
+| `colors` | array<string> | 曲线颜色 |
+
+其中 `instantData` 和 `rmsData` 结构一致，定义分别来自：
+
+- [InstantData.java](D:/Work/SourceCode/CN_Tool/tools/wave-tool/src/main/java/com/njcn/gather/tool/wave/pojo/bo/InstantData.java)
+- [RmsData.java](D:/Work/SourceCode/CN_Tool/tools/wave-tool/src/main/java/com/njcn/gather/tool/wave/pojo/bo/RmsData.java)
+
+公共字段：
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `max` | number | 当前曲线最大值 |
+| `min` | number | 当前曲线最小值 |
+| `aValue` | array<array<number>> | A 相点位 |
+| `bValue` | array<array<number>> | B 相点位 |
+| `cValue` | array<array<number>> | C 相点位 |
+
+### 5.4 eigenvalues
+
+定义来源：[EigenvalueDTO.java](D:/Work/SourceCode/CN_Tool/tools/wave-tool/src/main/java/com/njcn/gather/tool/wave/pojo/dto/EigenvalueDTO.java)
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `amplitude` | number | 特征幅值百分比 |
+| `residualVoltage` | number | 残余电压 |
+| `ratedVoltage` | number | 额定电压 |
+| `durationTime` | number | 持续时间 |
+
+## 6. 成功响应示例
+
+以下示例基于真实样本文件联测结果整理，长数组做了截断展示。
+
+```json
+{
+  "code": "SUCCESS",
+  "message": "成功",
+  "data": {
+    "waveData": {
+      "comtradeCfgDTO": {
+        "nChannelNum": 6,
+        "nPhasic": 3,
+        "nAnalogNum": 6,
+        "nDigitalNum": 0,
+        "timeStart": "2026-03-21 20:14:58.648",
+        "timeTrige": "2026-03-21 20:14:58.748",
+        "nRates": 1,
+        "firstMs": 748,
+        "nPush": 100,
+        "finalSampleRate": 512,
+        "nAllWaveNum": 30,
+        "strBinType": "BINARY"
+      },
+      "waveTitle": ["Time", "UA相", "UB相", "UC相", "IA相", "IB相", "IC相"],
+      "channelNames": ["/", "U1", "U2", "U3", "I1", "I2", "I3"],
+      "listWaveData": {
+        "count": 15616,
+        "first": [-100.0, -146.56, -76.9, -76.9, -0.13, 0.01, -0.2],
+        "last": [509.96, 148.02, 69.73, 69.75, 0.16, 0.01, 0.15]
+      },
+      "listRmsData": {
+        "count": 15616,
+        "first": [-100.0, 104.94, 104.22, 104.23, 0.27, 0.01, 0.28],
+        "last": [509.96, 105.6, 105.1, 105.12, 0.24, 0.01, 0.24]
+      },
+      "listRmsMinData": [
+        [40.74, 41.2],
+        [362.19, 0.01]
+      ],
+      "iPhasic": 3,
+      "ptType": 0,
+      "pt": 1.0,
+      "ct": 1.0,
+      "time": "2026-03-21 20:14:58.748",
+      "monitorName": "监测点1"
+    },
+    "waveDataDetails": [
+      {
+        "channelName": "U1",
+        "unit": "kV",
+        "a": "A相",
+        "b": "B相",
+        "c": "C相",
+        "isOpen": false
+      },
+      {
+        "channelName": "I1",
+        "unit": "A",
+        "a": "A相",
+        "b": "B相",
+        "c": "C相",
+        "isOpen": false
+      }
+    ],
+    "eigenvalues": [
+      {
+        "amplitude": 0.3926178,
+        "residualVoltage": 41.200005,
+        "ratedVoltage": 104.936676,
+        "durationTime": 48.632812
+      },
+      {
+        "amplitude": 0.4067544,
+        "residualVoltage": 42.390152,
+        "ratedVoltage": 104.21559,
+        "durationTime": 54.492188
+      },
+      {
+        "amplitude": 0.40674016,
+        "residualVoltage": 42.396355,
+        "ratedVoltage": 104.2345,
+        "durationTime": 54.492188
+      }
+    ]
+  }
+}
+```
+
+## 7. 失败场景
+
+基于当前代码，常见失败场景包括：
+
+| 场景 | 说明 |
+| --- | --- |
+| `cfgFile` 或 `datFile` 未上传 | 返回业务异常，提示“cfg 或 dat 文件不能为空” |
+| CFG 文件格式错误 | 返回 CFG 解析失败 |
+| DAT 文件为空或格式错误 | 返回 DAT 解析失败 |
+| COMTRADE 解析过程中出现异常 | 返回“COMTRADE 波形解析失败” |
+
+## 8. 备注
+
+- 当前接口已经移除图片生成相关参数，不再支持 `generateInstantImage`、`generateRmsImage` 等旧字段。
+- 当前接口文档只覆盖 `parseComtrade`，其他波形文本解析接口请单独编写。