# 数据校验 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` 必须来自后端趋势指标目录。