267 lines
9.1 KiB
Markdown
267 lines
9.1 KiB
Markdown
# 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`，其他波形文本解析接口请单独编写。
|