refactor(steady): 重构数据校验功能并新增PQDIF解析预留模块

- 将数据校验中的缺失率相关字段替换为数据完整性字段 - 新增数据校验任务删除功能及相应测试 - 在tools模块中添加parse-pqdif子模块作为PQDIF文件解析预留 - 更新README文档以反映新的模块结构和依赖关系 - 优化数据校验统计汇总逻辑和测试覆盖 - 在entrance模块中集成parse-pqdif依赖 - 重构数据校验服务层实现和数据对象映射
2026-06-12 08:41:11 +08:00
parent f7154db93d
commit 212b69060c
37 changed files with 1606 additions and 126 deletions
--- a/steady/steady-DataView/steady-checksquare-api-debug_20260610.md
+++ b/steady/steady-DataView/steady-checksquare-api-debug_20260610.md
@@ -0,0 +1,522 @@
+# 数据校验 API 调试文档
+
+## 1. 基础信息
+
+- 模块：`steady/steady-DataView`
+- 控制器：`com.njcn.gather.steady.checksquare.controller.SteadyChecksquareController`
+- 接口前缀：`/steady/data-view/checksquare`
+- 本地默认地址：`http://localhost:18192`
+- Content-Type：`application/json`
+- 认证：除登录和 Swagger 资源外，请求需要携带登录后的 `Authorization` 请求头。
+- 数据库结果表：`steady_checksquare_task`、`steady_checksquare_item`、`steady_checksquare_stat_summary`、`steady_checksquare_detail`
+
+通用请求头：
+
+```http
+Authorization: Bearer <token>
+Content-Type: application/json
+```
+
+通用返回结构：
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {}
+}
+```
+
+> 实际 `code`、`message` 字段以项目公共 `HttpResult` 封装为准，下面示例重点展示 `data` 内容。
+
+## 2. 查询数据校验历史记录
+
+- 方法：`POST`
+- 路径：`/steady/data-view/checksquare/query`
+- 返回：`HttpResult<Page<SteadyChecksquareTaskVO>>`
+- 说明：分页查询已落库的数据校验任务，按创建时间倒序返回。
+
+请求示例：
+
+```json
+{
+  "pageNum": 1,
+  "pageSize": 10,
+  "lineId": "line-001",
+  "indicatorCode": "V_RMS",
+  "timeStart": "2026-05-01 00:00:00",
+  "timeEnd": "2026-05-01 23:59:59",
+  "hasAbnormal": true
+}
+```
+
+请求字段：
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `pageNum` | 否 | 当前页码，继承自 `BaseParam` |
+| `pageSize` | 否 | 每页数量，继承自 `BaseParam` |
+| `lineId` | 否 | 监测点 ID，精确匹配 |
+| `indicatorCode` | 否 | 指标编码，按任务指标集合匹配 |
+| `timeStart` | 否 | 检测开始时间下限，格式 `yyyy-MM-dd HH:mm:ss` |
+| `timeEnd` | 否 | 检测结束时间上限，格式 `yyyy-MM-dd HH:mm:ss` |
+| `hasAbnormal` | 否 | 是否只查询存在异常项的任务；`true` 表示 `abnormalItemCount > 0` |
+
+返回示例：
+
+```json
+{
+  "records": [
+    {
+      "taskId": "8f7a4d6d1f3145a88b6f9d7a8e6c1001",
+      "taskNo": "CS202606101630001",
+      "lineId": "line-001",
+      "lineName": "进线一",
+      "timeStart": "2026-05-01 00:00:00",
+      "timeEnd": "2026-05-01 23:59:59",
+      "intervalMinutes": 1,
+      "taskStatus": "SUCCESS",
+      "itemCount": 2,
+      "abnormalItemCount": 1,
+      "minDataIntegrity": 0.999306,
+      "createTime": "2026-06-10 16:30:00"
+    }
+  ],
+  "total": 1,
+  "size": 10,
+  "current": 1,
+  "pages": 1
+}
+```
+
+cURL 示例：
+
+```bash
+curl -X POST "http://localhost:18192/steady/data-view/checksquare/query" \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"pageNum":1,"pageSize":10,"lineId":"line-001","indicatorCode":"V_RMS","hasAbnormal":true}'
+```
+
+## 3. 新增数据校验记录
+
+- 方法：`POST`
+- 路径：`/steady/data-view/checksquare/create`
+- 返回：`HttpResult<SteadyChecksquareCreateVO>`
+- 说明：按监测点、指标和时间范围实时查询 InfluxDB，执行缺数校验、指标值大小关系校验、谐波奇偶关系校验，并将任务、检测项、统计摘要和明细写入 MySQL。
+
+请求示例：
+
+```json
+{
+  "lineId": "line-001",
+  "indicatorCodes": ["V_RMS", "FREQ", "V_HARMONIC"],
+  "timeStart": "2026-05-01 00:00:00",
+  "timeEnd": "2026-05-01 23:59:59"
+}
+```
+
+请求字段：
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `lineId` | 是 | 监测点 ID，需要能在台账中找到且处于可用状态 |
+| `indicatorCodes` | 是 | 指标编码列表，来自 `/steady/data-view/indicator-tree` |
+| `timeStart` | 是 | 检测开始时间，格式 `yyyy-MM-dd HH:mm:ss` |
+| `timeEnd` | 是 | 检测结束时间，格式 `yyyy-MM-dd HH:mm:ss` |
+
+返回示例：
+
+```json
+{
+  "taskId": "8f7a4d6d1f3145a88b6f9d7a8e6c1001",
+  "taskNo": "CS202606101630001",
+  "lineId": "line-001",
+  "lineName": "进线一",
+  "timeStart": "2026-05-01 00:00:00",
+  "timeEnd": "2026-05-01 23:59:59",
+  "intervalMinutes": 1,
+  "itemCount": 3,
+  "abnormalItemCount": 1
+}
+```
+
+cURL 示例：
+
+```bash
+curl -X POST "http://localhost:18192/steady/data-view/checksquare/create" \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"lineId":"line-001","indicatorCodes":["V_RMS","FREQ","V_HARMONIC"],"timeStart":"2026-05-01 00:00:00","timeEnd":"2026-05-01 23:59:59"}'
+```
+
+调试建议：
+
+- 新增接口会实际写入 MySQL，重复调用会生成新的任务记录。
+- 时间范围越大、指标越多，InfluxDB 查询和明细落库耗时越高。
+- 谐波类指标固定按 2-50 次聚合检测，不需要在请求体传 `harmonicOrders`。
+
+## 4. 查询数据校验任务详情
+
+- 方法：`GET`
+- 路径：`/steady/data-view/checksquare/detail`
+- 返回：`HttpResult<SteadyChecksquareQueryVO>`
+- 说明：按任务 ID 查询任务基础信息、检测项列表和各检测项统计摘要。检测项的明细列表通过 `/item-detail` 按需查询。
+
+请求参数：
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `taskId` | 是 | 数据校验任务 ID，即 `/query` 或 `/create` 返回的 `taskId` |
+
+请求示例：
+
+```http
+GET /steady/data-view/checksquare/detail?taskId=8f7a4d6d1f3145a88b6f9d7a8e6c1001
+```
+
+返回示例：
+
+```json
+{
+  "taskId": "8f7a4d6d1f3145a88b6f9d7a8e6c1001",
+  "taskNo": "CS202606101630001",
+  "lineId": "line-001",
+  "lineName": "进线一",
+  "timeStart": "2026-05-01 00:00:00",
+  "timeEnd": "2026-05-01 23:59:59",
+  "intervalMinutes": 1,
+  "items": [
+    {
+      "itemId": "0f4b6d6c3e9d400a902a2df101d10001",
+      "itemKey": "line-001|V_RMS",
+      "indicatorCode": "V_RMS",
+      "indicatorName": "相电压有效值",
+      "harmonicOrder": null,
+      "intervalMinutes": 1,
+      "hasData": true,
+      "expectedPointCount": 5760,
+      "actualPointCount": 5756,
+      "missingPointCount": 4,
+      "dataIntegrity": 0.999306,
+      "dataIntegrityText": "99.93%",
+      "abnormal": true,
+      "abnormalPointCount": 2,
+      "harmonicParityAbnormal": false,
+      "harmonicParityAbnormalPointCount": 0,
+      "statSummaries": [
+        {
+          "statType": "AVG",
+          "supported": true,
+          "hasData": true,
+          "expectedPointCount": 1440,
+          "actualPointCount": 1439,
+          "missingPointCount": 1,
+          "dataIntegrity": 0.999306,
+          "dataIntegrityText": "99.93%",
+        }
+      ],
+      "statDetails": []
+    }
+  ]
+}
+```
+
+cURL 示例：
+
+```bash
+curl -X GET "http://localhost:18192/steady/data-view/checksquare/detail?taskId=8f7a4d6d1f3145a88b6f9d7a8e6c1001" \
+  -H "Authorization: Bearer <token>"
+```
+
+## 5. 查询检测项明细
+
+- 方法：`GET`
+- 路径：`/steady/data-view/checksquare/item-detail`
+- 返回：`HttpResult<SteadyChecksquareItemDetailVO>`
+- 说明：按检测项 ID、明细类型查询缺数连续区间、指标值大小关系异常点或谐波奇偶关系异常点。`pageNum` 和 `pageSize` 未同时传入时保持全量返回；两者同时传入且均大于 0 时返回当前页明细，并在结果中带回分页元数据。
+
+请求参数：
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `itemId` | 是 | 检测项 ID，即任务详情中每个 `items[].itemId` |
+| `detailType` | 是 | 明细类型：`SEGMENT`、`VALUE_ORDER`、`HARMONIC_PARITY` |
+| `statType` | 否 | 统计类型：`AVG`、`MAX`、`MIN`、`CP95`；查询缺数区间时建议传入 |
+| `pageNum` | 否 | 明细分页页码；与 `pageSize` 同时传入且大于 0 时启用分页 |
+| `pageSize` | 否 | 明细分页条数；与 `pageNum` 同时传入且大于 0 时启用分页 |
+
+### 5.1 查询缺数连续区间
+
+请求示例：
+
+```http
+GET /steady/data-view/checksquare/item-detail?itemId=0f4b6d6c3e9d400a902a2df101d10001&detailType=SEGMENT&statType=AVG
+```
+
+返回示例：
+
+```json
+{
+  "itemId": "0f4b6d6c3e9d400a902a2df101d10001",
+  "detailType": "SEGMENT",
+  "statType": "AVG",
+  "pageNum": null,
+  "pageSize": null,
+  "total": null,
+  "segments": [
+    {
+      "startTime": "2026-05-01 00:00:00",
+      "endTime": "2026-05-01 00:09:00",
+      "status": "NORMAL",
+      "harmonicOrder": null,
+      "missingPointCount": 0,
+      "durationMinutes": 10
+    },
+    {
+      "startTime": "2026-05-01 00:10:00",
+      "endTime": "2026-05-01 00:10:00",
+      "status": "MISSING",
+      "harmonicOrder": null,
+      "missingPointCount": 1,
+      "durationMinutes": 1
+    }
+  ],
+  "valueOrderDetails": [],
+  "harmonicParityDetails": []
+}
+```
+
+### 5.2 查询指标值大小关系异常明细
+
+请求示例：
+
+```http
+GET /steady/data-view/checksquare/item-detail?itemId=0f4b6d6c3e9d400a902a2df101d10001&detailType=VALUE_ORDER&pageNum=1&pageSize=20
+```
+
+返回示例：
+
+```json
+{
+  "itemId": "0f4b6d6c3e9d400a902a2df101d10001",
+  "detailType": "VALUE_ORDER",
+  "statType": null,
+  "pageNum": 1,
+  "pageSize": 20,
+  "total": 1,
+  "segments": [],
+  "valueOrderDetails": [
+    {
+      "time": "2026-05-01 00:10:00",
+      "phase": "A",
+      "harmonicOrder": null,
+      "maxValue": 219.8,
+      "minValue": 218.1,
+      "avgValue": 219.0,
+      "cp95Value": 219.8
+    }
+  ],
+  "harmonicParityDetails": []
+}
+```
+
+### 5.3 查询谐波奇偶关系异常明细
+
+请求示例：
+
+```http
+GET /steady/data-view/checksquare/item-detail?itemId=0f4b6d6c3e9d400a902a2df101d10002&detailType=HARMONIC_PARITY&pageNum=1&pageSize=20
+```
+
+返回示例：
+
+```json
+{
+  "itemId": "0f4b6d6c3e9d400a902a2df101d10002",
+  "detailType": "HARMONIC_PARITY",
+  "statType": null,
+  "pageNum": 1,
+  "pageSize": 20,
+  "total": 1,
+  "segments": [],
+  "valueOrderDetails": [],
+  "harmonicParityDetails": [
+    {
+      "time": "2026-05-01 00:10:00",
+      "phase": "A",
+      "statType": "AVG",
+      "evenHarmonicOrder": 4,
+      "evenValue": 0.32,
+      "oddHarmonicOrders": [3, 5],
+      "oddValues": [0.08, 0.09],
+      "oddMedianValue": 0.085,
+      "thresholdMultiplier": 3.0
+    }
+  ]
+}
+```
+
+cURL 示例：
+
+```bash
+curl -X GET "http://localhost:18192/steady/data-view/checksquare/item-detail?itemId=0f4b6d6c3e9d400a902a2df101d10001&detailType=VALUE_ORDER" \
+  -H "Authorization: Bearer <token>"
+```
+
+分页 cURL 示例：
+
+```bash
+curl -X GET "http://localhost:18192/steady/data-view/checksquare/item-detail?itemId=0f4b6d6c3e9d400a902a2df101d10001&detailType=VALUE_ORDER&pageNum=1&pageSize=20" \
+  -H "Authorization: Bearer <token>"
+```
+
+## 6. 删除数据校验任务
+
+- 方法：`POST`
+- 路径：`/steady/data-view/checksquare/delete`
+- 返回：`HttpResult<Boolean>`
+- 说明：按任务 ID 批量逻辑删除数据校验任务，并同步将任务下检测项置为删除态。删除后历史查询不再返回该任务，详情和检测项明细会按不存在处理。
+
+请求示例：
+
+```json
+[
+  "8f7a4d6d1f3145a88b6f9d7a8e6c1001"
+]
+```
+
+请求字段：
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| 请求体 | 是 | 数据校验任务 ID 数组 |
+
+返回示例：
+
+```json
+true
+```
+
+cURL 示例：
+
+```bash
+curl -X POST "http://localhost:18192/steady/data-view/checksquare/delete" \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '["8f7a4d6d1f3145a88b6f9d7a8e6c1001"]'
+```
+
+## 7. 校验规则说明
+
+### 7.1 缺数校验
+
+- 按检测项支持的统计类型分别查询实际存在的时间点。
+- 返回期望点数、实际点数、缺失点数、数据完整性和最大连续缺失时长。
+- `SEGMENT` 明细按连续区间返回，`status` 可取 `NORMAL`、`MISSING`。
+- `FLUC`、`PST` 固定按 10 分钟间隔校验，`PLT` 固定按 120 分钟间隔校验，其余指标按监测点统计间隔校验。
+
+### 7.2 指标值大小关系校验
+
+- 同一时间点、同一指标、同一相别需要满足 `MAX >= CP95 >= AVG >= MIN`。
+- 缺少 `MAX`、`CP95`、`AVG`、`MIN` 任一值的时间点不计入大小关系异常，由缺数校验体现。
+- 异常点写入 `VALUE_ORDER` 明细，前端可通过 `item-detail` 拉取后弹窗展示。
+
+### 7.3 谐波奇偶关系校验
+
+- 谐波指标固定聚合 2-50 次检测。
+- 偶次谐波值需要大于 `0.1` 才继续参与奇偶关系检测。
+- 异常点写入 `HARMONIC_PARITY` 明细，包含偶次谐波值、参与比较的奇次谐波值、中位数和阈值倍数。
+
+## 8. 字段说明
+
+### 8.1 任务字段
+
+| 字段 | 说明 |
+| --- | --- |
+| `taskId` | 数据校验任务 ID |
+| `taskNo` | 数据校验任务编号 |
+| `lineId` | 监测点 ID |
+| `lineName` | 监测点名称 |
+| `timeStart` | 检测开始时间 |
+| `timeEnd` | 检测结束时间 |
+| `intervalMinutes` | 监测点统计间隔，单位分钟 |
+| `taskStatus` | 任务状态，当前成功任务为 `SUCCESS` |
+| `itemCount` | 检测项数量 |
+| `abnormalItemCount` | 存在异常的检测项数量 |
+| `minDataIntegrity` | 检测项中的最低数据完整性 |
+| `createTime` | 任务创建时间 |
+
+### 8.2 检测项字段
+
+| 字段 | 说明 |
+| --- | --- |
+| `itemId` | 检测项 ID |
+| `itemKey` | 检测项唯一键 |
+| `indicatorCode` | 指标编码 |
+| `indicatorName` | 指标名称 |
+| `harmonicOrder` | 谐波次数；聚合检测项为空 |
+| `hasData` | 当前检测项是否存在任意数据 |
+| `expectedPointCount` | 期望点数 |
+| `actualPointCount` | 实际点数 |
+| `missingPointCount` | 缺失点数 |
+| `dataIntegrity` | 数据完整性数值 |
+| `dataIntegrityText` | 数据完整性文本 |
+| `abnormal` | 指标值大小关系是否异常 |
+| `abnormalPointCount` | 指标值大小关系异常点数 |
+| `harmonicParityAbnormal` | 谐波奇偶关系是否异常 |
+| `harmonicParityAbnormalPointCount` | 谐波奇偶关系异常点数 |
+| `statSummaries` | 各统计类型缺数摘要 |
+| `statDetails` | 兼容字段；明细建议通过 `/item-detail` 按需查询 |
+
+### 8.3 检测项明细字段
+
+| 字段 | 说明 |
+| --- | --- |
+| `itemId` | 检测项 ID |
+| `detailType` | 明细类型：`SEGMENT`、`VALUE_ORDER`、`HARMONIC_PARITY` |
+| `statType` | 统计类型；未传入或当前明细类型不按统计类型过滤时为空 |
+| `pageNum` | 当前页码；未启用分页时为空 |
+| `pageSize` | 每页条数；未启用分页时为空 |
+| `total` | 当前查询条件下的总明细数；未启用分页时为空 |
+| `segments` | 缺数连续区间，仅 `SEGMENT` 查询返回数据 |
+| `valueOrderDetails` | 指标值大小关系异常点，仅 `VALUE_ORDER` 查询返回数据 |
+| `harmonicParityDetails` | 谐波奇偶关系异常点，仅 `HARMONIC_PARITY` 查询返回数据 |
+
+## 9. 常见错误场景
+
+| 场景 | 后端提示 |
+| --- | --- |
+| 新增时 `lineId` 为空 | `监测点 ID 不能为空` |
+| 新增时 `indicatorCodes` 为空 | `指标不能为空` |
+| 新增时开始时间为空 | `开始时间不能为空` |
+| 新增时结束时间为空 | `结束时间不能为空` |
+| 开始时间大于结束时间 | `开始时间不能大于结束时间` |
+| 时间格式不正确 | `时间格式不正确，仅支持 yyyy-MM-dd HH:mm:ss` |
+| 监测点不存在或不可用 | `监测点不存在或不可用` |
+| 指标编码不支持 | `稳态指标不支持：xxx` |
+| 任务不存在或已删除 | `数据校验任务不存在` |
+| 检测项不存在或已删除 | `数据校验检测项不存在` |
+| 删除时任务 ID 为空 | `数据校验任务 ID 不能为空` |
+| 删除时任务不存在或已删除 | `数据校验任务不存在或已删除` |
+| 明细类型为空 | `明细类型不能为空` |
+| 明细类型不支持 | `明细类型不支持：xxx` |
+
+## 10. 调试流程建议
+
+1. 调用 `/steady/data-view/ledger-tree` 获取可用监测点，取叶子节点 `lineId`。
+2. 调用 `/steady/data-view/indicator-tree` 获取可用指标编码。
+3. 调用 `/steady/data-view/checksquare/create` 新增校验任务。
+4. 使用返回的 `taskId` 调用 `/steady/data-view/checksquare/detail` 查看任务详情和检测项列表。
+5. 使用 `items[].itemId` 调用 `/steady/data-view/checksquare/item-detail` 查看缺数区间或异常点明细。
+6. 调用 `/steady/data-view/checksquare/query` 验证任务已落库，并按监测点、指标、时间和异常状态筛选历史记录。
+7. 调用 `/steady/data-view/checksquare/delete` 删除任务后，再调用 `/query`、`/detail` 验证任务已不可见。
+
+## 11. 环境依赖
+
+- MySQL：需要已初始化 4 张 `steady_checksquare_*` 结果表。
+- InfluxDB：新增校验任务时需要可访问 `steady.influxdb` 配置的时序库。
+- 台账：新增校验任务时需要 `lineId` 能在台账中解析到监测点路径和统计间隔。
+- 指标目录：`indicatorCodes` 必须来自后端趋势指标目录。
+
+