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