ClientApps/CN_Tool

Fork 0

Files

yexb 90219a3daf 我叫圣文

2026-05-15 16:37:22 +08:00

11 KiB

Raw Blame History

event-list API 调试文档

1. 基础信息

模块：event/event-list
控制器：EventListController
接口前缀：/event/list
本地默认地址：http://localhost:18192
Content-Type：application/json
认证：除 /admin/login、/admin/getPublicKey、Swagger 资源外，请求需要携带登录后的 Authorization 头。

Authorization: Bearer <accessToken>

说明：

event-list 当前提供暂态事件分页查询、详情查询和导出能力。
事件数据来自 r_mp_event_detail。
工程、项目、设备、监测点名称由 tools/add-ledger 内部服务按监测点 ID 批量补齐。
本文示例中的业务数据为调试示例，实际值以数据库为准。

2. 通用响应

分页和详情接口统一返回 HttpResult 包装结果。外层字段由公共组件序列化，常见结构如下：

{
  "code": "000000",
  "message": "成功",
  "data": {}
}

调试时重点查看：

code：业务响应码。
message：业务响应消息。
data：接口返回数据。

导出接口直接返回 Excel 文件流，不返回 HttpResult JSON。

3. 分页查询暂态事件列表

3.1 接口信息

路径：POST /event/list/transient/page
完整地址：http://localhost:18192/event/list/transient/page
控制器方法：EventListController#pageTransientEvents
服务方法：EventListService#pageTransientEvents
返回：HttpResult<Page<EventListVO>>
默认排序：start_time DESC, event_id DESC

3.2 请求示例

{
  "pageNum": 1,
  "pageSize": 10,
  "startTimeStart": "2026-05-01 00:00:00",
  "startTimeEnd": "2026-05-09 23:59:59",
  "eventType": "VOLTAGE_SAG",
  "phase": "A",
  "eventDescribe": "暂降",
  "durationMin": 0.02,
  "durationMax": 10,
  "featureAmplitudeMin": 10,
  "featureAmplitudeMax": 90,
  "fileFlag": 1,
  "dealFlag": 0,
  "lineIds": [
    "line-001"
  ],
  "engineeringName": "示例工程",
  "projectName": "示例项目",
  "equipmentName": "示例设备",
  "lineName": "示例测点"
}

分页字段继承公共 BaseParam，调试时按项目现有分页参数约定传入。示例使用 pageNum、pageSize。

3.3 请求字段

字段	类型	必填	说明
`pageNum`	Number	否	页码，来自公共分页参数
`pageSize`	Number	否	每页条数，来自公共分页参数
`startTimeStart`	String	否	发生时刻开始，格式 `yyyy-MM-dd HH:mm:ss`
`startTimeEnd`	String	否	发生时刻结束，格式 `yyyy-MM-dd HH:mm:ss`
`eventType`	String	否	事件类型，对应 `r_mp_event_detail.event_type`
`phase`	String	否	相别，对应 `r_mp_event_detail.phase`
`eventDescribe`	String	否	事件描述关键字，按 `LIKE` 查询
`durationMin`	Number	否	持续时间下限，单位秒
`durationMax`	Number	否	持续时间上限，单位秒
`featureAmplitudeMin`	Number	否	暂降/暂升幅值下限
`featureAmplitudeMax`	Number	否	暂降/暂升幅值上限
`fileFlag`	Number	否	波形文件状态：`0` 未招，`1` 已招
`dealFlag`	Number	否	处理状态：`0` 未处理，`1` 已处理，`2` 已处理无结果，`3` 计算失败
`lineIds`	Array	否	监测点 ID 列表，最多 1000 个
`engineeringName`	String	否	工程名称关键字，通过 `add-ledger` 反查监测点
`projectName`	String	否	项目名称关键字，通过 `add-ledger` 反查监测点
`equipmentName`	String	否	设备名称关键字，通过 `add-ledger` 反查监测点
`lineName`	String	否	监测点名称关键字，通过 `add-ledger` 反查监测点

时间字段支持以下输入格式：

