# parseComtradeVector 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)
- 方法：`parseComtradeVector`
- 请求路径：`POST /wave/parseComtradeVector`
- Content-Type：`multipart/form-data`
- 返回类型：`HttpResult<WaveComtradeVectorResultVO>`

用途说明：

- 上传一组 COMTRADE `cfg/dat` 文件
- 按原始波形逐周波计算电能质量指标
- 返回总有效值、基波相角、谐波指标、序分量与不平衡度

## 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 | 否 | `3` | 本接口内部固定按原始波形口径计算，建议传 `3` |
| `ptType` | integer | 否 | `0` | PT 接线方式：`0` 星形，`1` 三角，`2` 开口三角 |
| `pt` | number | 否 | `1` | PT 变比，电压结果按 `pt/1000` 换算为 `kV` |
| `ct` | number | 否 | `1` | CT 变比，电流结果按 `ct` 换算为 `A` |
| `monitorName` | string | 否 | `未命名测点` | 测点名称 |

## 3. 调试请求示例

### 3.1 curl

```bash
curl -X POST "http://localhost:8080/wave/parseComtradeVector" \
  -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=3" \
  -F "ptType=0" \
  -F "pt=1" \
  -F "ct=1" \
  -F "monitorName=监测点1"
```

### 3.2 Apifox / Postman

- Method：`POST`
- URL：`http://localhost:8080/wave/parseComtradeVector`
- Body：`form-data`

| Key | Type | 示例值 |
| --- | --- | --- |
| `cfgFile` | File | 选择 `.cfg` 文件 |
| `datFile` | File | 选择 `.dat` 文件 |
| `parseType` | Text | `3` |
| `ptType` | Text | `0` |
| `pt` | Text | `1` |
| `ct` | Text | `1` |
| `monitorName` | Text | `监测点1` |

## 4. 响应结构

### 4.1 data 字段

定义来源：[WaveComtradeVectorResultVO.java](D:/Work/SourceCode/CN_Tool/tools/wave-tool/src/main/java/com/njcn/gather/tool/wave/pojo/vo/WaveComtradeVectorResultVO.java)

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| `monitorName` | string | 测点名称 |
| `time` | string | 事件发生时刻 |
| `samplePerCycle` | integer | 每周波采样点数 |
| `cycleCount` | integer | 可计算周波数 |
| `vectorGroups` | array | 各电压/电流组的逐周波电能质量结果 |

### 4.2 vectorGroups

定义来源：[WaveVectorGroupDTO.java](D:/Work/SourceCode/CN_Tool/tools/wave-tool/src/main/java/com/njcn/gather/tool/wave/pojo/dto/WaveVectorGroupDTO.java)

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| `channelName` | string | 通道名称，例如 `U1`、`I1` |
| `unit` | string | 单位，电压组为 `kV`，电流组为 `A` |
| `phaseCount` | integer | 相别数量 |
| `phaseNames` | array<string> | 相别名称列表，例如 `A相/B相/C相` |
| `vectorSeries` | array | 当前组的逐周波结果序列 |

### 4.3 vectorSeries

定义来源：[WaveCycleVectorDTO.java](D:/Work/SourceCode/CN_Tool/tools/wave-tool/src/main/java/com/njcn/gather/tool/wave/pojo/dto/WaveCycleVectorDTO.java)

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| `cycleIndex` | integer | 周波序号，从 `0` 开始 |
| `time` | number | 当前周波中点时刻，单位毫秒 |
| `phaseVectors` | array | 各相结果 |
| `positiveSequence` | object | 正序分量 |
| `negativeSequence` | object | 负序分量 |
| `zeroSequence` | object | 零序分量 |
| `unbalance` | object | 负序/零序不平衡度 |

### 4.4 phaseVectors

定义来源：[WavePhaseVectorDTO.java](D:/Work/SourceCode/CN_Tool/tools/wave-tool/src/main/java/com/njcn/gather/tool/wave/pojo/dto/WavePhaseVectorDTO.java)

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| `phaseName` | string | 相别名称 |
| `totalRms` | number | 电压/电流总有效值 |
| `fundamentalAmplitude` | number | 基波幅值 |
| `fundamentalRms` | number | 基波有效值 |
| `fundamentalPhaseAngle` | number | 基波相角，单位度 |
| `harmonicVoltageContentRates` | array | 仅电压组返回，2~50 次谐波电压含有率 |
| `harmonicCurrentAmplitudes` | array | 仅电流组返回，2~50 次谐波电流幅值 |
| `harmonicDistortionRate` | number | 谐波畸变率，百分比 |

