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
yexb 92b7d3cd73 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

19 KiB
Raw Blame History

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 请求示例

单监测点兼容写法：

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

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

多监测点标准写法：

{
  "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 响应示例

{
  "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 请求示例

POST /steady/checksquare/query
Content-Type: application/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 响应示例

{
  "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 请求示例

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 响应示例

{
  "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 请求示例

查询连续性区间：

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

查询大小关系异常：

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

查询谐波奇偶关系异常：

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 响应示例

连续性区间：

{
  "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": []
  }
}

大小关系异常：

{
  "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 请求示例

POST /steady/checksquare/restart?taskId=1812345678901234567

8.5 响应说明

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

{
  "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 请求示例

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

[
  "1812345678901234567"
]

9.4 响应示例

{
  "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。