318 lines
11 KiB
Markdown
318 lines
11 KiB
Markdown
# event-list API 调试文档
|
||
|
||
## 1. 基础信息
|
||
|
||
- 模块：`event/event-list`
|
||
- 控制器：`EventListController`
|
||
- 接口前缀：`/event/list`
|
||
- 本地默认地址：`http://localhost:18192`
|
||
- Content-Type：`application/json`
|
||
- 认证：除 `/admin/login`、`/admin/getPublicKey`、Swagger 资源外，请求需要携带登录后的 `Authorization` 头。
|
||
|
||
```text
|
||
Authorization: Bearer <accessToken>
|
||
```
|
||
|
||
说明：
|
||
|
||
- `event-list` 当前提供暂态事件分页查询、详情查询和导出能力。
|
||
- 事件数据来自 `r_mp_event_detail`。
|
||
- 工程、项目、设备、监测点名称由 `tools/add-ledger` 内部服务按监测点 ID 批量补齐。
|
||
- 本文示例中的业务数据为调试示例，实际值以数据库为准。
|
||
|
||
## 2. 通用响应
|
||
|
||
分页和详情接口统一返回 `HttpResult` 包装结果。外层字段由公共组件序列化，常见结构如下：
|
||
|
||
```json
|
||
{
|
||
"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 请求示例
|
||
|
||
```json
|
||
{
|
||
"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<String> | 否 | 监测点 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 响应示例
|
||
|
||
```json
|
||
{
|
||
"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 示例
|
||
|
||
```powershell
|
||
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 响应示例
|
||
|
||
```json
|
||
{
|
||
"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 示例
|
||
|
||
```powershell
|
||
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 请求示例
|
||
|
||
```json
|
||
{
|
||
"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 示例
|
||
|
||
```powershell
|
||
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` 实际定义和前端现有调用约定为准。
|