yexb
212b69060c
- 将数据校验中的缺失率相关字段替换为数据完整性字段 - 新增数据校验任务删除功能及相应测试 - 在tools模块中添加parse-pqdif子模块作为PQDIF文件解析预留 - 更新README文档以反映新的模块结构和依赖关系 - 优化数据校验统计汇总逻辑和测试覆盖 - 在entrance模块中集成parse-pqdif依赖 - 重构数据校验服务层实现和数据对象映射
523 lines
16 KiB
Markdown
523 lines
16 KiB
Markdown
# 数据校验 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` 必须来自后端趋势指标目录。
|
||
|
||
|