ClientApps/CN_Tool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
38f910fccd3f4ee505627cf56382c9175620da03
CN_Tool/event/event-list/API_DEBUG.md

318 lines
11 KiB
Markdown
Raw Normal View History

我叫圣文
2026-05-15 16:37:22 +08:00
# 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` 实际定义和前端现有调用约定为准。
Reference in New Issue Copy Permalink