206 lines
4.3 KiB
Markdown
206 lines
4.3 KiB
Markdown
# wave-tool 模块说明
|
||
|
||
## 模块定位
|
||
|
||
`wave-tool` 是 `tools` 下的波形处理模块，当前承担以下能力：
|
||
|
||
- 文本波形解析
|
||
- COMTRADE `cfg/dat` 文件解析
|
||
- RMS 波形计算
|
||
- 波形明细组装
|
||
- 波形特征值计算
|
||
- 波形图片生成与上传
|
||
|
||
当前实现以 Spring Bean 方式对外提供能力，并由 `entrance` 模块直接聚合。
|
||
|
||
## 代码结构
|
||
|
||
```text
|
||
wave-tool/
|
||
├── src/main/java/com/njcn/gather/tool/wave/
|
||
│ ├── bo
|
||
│ ├── component
|
||
│ ├── controller
|
||
│ ├── dto
|
||
│ ├── enums
|
||
│ ├── param
|
||
│ ├── service
|
||
│ ├── utils
|
||
│ └── vo
|
||
└── temp/
|
||
```
|
||
|
||
说明：
|
||
|
||
- `component/WaveFileComponent`
|
||
- 负责 COMTRADE 波形文件解析、RMS 计算、特征值计算
|
||
- `component/WavePicComponent`
|
||
- 负责波形图片绘制结果合成与上传
|
||
- `service/impl/WaveServiceImpl`
|
||
- 负责统一编排文本波形解析与 COMTRADE 解析链路
|
||
- `utils/WaveUtil`
|
||
- 负责前端查看明细组装
|
||
- `utils/BitConverter`
|
||
- 负责波形二进制字节转换
|
||
- `temp/`
|
||
- 保留原始参考代码，不作为正式运行入口
|
||
|
||
## 对外接口
|
||
|
||
### 1. 文本波形解析
|
||
|
||
- 路径：`POST /wave/parse`
|
||
- Content-Type：`application/json`
|
||
|
||
请求体字段：
|
||
|
||
- `waveformText`
|
||
- 波形文本内容，必填
|
||
- `separator`
|
||
- 分隔符，支持 `AUTO`、`TAB`、`SPACE` 或直接传入具体字符
|
||
- `containsXAxis`
|
||
- 是否显式包含 X 轴
|
||
- `xColumnIndex`
|
||
- X 轴列下标
|
||
- `yColumnIndex`
|
||
- Y 轴列下标
|
||
- `skipHeaderLines`
|
||
- 跳过的表头行数
|
||
- `samplingInterval`
|
||
- 单列波形采样间隔
|
||
- `maxPointCount`
|
||
- 返回最大点位数
|
||
|
||
返回字段：
|
||
|
||
- `containsXAxis`
|
||
- `sourcePointCount`
|
||
- `displayPointCount`
|
||
- `ignoredLineCount`
|
||
- `sampled`
|
||
- `minX`
|
||
- `maxX`
|
||
- `minY`
|
||
- `maxY`
|
||
- `averageY`
|
||
- `points`
|
||
|
||
### 2. COMTRADE 波形解析
|
||
|
||
- 路径：`POST /wave/parseComtrade`
|
||
- Content-Type：`multipart/form-data`
|
||
|
||
文件字段：
|
||
|
||
- `cfgFile`
|
||
- COMTRADE 配置文件
|
||
- `datFile`
|
||
- COMTRADE 数据文件
|
||
|
||
表单字段：
|
||
|
||
- `parseType`
|
||
- 解析类型
|
||
- `0`: 高级算法采样率 32-128
|
||
- `1`: 普通展示
|
||
- `2`: App 抽点
|
||
- `3`: 原始波形
|
||
- `ptType`
|
||
- PT 接线方式
|
||
- `0`: 星形
|
||
- `1`: 三角
|
||
- `2`: 开口三角
|
||
- `pt`
|
||
- PT 变比
|
||
- `ct`
|
||
- CT 变比
|
||
- `monitorName`
|
||
- 测点名称
|
||
- `calculateRms`
|
||
- 是否计算 RMS
|
||
- `buildDetails`
|
||
- 是否组装前端查看明细
|
||
- `calculateEigenvalue`
|
||
- 是否计算特征值
|
||
- `dynamicThreshold`
|
||
- 特征值算法是否使用浮动门槛
|
||
- `generateInstantImage`
|
||
- 是否生成瞬时波形图
|
||
- `generateRmsImage`
|
||
- 是否生成 RMS 波形图
|
||
- `generateInstantZlImage`
|
||
- 是否生成治理场景瞬时波形图
|
||
- `generateRmsZlImage`
|
||
- 是否生成治理场景 RMS 波形图
|
||
|
||
返回字段：
|
||
|
||
- `waveData`
|
||
- 波形基础数据，包含 `cfg`、原始波形、RMS、标题等
|
||
- `waveDataDetails`
|
||
- 前端查看明细
|
||
- `eigenvalues`
|
||
- 特征值结果
|
||
- `instantImagePath`
|
||
- 瞬时波形图路径
|
||
- `rmsImagePath`
|
||
- RMS 波形图路径
|
||
- `instantZlImagePath`
|
||
- 治理场景瞬时波形图路径
|
||
- `rmsZlImagePath`
|
||
- 治理场景 RMS 波形图路径
|
||
|
||
## 使用示例
|
||
|
||
### 文本波形
|
||
|
||
```json
|
||
{
|
||
"waveformText": "0,220\n1,221\n2,219",
|
||
"separator": "AUTO",
|
||
"containsXAxis": true,
|
||
"maxPointCount": 2000
|
||
}
|
||
```
|
||
|
||
### COMTRADE 波形
|
||
|
||
```bash
|
||
curl -X POST "http://localhost:8080/wave/parseComtrade" \
|
||
-F "cfgFile=@D:/data/test.cfg" \
|
||
-F "datFile=@D:/data/test.dat" \
|
||
-F "parseType=1" \
|
||
-F "ptType=0" \
|
||
-F "pt=1" \
|
||
-F "ct=1" \
|
||
-F "monitorName=测试测点" \
|
||
-F "calculateRms=true" \
|
||
-F "buildDetails=true" \
|
||
-F "calculateEigenvalue=true" \
|
||
-F "dynamicThreshold=true" \
|
||
-F "generateInstantImage=true" \
|
||
-F "generateRmsImage=true"
|
||
```
|
||
|
||
## 依赖说明
|
||
|
||
模块自身直接声明的依赖仍然较轻，核心包括：
|
||
|
||
- `com.njcn:njcn-common`
|
||
- `com.njcn:spingboot2.3.12`
|
||
|
||
但当前图片链路还依赖私有组件能力：
|
||
|
||
- `DrawPicUtil`
|
||
- `FileStorageUtil`
|
||
- `OssPath`
|
||
- `PicCommonData`
|
||
|
||
因此，若要真实运行图片生成功能，需要确保这些依赖在实际环境中可用。
|
||
|
||
## 当前限制
|
||
|
||
- 当前未执行 `mvn` 编译或测试验证
|
||
- `temp/` 中仍保留原始参考代码，后续如确认正式模块稳定，可再决定是否清理
|
||
- 图片生成依赖私有绘图与文件存储组件，当前仅完成代码接入，未做运行态验证
|