# check-square API 调试文档

## 1. 模块说明

- 模块路径：`steady/check-square`
- 接口基础路径：`/steady/checksquare`
- 返回包装：接口统一返回 `HttpResult<T>`，调试时重点查看响应体中的业务数据字段 `data`。
- 时间格式：`yyyy-MM-dd HH:mm:ss`

本模块用于按监测点、时间范围和指标执行稳态数据校验，并提供任务列表、任务详情、检测项明细查询、失败任务重启和任务删除能力。当前标准支持单监测点和多监测点任务：单监测点可继续传 `lineId`，多监测点推荐传 `lineIds`。

## 2. 通用约定

### 2.1 请求头

| 名称 | 示例 | 说明 |
| --- | --- | --- |
| `Content-Type` | `application/json` | `POST` 请求使用 JSON 请求体 |
| `Authorization` | 登录态 Token | 如当前环境开启认证，需携带现有登录接口返回的认证信息 |

### 2.2 任务状态

| 值 | 说明 |
| --- | --- |
| `RUNNING` | 执行中 |
| `SUCCESS` | 执行成功 |
| `FAIL` | 执行失败 |

### 2.3 明细类型

| 值 | 说明 |
| --- | --- |
| `SEGMENT` | 连续性区间，包含正常区间和缺失区间 |
| `VALUE_ORDER` | 指标值大小关系异常明细 |
| `HARMONIC_PARITY` | 谐波奇偶关系异常明细 |

### 2.4 统计类型

| 值 | 说明 |
| --- | --- |
| `AVG` | 平均值 |
| `MAX` | 最大值 |
| `MIN` | 最小值 |
| `CP95` | CP95 值 |

## 3. 调试顺序建议

1. 调用 `POST /steady/checksquare/create`：按监测点列表、时间范围和指标列表创建或复用任务。
2. 读取 `/create` 返回的 `data.taskId`：该返回值是任务列表中的行信息。
3. 如果 `taskStatus=RUNNING`，轮询 `POST /steady/checksquare/query`，或稍后调用 `GET /steady/checksquare/detail` 查看任务详情。
4. 调用 `GET /steady/checksquare/detail`：用 `taskId` 查询任务下的检测项。
5. 读取 `/detail` 返回的 `items[].itemId`：按检测项继续查询连续性区间或异常明细。
6. 调用 `GET /steady/checksquare/item-detail`：按 `itemId + detailType` 查询具体明细。
7. 任务失败后如需重新执行，调用 `POST /steady/checksquare/restart`。
8. 需要清理任务时调用 `POST /steady/checksquare/delete`。

注意：旧的获取或创建兼容接口已移除。创建或复用任务的逻辑已经合并到 `/create` 中。

## 4. 创建或复用任务

### 4.1 接口

`POST /steady/checksquare/create`

### 4.2 行为说明

接口开始执行前，会先按 `lineIds + timeStart + timeEnd` 查询是否存在未删除任务：

- 已存在：直接返回该任务的任务列表行信息。
- 不存在：创建 `RUNNING` 任务并立即返回任务列表行信息，后台继续执行校验；任务完成后状态更新为 `SUCCESS`，失败时更新为 `FAIL`。

`lineIds` 会去重并清理空字符串。若未传 `lineIds`，后端会兼容读取 `lineId` 并转换为单元素监测点列表。返回对象为 `SteadyChecksquareTaskVO`。

### 4.3 请求字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `lineId` | `String` | 条件必填 | 单监测点 ID；当 `lineIds` 为空时使用 |
| `lineIds` | `Array<String>` | 条件必填 | 监测点 ID 列表；多监测点推荐使用该字段 |
| `indicatorCodes` | `Array<String>` | 是 | 指标编码列表 |
| `timeStart` | `String` | 是 | 开始时间，格式 `yyyy-MM-dd HH:mm:ss` |
| `timeEnd` | `String` | 是 | 结束时间，格式 `yyyy-MM-dd HH:mm:ss` |

`lineId` 与 `lineIds` 至少传一个；`indicatorCodes` 是数组，不要传成单个字符串。

### 4.4 请求示例

单监测点兼容写法：

```http
POST /steady/checksquare/create
Content-Type: application/json
```

```json
{
  "lineId": "LINE_001",
  "indicatorCodes": ["VOLTAGE_A", "CURRENT_A"],
  "timeStart": "2026-06-18 00:00:00",
  "timeEnd": "2026-06-18 01:00:00"
}
```