yyyy-MM-dd HH:mm:ss
yyyy-MM-dd HH:mm:ss.SSS
yyyy-MM-dd'T'HH:mm:ss
yyyy-MM-dd'T'HH:mm:ss.SSS

如果不传 startTimeStart，后端默认取当前月 1 日 00:00:00。如果不传 startTimeEnd，后端默认取当前时间。

3.4 响应示例

{
  "code": "000000",
  "message": "成功",
  "data": {
    "records": [
      {
        "eventId": "event-001",
        "measurementPointId": "line-001",
        "eventType": "VOLTAGE_SAG",
        "equipmentName": "示例设备",
        "engineeringName": "示例工程",
        "projectName": "示例项目",
        "startTime": "2026-05-09 10:20:30",
        "lineName": "示例测点",
        "eventDescribe": "电压暂降",
        "sagsource": "上游",
        "phase": "A",
        "duration": 0.12,
        "featureAmplitude": 65.5,
        "wavePath": "D:/wave/event-001.cfg",
        "fileFlag": 1,
        "dealFlag": 0,
        "createTime": "2026-05-09 10:21:00"
      }
    ],
    "total": 1,
    "size": 10,
    "current": 1,
    "pages": 1
  }
}

Page 对象可能包含 MyBatis-Plus 的其他分页字段，调试时主要关注 records、total、size、current、pages。

3.5 curl 示例

curl.exe -X POST "http://localhost:18192/event/list/transient/page" `
  -H "Content-Type: application/json" `
  -H "Authorization: Bearer <accessToken>" `
  -d "{\"pageNum\":1,\"pageSize\":10,\"startTimeStart\":\"2026-05-01 00:00:00\",\"startTimeEnd\":\"2026-05-09 23:59:59\",\"eventDescribe\":\"暂降\"}"

4. 查询暂态事件详情

4.1 接口信息

路径：GET /event/list/transient/{eventId}
完整地址：http://localhost:18192/event/list/transient/{eventId}
控制器方法：EventListController#getTransientEventDetail
服务方法：EventListService#getTransientEventDetail
返回：HttpResult<EventListVO>

4.2 请求参数

参数	位置	类型	必填	说明
`eventId`	Path	String	是	暂态事件 ID，对应 `r_mp_event_detail.event_id`

4.3 响应示例

{
  "code": "000000",
  "message": "成功",
  "data": {
    "eventId": "event-001",
    "measurementPointId": "line-001",
    "eventType": "VOLTAGE_SAG",
    "equipmentName": "示例设备",
    "engineeringName": "示例工程",
    "projectName": "示例项目",
    "startTime": "2026-05-09 10:20:30",
    "lineName": "示例测点",
    "eventDescribe": "电压暂降",
    "sagsource": "上游",
    "phase": "A",
    "duration": 0.12,
    "featureAmplitude": 65.5,
    "wavePath": "D:/wave/event-001.cfg",
    "fileFlag": 1,
    "dealFlag": 0,
    "createTime": "2026-05-09 10:21:00"
  }
}

4.4 curl 示例

curl.exe -X GET "http://localhost:18192/event/list/transient/event-001" `
  -H "Authorization: Bearer <accessToken>"

5. 导出暂态事件列表

5.1 接口信息

路径：POST /event/list/transient/export
完整地址：http://localhost:18192/event/list/transient/export
控制器方法：EventListController#exportTransientEvents
服务方法：EventListService#exportTransientEvents
返回：Excel 文件流
文件名：暂态事件列表.xlsx
Sheet 名称：暂态事件列表

导出复用分页查询的筛选条件，但不使用分页结果。当前同步导出最多允许 5000 条，超过时返回业务错误。

5.2 请求示例

{
  "startTimeStart": "2026-05-01 00:00:00",
  "startTimeEnd": "2026-05-09 23:59:59",
  "eventDescribe": "暂降",
  "fileFlag": 1
}

5.3 导出字段

