波形解析相关

2026-04-17 08:11:43 +08:00
parent 7fc8996bdf
commit dfbd552218
16 changed files with 1135 additions and 74 deletions
--- a/tools/wave-tool/README.md
+++ b/tools/wave-tool/README.md
@@ -0,0 +1,205 @@
+# 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/` 中仍保留原始参考代码，后续如确认正式模块稳定，可再决定是否清理
+- 图片生成依赖私有绘图与文件存储组件，当前仅完成代码接入，未做运行态验证