多监测点标准写法：

```json
{
  "lineIds": ["LINE_001", "LINE_002"],
  "indicatorCodes": ["VOLTAGE_A", "CURRENT_A"],
  "timeStart": "2026-06-18 00:00:00",
  "timeEnd": "2026-06-18 01:00:00"
}
```

### 4.5 响应字段 `data`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `taskId` | `String` | 任务 ID |
| `taskNo` | `String` | 任务编号 |
| `lineId` | `String` | 任务首个监测点 ID；兼容旧页面字段 |
| `lineIds` | `Array<String>` | 本次任务的监测点 ID 列表 |
| `lineName` | `String` | 监测点名称；多监测点时为多个名称拼接结果 |
| `timeStart` | `String` | 开始时间 |
| `timeEnd` | `String` | 结束时间 |
| `intervalMinutes` | `Integer` | 统计间隔，单位分钟 |
| `taskStatus` | `String` | 任务状态：`RUNNING`、`SUCCESS`、`FAIL` |
| `itemCount` | `Integer` | 检测项数量 |
| `abnormalItemCount` | `Integer` | 异常检测项数量 |
| `minDataIntegrity` | `BigDecimal` | 最低数据完整性，0 到 1 的小数 |
| `createTime` | `String` | 创建时间 |

### 4.6 响应示例

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "1812345678901234567",
    "taskNo": "CS202606180001",
    "lineId": "LINE_001",
    "lineIds": ["LINE_001", "LINE_002"],
    "lineName": "1号监测点,2号监测点",
    "timeStart": "2026-06-18 00:00:00",
    "timeEnd": "2026-06-18 01:00:00",
    "intervalMinutes": 1,
    "taskStatus": "RUNNING",
    "itemCount": 0,
    "abnormalItemCount": 0,
    "minDataIntegrity": 0.000000,
    "createTime": "2026-06-18 09:30:00"
  }
}
```

## 5. 查询任务列表

### 5.1 接口

`POST /steady/checksquare/query`

### 5.2 请求字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `lineId` | `String` | 否 | 监测点 ID；后端按任务的 `lineIds` 检索文本匹配 |
| `indicatorCode` | `String` | 否 | 指标编码；后端按任务的指标编码检索文本匹配 |
| `timeStart` | `String` | 否 | 检测开始时间，格式 `yyyy-MM-dd HH:mm:ss` |
| `timeEnd` | `String` | 否 | 检测结束时间，格式 `yyyy-MM-dd HH:mm:ss` |
| `hasAbnormal` | `Boolean` | 否 | 是否存在异常；传 `true` 时仅查询异常检测项数量大于 0 的任务 |
| `pageNum` | `Integer` | 否 | 页码 |
| `pageSize` | `Integer` | 否 | 每页条数 |

`indicatorCode` 是单个字符串，用于历史任务筛选；和 `/create` 的 `indicatorCodes` 数组不同。

### 5.3 请求示例

```http
POST /steady/checksquare/query
Content-Type: application/json
```

```json
{
  "lineId": "LINE_001",
  "indicatorCode": "VOLTAGE_A",
  "timeStart": "2026-06-18 00:00:00",
  "timeEnd": "2026-06-18 23:59:59",
  "hasAbnormal": true,
  "pageNum": 1,
  "pageSize": 10
}
```

### 5.4 响应说明

`data` 为 MyBatis-Plus `Page<SteadyChecksquareTaskVO>` 分页对象，常用字段如下：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `records` | `Array<Object>` | 任务列表，每项字段同 `/create` 返回的 `SteadyChecksquareTaskVO` |
| `total` | `Long` | 总记录数 |
| `size` | `Long` | 每页条数 |
| `current` | `Long` | 当前页码 |
| `pages` | `Long` | 总页数 |

### 5.5 响应示例

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "records": [
      {
        "taskId": "1812345678901234567",
        "taskNo": "CS202606180001",
        "lineId": "LINE_001",
        "lineIds": ["LINE_001", "LINE_002"],
        "lineName": "1号监测点,2号监测点",
        "timeStart": "2026-06-18 00:00:00",
        "timeEnd": "2026-06-18 01:00:00",
        "intervalMinutes": 1,
        "taskStatus": "SUCCESS",
        "itemCount": 4,
        "abnormalItemCount": 1,
        "minDataIntegrity": 0.985000,
        "createTime": "2026-06-18 09:30:00"
      }
    ],
    "total": 1,
    "size": 10,
    "current": 1,
    "pages": 1
  }
}
```

