Files

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

- 将数据校验中的缺失率相关字段替换为数据完整性字段
- 新增数据校验任务删除功能及相应测试
- 在tools模块中添加parse-pqdif子模块作为PQDIF文件解析预留
- 更新README文档以反映新的模块结构和依赖关系
- 优化数据校验统计汇总逻辑和测试覆盖
- 在entrance模块中集成parse-pqdif依赖
- 重构数据校验服务层实现和数据对象映射

2026-06-12 08:41:11 +08:00

16 KiB

Raw Blame History

数据校验 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

通用请求头：

Authorization: Bearer <token>
Content-Type: application/json

通用返回结构：

{
  "code": 200,
  "message": "success",
  "data": {}
}

实际 code、message 字段以项目公共 HttpResult 封装为准，下面示例重点展示 data 内容。

2. 查询数据校验历史记录

方法：POST
路径：/steady/data-view/checksquare/query
返回：HttpResult<Page<SteadyChecksquareTaskVO>>
说明：分页查询已落库的数据校验任务，按创建时间倒序返回。

请求示例：

{
  "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`

返回示例：

{
  "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 示例：

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。

请求示例：

{
  "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`

返回示例：

{
  "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 示例：

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`

请求示例：

GET /steady/data-view/checksquare/detail?taskId=8f7a4d6d1f3145a88b6f9d7a8e6c1001

返回示例：

{
  "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 示例：

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 查询缺数连续区间

请求示例：

GET /steady/data-view/checksquare/item-detail?itemId=0f4b6d6c3e9d400a902a2df101d10001&detailType=SEGMENT&statType=AVG

返回示例：

{
  "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 查询指标值大小关系异常明细

请求示例：

GET /steady/data-view/checksquare/item-detail?itemId=0f4b6d6c3e9d400a902a2df101d10001&detailType=VALUE_ORDER&pageNum=1&pageSize=20

返回示例：

{
  "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 查询谐波奇偶关系异常明细

请求示例：

GET /steady/data-view/checksquare/item-detail?itemId=0f4b6d6c3e9d400a902a2df101d10002&detailType=HARMONIC_PARITY&pageNum=1&pageSize=20

返回示例：

{
  "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 示例：

curl -X GET "http://localhost:18192/steady/data-view/checksquare/item-detail?itemId=0f4b6d6c3e9d400a902a2df101d10001&detailType=VALUE_ORDER" \
  -H "Authorization: Bearer <token>"

分页 cURL 示例：

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 批量逻辑删除数据校验任务，并同步将任务下检测项置为删除态。删除后历史查询不再返回该任务，详情和检测项明细会按不存在处理。

请求示例：

[
  "8f7a4d6d1f3145a88b6f9d7a8e6c1001"
]

请求字段：

字段	必填	说明
请求体	是	数据校验任务 ID 数组

返回示例：

true

cURL 示例：

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. 调试流程建议

调用 /steady/data-view/ledger-tree 获取可用监测点，取叶子节点 lineId。
调用 /steady/data-view/indicator-tree 获取可用指标编码。
调用 /steady/data-view/checksquare/create 新增校验任务。
使用返回的 taskId 调用 /steady/data-view/checksquare/detail 查看任务详情和检测项列表。
使用 items[].itemId 调用 /steady/data-view/checksquare/item-detail 查看缺数区间或异常点明细。
调用 /steady/data-view/checksquare/query 验证任务已落库，并按监测点、指标、时间和异常状态筛选历史记录。
调用 /steady/data-view/checksquare/delete 删除任务后，再调用 /query、/detail 验证任务已不可见。

11. 环境依赖

MySQL：需要已初始化 4 张 steady_checksquare_* 结果表。
InfluxDB：新增校验任务时需要可访问 steady.influxdb 配置的时序库。
台账：新增校验任务时需要 lineId 能在台账中解析到监测点路径和统计间隔。
指标目录：indicatorCodes 必须来自后端趋势指标目录。

16 KiB Raw Blame History Unescape Escape

数据校验 API 调试文档

1. 基础信息

2. 查询数据校验历史记录

3. 新增数据校验记录

4. 查询数据校验任务详情

5. 查询检测项明细

5.1 查询缺数连续区间

5.2 查询指标值大小关系异常明细

5.3 查询谐波奇偶关系异常明细

6. 删除数据校验任务

7. 校验规则说明

7.1 缺数校验

7.2 指标值大小关系校验

7.3 谐波奇偶关系校验

8. 字段说明

8.1 任务字段

8.2 检测项字段

8.3 检测项明细字段

9. 常见错误场景

10. 调试流程建议

11. 环境依赖

16 KiB

Raw Blame History