ClientApps/CN_Tool_client
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
45ab5c9e841cfbbc18c1777d63180cf82e67b944
CN_Tool_client/PARSE_COMTRADE_VECTOR_API.md

213 lines
8.0 KiB
Markdown
Raw Normal View History

波形解析相关
2026-04-16 20:20:52 +08:00
# 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` 次。
- 如果单周波采样点数过低，高次谐波指标会受分辨率限制。
Reference in New Issue Copy Permalink