## 6. 查询任务详情

### 6.1 接口

`GET /steady/checksquare/detail?taskId={taskId}`

### 6.2 请求参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `taskId` | `String` | 是 | 任务 ID |

### 6.3 请求示例

```http
GET /steady/checksquare/detail?taskId=1812345678901234567
```

### 6.4 响应字段 `data`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `taskId` | `String` | 任务 ID |
| `taskNo` | `String` | 任务编号 |
| `lineId` | `String` | 任务首个监测点 ID；兼容旧页面字段 |
| `lineIds` | `Array<String>` | 本次任务的监测点 ID 列表 |
| `lineName` | `String` | 监测点名称 |
| `timeStart` | `String` | 开始时间 |
| `timeEnd` | `String` | 结束时间 |
| `intervalMinutes` | `Integer` | 统计间隔，单位分钟 |
| `items` | `Array<Object>` | 检测项列表 |

### 6.5 检测项字段 `items[]`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `itemId` | `String` | 检测项 ID，用于查询明细 |
| `itemKey` | `String` | 检测项唯一键 |
| `lineId` | `String` | 当前检测项所属监测点 ID |
| `lineName` | `String` | 当前检测项所属监测点名称 |
| `indicatorCode` | `String` | 指标编码 |
| `indicatorName` | `String` | 指标名称 |
| `harmonicOrder` | `Integer` | 谐波次数；非谐波或聚合项可为空 |
| `intervalMinutes` | `Integer` | 当前检测项统计间隔，单位分钟 |
| `hasData` | `Boolean` | 时间范围内是否存在任意数据 |
| `expectedPointCount` | `Integer` | 期望点数 |
| `actualPointCount` | `Integer` | 实际点数 |
| `missingPointCount` | `Integer` | 缺失点数 |
| `dataIntegrity` | `BigDecimal` | 数据完整性，0 到 1 的小数 |
| `dataIntegrityText` | `String` | 数据完整性文本 |
| `abnormal` | `Boolean` | 指标值大小关系是否异常 |
| `abnormalPointCount` | `Integer` | 指标值大小关系异常点数 |
| `abnormalDetails` | `Array<Object>` | 指标值大小关系异常明细摘要 |
| `harmonicParityAbnormal` | `Boolean` | 谐波奇偶关系是否异常 |
| `harmonicParityAbnormalPointCount` | `Integer` | 谐波奇偶关系异常点数 |
| `harmonicParityAbnormalDetails` | `Array<Object>` | 谐波奇偶关系异常明细摘要 |
| `statSummaries` | `Array<Object>` | 统计类型摘要 |
| `statDetails` | `Array<Object>` | 统计类型明细 |

### 6.6 统计摘要字段 `statSummaries[]`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `statType` | `String` | 统计类型：`AVG`、`MAX`、`MIN`、`CP95` |
| `supported` | `Boolean` | 是否支持该统计类型 |
| `hasData` | `Boolean` | 是否存在数据 |
| `expectedPointCount` | `Integer` | 期望点数 |
| `actualPointCount` | `Integer` | 实际点数 |
| `missingPointCount` | `Integer` | 缺失点数 |
| `dataIntegrity` | `BigDecimal` | 数据完整性 |
| `dataIntegrityText` | `String` | 数据完整性文本 |