Excel 列名	响应字段	说明
设备名称	`equipmentName`	由 `add-ledger` 按监测点补齐
工程名称	`engineeringName`	由 `add-ledger` 按监测点补齐
项目名称	`projectName`	由 `add-ledger` 按监测点补齐
发生时刻	`startTime`	格式 `yyyy-MM-dd HH:mm:ss`
监测点名称	`lineName`	由 `add-ledger` 按监测点补齐
事件描述	`eventDescribe`	为空时使用 `eventType`
事件发生位置	`sagsource`	为空时返回 `-`
相别	`phase`	为空时返回 `-`
持续时间(s)	`duration`	单位秒
暂降/暂升幅值(%)	`featureAmplitude`	原值导出

5.4 curl 示例

curl.exe -X POST "http://localhost:18192/event/list/transient/export" `
  -H "Content-Type: application/json" `
  -H "Authorization: Bearer <accessToken>" `
  -d "{\"startTimeStart\":\"2026-05-01 00:00:00\",\"startTimeEnd\":\"2026-05-09 23:59:59\",\"eventDescribe\":\"暂降\"}" `
  -o "D:/temp/暂态事件列表.xlsx"

6. 返回字段说明

字段	类型	说明
`eventId`	String	事件 ID
`measurementPointId`	String	监测点 ID
`eventType`	String	事件类型
`equipmentName`	String	设备名称，台账缺失时为 `-`
`engineeringName`	String	工程名称，台账缺失时为 `-`
`projectName`	String	项目名称，台账缺失时为 `-`
`startTime`	String	发生时刻，格式 `yyyy-MM-dd HH:mm:ss`
`lineName`	String	监测点名称，台账缺失时为 `-`
`eventDescribe`	String	事件描述，空值时返回 `eventType`
`sagsource`	String	事件发生位置，空值时为 `-`
`phase`	String	相别，空值时为 `-`
`duration`	Number	持续时间，单位秒
`featureAmplitude`	Number	暂降/暂升幅值
`wavePath`	String	波形文件路径
`fileFlag`	Number	波形文件状态：`0` 未招，`1` 已招
`dealFlag`	Number	处理状态：`0` 未处理，`1` 已处理，`2` 已处理无结果，`3` 计算失败
`createTime`	String	创建时间，格式 `yyyy-MM-dd HH:mm:ss`

7. 常见错误场景

场景	后端提示
详情接口 `eventId` 为空	`事件 ID 不能为空`
详情数据不存在	`暂态事件不存在`
开始时间大于结束时间	`开始时间不能大于结束时间`
时间格式无法解析	`时间格式不正确，仅支持 yyyy-MM-dd HH:mm:ss`
持续时间下限大于上限	`持续时间下限不能大于上限`
幅值下限大于上限	`幅值下限不能大于上限`
`fileFlag` 不为 `0` 或 `1`	`波形文件状态只能是 0 或 1`
`dealFlag` 不在 `0-3` 范围内	`处理状态只能是 0、1、2、3`
`lineIds` 超过 1000 个	`监测点 ID 查询数量不能超过 1000 个`
台账关键字匹配监测点超过 1000 个	`台账检索匹配监测点过多，请缩小查询条件`
导出超过 5000 条	`导出数据超过 5000 条，请缩小查询条件`

未携带有效 Authorization 时，全局认证过滤器会返回 token 解析相关错误。

8. 调试注意事项

先登录获取 accessToken，再调试 event-list 接口。
分页查询不传时间范围时，后端默认查当前月 1 日到当前时间。
台账关键字筛选会先通过 add-ledger 查询匹配监测点，再查询事件表。
如果台账关键字命中范围过大，需要缩小工程、项目、设备或测点关键字。
导出接口建议始终传入明确时间范围，避免超过 5000 条限制。
如查询性能不稳定，可先检查是否已按需执行 event/event-list/src/main/resources/sql/event-list/event-list-index.sql 中的建议索引。

9. 当前限制

本文档只补充 API 调试说明，未改动业务代码。
当前未执行 mvn 编译、打包、测试或真实接口联调。
响应外层 HttpResult 字段以公共组件实际序列化结果为准。
分页参数字段以公共 BaseParam 实际定义和前端现有调用约定为准。

11 KiB Raw Blame History Unescape Escape