### 4.5 谐波对象

定义来源：[WaveHarmonicDTO.java](D:/Work/SourceCode/CN_Tool/tools/wave-tool/src/main/java/com/njcn/gather/tool/wave/pojo/dto/WaveHarmonicDTO.java)

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| `harmonicOrder` | integer | 谐波次数，当前范围 `2~50` |
| `amplitude` | number | 谐波幅值 |
| `rms` | number | 谐波有效值 |
| `rate` | number | 谐波占基波比率，百分比，仅电压组使用 |

### 4.6 序分量与不平衡度

定义来源：
- [WaveSequenceVectorDTO.java](D:/Work/SourceCode/CN_Tool/tools/wave-tool/src/main/java/com/njcn/gather/tool/wave/pojo/dto/WaveSequenceVectorDTO.java)
- [WaveSequenceUnbalanceDTO.java](D:/Work/SourceCode/CN_Tool/tools/wave-tool/src/main/java/com/njcn/gather/tool/wave/pojo/dto/WaveSequenceUnbalanceDTO.java)

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| `sequenceName` | string | 序分量名称 |
| `amplitude` | number | 序分量幅值 |
| `rms` | number | 序分量有效值 |
| `phaseAngle` | number | 序分量相角 |
| `negativeUnbalanceRate` | number | 负序不平衡度，`负序/正序 * 100%` |
| `zeroUnbalanceRate` | number | 零序不平衡度，`零序/正序 * 100%` |

## 5. 成功响应示例

```json
{
  "code": "SUCCESS",
  "message": "成功",
  "data": {
    "monitorName": "监测点1",
    "time": "2026-03-21 20:14:58.748",
    "samplePerCycle": 512,
    "cycleCount": 30,
    "vectorGroups": [
      {
        "channelName": "U1",
        "unit": "kV",
        "phaseCount": 3,
        "phaseNames": ["A相", "B相", "C相"],
        "vectorSeries": [
          {
            "cycleIndex": 0,
            "time": -90.0,
            "phaseVectors": [
              {
                "phaseName": "A相",
                "totalRms": 104.9367,
                "fundamentalAmplitude": 148.4032,
                "fundamentalRms": 104.9367,
                "fundamentalPhaseAngle": 1.3258,
                "harmonicVoltageContentRates": [
                  { "harmonicOrder": 2, "amplitude": 0.4213, "rms": 0.2979, "rate": 0.2839 },
                  { "harmonicOrder": 3, "amplitude": 0.3187, "rms": 0.2254, "rate": 0.2147 }
                ],
                "harmonicDistortionRate": 1.1284
              }
            ],
            "positiveSequence": { "sequenceName": "正序", "amplitude": 148.1021, "rms": 104.7238, "phaseAngle": 0.9864 },
            "negativeSequence": { "sequenceName": "负序", "amplitude": 0.8632, "rms": 0.6104, "phaseAngle": -117.6241 },
            "zeroSequence": { "sequenceName": "零序", "amplitude": 0.2261, "rms": 0.1599, "phaseAngle": 86.3174 },
            "unbalance": { "negativeUnbalanceRate": 0.5828, "zeroUnbalanceRate": 0.1527 }
          }
        ]
      }
    ]
  }
}
```

## 6. 失败场景

| 场景 | 说明 |
| --- | --- |
| `cfgFile` 或 `datFile` 未上传 | 返回业务异常，提示“cfg 或 dat 文件不能为空” |
| CFG 文件格式错误 | 返回 CFG 解析失败 |
| DAT 文件为空或格式错误 | 返回 DAT 解析失败 |
| 采样点不足一个周波 | 返回波形文件数据缺失或向量计算失败 |
| COMTRADE 向量计算过程中出现异常 | 返回“COMTRADE 向量计算失败” |

## 7. 备注

- 当前接口固定按原始波形口径计算，不依赖 `parseComtrade` 的 RMS 或特征值开关。
- 当前谐波范围默认计算 `2~50` 次。
- 如果单周波采样点数过低，高次谐波指标会受分辨率限制。