### 6.7 响应示例

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "1812345678901234567",
    "taskNo": "CS202606180001",
    "lineId": "LINE_001",
    "lineIds": ["LINE_001", "LINE_002"],
    "lineName": "1号监测点,2号监测点",
    "timeStart": "2026-06-18 00:00:00",
    "timeEnd": "2026-06-18 01:00:00",
    "intervalMinutes": 1,
    "items": [
      {
        "itemId": "1812345678901234568",
        "itemKey": "LINE_001:VOLTAGE_A",
        "lineId": "LINE_001",
        "lineName": "1号监测点",
        "indicatorCode": "VOLTAGE_A",
        "indicatorName": "A相电压",
        "harmonicOrder": null,
        "intervalMinutes": 1,
        "hasData": true,
        "expectedPointCount": 60,
        "actualPointCount": 59,
        "missingPointCount": 1,
        "dataIntegrity": 0.983333,
        "dataIntegrityText": "98.33%",
        "abnormal": true,
        "abnormalPointCount": 1,
        "abnormalDetails": [],
        "harmonicParityAbnormal": false,
        "harmonicParityAbnormalPointCount": 0,
        "harmonicParityAbnormalDetails": [],
        "statSummaries": [
          {
            "statType": "AVG",
            "supported": true,
            "hasData": true,
            "expectedPointCount": 60,
            "actualPointCount": 59,
            "missingPointCount": 1,
            "dataIntegrity": 0.983333,
            "dataIntegrityText": "98.33%"
          }
        ],
        "statDetails": []
      }
    ]
  }
}
```

## 7. 查询检测项明细

### 7.1 接口

`GET /steady/checksquare/item-detail`

### 7.2 请求参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `itemId` | `String` | 是 | 检测项 ID |
| `detailType` | `String` | 是 | 明细类型：`SEGMENT`、`VALUE_ORDER`、`HARMONIC_PARITY` |
| `statType` | `String` | 否 | 统计类型；查询统计类型连续性或谐波奇偶明细时使用 |
| `pageNum` | `Integer` | 否 | 页码；和 `pageSize` 同时为正数时启用分页 |
| `pageSize` | `Integer` | 否 | 每页条数；和 `pageNum` 同时为正数时启用分页 |

### 7.3 请求示例

查询连续性区间：

```http
GET /steady/checksquare/item-detail?itemId=1812345678901234568&detailType=SEGMENT&pageNum=1&pageSize=10
```

查询大小关系异常：

```http
GET /steady/checksquare/item-detail?itemId=1812345678901234568&detailType=VALUE_ORDER&pageNum=1&pageSize=10
```

查询谐波奇偶关系异常：

```http
GET /steady/checksquare/item-detail?itemId=1812345678901234568&detailType=HARMONIC_PARITY&statType=AVG&pageNum=1&pageSize=10
```

### 7.4 响应字段 `data`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `itemId` | `String` | 检测项 ID |
| `lineId` | `String` | 当前检测项所属监测点 ID |
| `lineName` | `String` | 当前检测项所属监测点名称 |
| `detailType` | `String` | 明细类型 |
| `statType` | `String` | 统计类型 |
| `pageNum` | `Integer` | 当前页码；未分页查询时为空 |
| `pageSize` | `Integer` | 每页条数；未分页查询时为空 |
| `total` | `Long` | 总记录数；未分页查询时为空 |
| `segments` | `Array<Object>` | 连续性区间，`detailType=SEGMENT` 时查看 |
| `valueOrderDetails` | `Array<Object>` | 指标值大小关系异常明细，`detailType=VALUE_ORDER` 时查看 |
| `harmonicParityDetails` | `Array<Object>` | 谐波奇偶关系异常明细，`detailType=HARMONIC_PARITY` 时查看 |

### 7.5 连续性区间字段 `segments[]`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `startTime` | `String` | 区间开始时间 |
| `endTime` | `String` | 区间结束时间 |
| `status` | `String` | 区间状态：`NORMAL`、`MISSING` |
| `harmonicOrder` | `Integer` | 谐波次数 |
| `missingPointCount` | `Integer` | 缺失点数 |
| `durationMinutes` | `Integer` | 持续时长，单位分钟 |

### 7.6 大小关系异常字段 `valueOrderDetails[]`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `time` | `String` | 异常点时间 |
| `phase` | `String` | 相别 |
| `harmonicOrder` | `Integer` | 谐波次数 |
| `maxValue` | `BigDecimal` | 最大值 |
| `minValue` | `BigDecimal` | 最小值 |
| `avgValue` | `BigDecimal` | 平均值 |
| `cp95Value` | `BigDecimal` | CP95 值 |

### 7.7 谐波奇偶关系异常字段 `harmonicParityDetails[]`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `time` | `String` | 异常点时间 |
| `phase` | `String` | 相别 |
| `statType` | `String` | 统计类型 |
| `evenHarmonicOrder` | `Integer` | 偶次谐波次数 |
| `evenValue` | `BigDecimal` | 偶次谐波值 |
| `oddHarmonicOrders` | `Array<Integer>` | 参与比较的奇次谐波次数 |
| `oddValues` | `Array<BigDecimal>` | 参与比较的奇次谐波值 |
| `oddMedianValue` | `BigDecimal` | 奇次谐波中位数 |
| `thresholdMultiplier` | `BigDecimal` | 异常阈值倍数 |

### 7.8 响应示例

连续性区间：

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "itemId": "1812345678901234568",
    "lineId": "LINE_001",
    "lineName": "1号监测点",
    "detailType": "SEGMENT",
    "statType": null,
    "pageNum": 1,
    "pageSize": 10,
    "total": 1,
    "segments": [
      {
        "startTime": "2026-06-18 00:10:00",
        "endTime": "2026-06-18 00:10:00",
        "status": "MISSING",
        "harmonicOrder": null,
        "missingPointCount": 1,
        "durationMinutes": 1
      }
    ],
    "valueOrderDetails": [],
    "harmonicParityDetails": []
  }
}
```

