# 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` 实际定义和前端现有调用约定为准。