213 lines
8.0 KiB
Markdown
213 lines
8.0 KiB
Markdown
# 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` 次。
|
||
- 如果单周波采样点数过低，高次谐波指标会受分辨率限制。
|