ClientApps/CN_Tool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7fc8996bdfd28ed09f32f1ea267faf87bb0a3f33
CN_Tool/tools/wave-tool/PARSE_COMTRADE_API.md

267 lines
9.1 KiB
Markdown
Raw Normal View History

波形解析相关
2026-04-16 08:18:22 +08:00
# 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`，其他波形文本解析接口请单独编写。
Reference in New Issue Copy Permalink