大小关系异常：

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "itemId": "1812345678901234568",
    "lineId": "LINE_001",
    "lineName": "1号监测点",
    "detailType": "VALUE_ORDER",
    "statType": null,
    "pageNum": 1,
    "pageSize": 10,
    "total": 1,
    "segments": [],
    "valueOrderDetails": [
      {
        "time": "2026-06-18 00:20:00",
        "phase": "A",
        "harmonicOrder": null,
        "maxValue": 231.12000000,
        "minValue": 228.45000000,
        "avgValue": 229.64000000,
        "cp95Value": 230.98000000
      }
    ],
    "harmonicParityDetails": []
  }
}
```

## 8. 重启失败任务

### 8.1 接口

`POST /steady/checksquare/restart?taskId={taskId}`

### 8.2 行为说明

- 仅允许重启 `taskStatus=FAIL` 的任务。
- 重启复用原任务记录，`taskId` 不变。
- 重启前会清理该任务旧的检测项、统计摘要和明细数据，避免重复结果键。
- 接口返回时任务状态已更新为 `RUNNING`；后台执行结束后更新为 `SUCCESS` 或 `FAIL`。

### 8.3 请求参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `taskId` | `String` | 是 | 失败任务 ID |

### 8.4 请求示例

```http
POST /steady/checksquare/restart?taskId=1812345678901234567
```

### 8.5 响应说明

响应 `data` 与 `/create` 的 `SteadyChecksquareTaskVO` 字段一致。

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "1812345678901234567",
    "taskNo": "CS202606180001",
    "lineId": "LINE_001",
    "lineIds": ["LINE_001", "LINE_002"],
    "lineName": "1号监测点,2号监测点",
    "timeStart": "2026-06-18 00:00:00",
    "timeEnd": "2026-06-18 01:00:00",
    "intervalMinutes": 1,
    "taskStatus": "RUNNING",
    "itemCount": 0,
    "abnormalItemCount": 0,
    "minDataIntegrity": 0.000000,
    "createTime": "2026-06-18 09:30:00"
  }
}
```

## 9. 删除任务

### 9.1 接口

`POST /steady/checksquare/delete`

### 9.2 请求字段

请求体直接传任务 ID 数组。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `taskIds` | `Array<String>` | 是 | 任务 ID 数组 |

### 9.3 请求示例

```http
POST /steady/checksquare/delete
Content-Type: application/json
```

```json
[
  "1812345678901234567"
]
```

### 9.4 响应示例

```json
{
  "code": 200,
  "msg": "success",
  "data": true
}
```

## 10. 常见调试注意事项

- `/create` 返回的是任务列表行信息，不是详情页完整数据。
- `/create` 如果命中已存在任务，会直接返回该任务，不会生成重复任务。
- 新标准推荐传 `lineIds`；`lineId` 仅作为单监测点兼容字段保留。
- `/query` 的 `lineId` 会匹配任务内的 `lineIds`，可用于筛选多监测点任务。
- `/detail` 需要使用 `/create`、`/restart` 或 `/query` 返回的 `taskId`。
- `/detail` 的任务级 `lineId` 是首个监测点，检测项级 `items[].lineId` 才是该检测项实际所属监测点。
- `/item-detail` 需要使用 `/detail` 返回的 `items[].itemId`。
- `/item-detail` 只有 `pageNum` 和 `pageSize` 同时为正数时才分页；否则返回全部匹配明细，分页字段为空。
- `/restart` 只允许重启失败任务，成功或执行中的任务调用会返回业务失败。
- `dataIntegrity` 是 0 到 1 的小数，展示百分比优先使用 `dataIntegrityText`。