ClientApps/CN_Tool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1edee2bf1279e4a786d26fda9decdcb16ef4947a
CN_Tool/steady/steady-DataView/steady-checksquare-api-debug_20260610.md

523 lines
16 KiB
Markdown
Raw Normal View History

refactor(steady): 重构数据校验功能并新增PQDIF解析预留模块 - 将数据校验中的缺失率相关字段替换为数据完整性字段 - 新增数据校验任务删除功能及相应测试 - 在tools模块中添加parse-pqdif子模块作为PQDIF文件解析预留 - 更新README文档以反映新的模块结构和依赖关系 - 优化数据校验统计汇总逻辑和测试覆盖 - 在entrance模块中集成parse-pqdif依赖 - 重构数据校验服务层实现和数据对象映射
2026-06-12 08:41:11 +08:00
# 数据校验 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` 必须来自后端趋势指标目录。
Reference in New Issue Copy Permalink