CN_Tool/tools/wave-tool/README.md

# 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`: 原始波形
  - `4`: 简化显示，保留 x 轴时间，对暂降底部中间段幅值置空
- `ptType`
  - PT 接线方式
  - `0`: 星形
  - `1`: 三角
  - `2`: 开口三角
- `pt`
  - PT 变比，优先使用 `cfg` 模拟量通道的一次/二次变比；`cfg` 无有效变比时使用该参数
- `ct`
  - CT 变比，优先使用 `cfg` 模拟量通道的一次/二次变比；`cfg` 无有效变比时使用该参数
- `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/` 中仍保留原始参考代码，后续如确认正式模块稳定，可再决定是否清理
- 图片生成依赖私有绘图与文件存储组件，当前仅完成代码接入，未做运行态验证