我叫圣文

2026-05-15 16:37:22 +08:00
parent 41c915d1df
commit 90219a3daf
52 changed files with 3315 additions and 5 deletions
--- a/event/event-list/API_DEBUG.md
+++ b/event/event-list/API_DEBUG.md
@@ -0,0 +1,317 @@
+# 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` 实际定义和前端现有调用约定为准。