ClientApps/CN_Tool_client
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a6228faaba1d3e6c01b034d80bfb04132ae279f7
CN_Tool_client/frontend/src/views/steady/checksquare/check-square-api-debug_20260618.md

622 lines
19 KiB
Markdown
Raw Normal View History

refactor(steady): 重构稳态校验功能的合同验证逻辑 - 优化测量点对话框路径解析格式化 - 添加稳态校验重启API端点验证功能 - 更新创建参数类型定义支持可选lineId和lineIds数组 - 修复任务表格组件模板缩进格式问题 - 扩展任务表格列配置验证数组格式 - 添加任务表格仅对失败行显示重启操作功能 - 集成共享台账树组件发送选中叶节点监测点功能 - 添加多监测点创建参数构建支持 - 实现指标选择为空时全指标校验功能 - 添加预期项目数量计算功能 - 优化创建对话框指标选择标签防止输入框重置 - 添加任务表格树形选择滚动下拉菜单样式 - 实现页面创建流程调用创建API并轮询任务状态 - 添加创建结果面板加载状态和进度显示 - 实现页面重启流程确认调用重启API功能 - 优化汇总表格异常字段持久化支持 - 添加汇总表格监测点名称显示功能 - 优化详情面板按需加载项目详情 - 更新接口类型支持分页字段定义 - 优化ICD路径检查对话框标准映射参数传递 - 添加ICD记录导出SQL和JSON功能 - 扩展ICD路径API端点和类型定义 - 添加ICD路径参考选项和映射详情功能 - 重构ICD表格列显示移除激活和创建时间列 - 添加ICD映射详情对话框三个标签页功能 - 优化ICD映射详情JSON树形视图显示 - 更新ICD类型选项覆盖手动和上游标准状态
2026-06-18 16:35:06 +08:00
# 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`。
Reference in New Issue Copy Permalink