报警日志接口联调说明

1. 背景

Web 端已新增“报警日志记录”页面，用于查询、筛选、查看和确认报警记录。

当前前端页面入口：

• 路由：/system-tools/alarm-logs
• 页面文件：src/pages/alarm-logs/AlarmLogPage.vue
• 服务文件：src/services/alarmLogs.ts

本说明用于前后端联调，定义当前页面所需的最小接口集合、字段结构和返回格式。

2. 最小必需接口

当前页面最少依赖以下 2 个接口：

1. GET /api/alarm-logs
2. POST /api/alarm-logs/{id}/acknowledge

只要这两个接口可用，页面即可完成以下能力：

• 分页查询报警日志
• 按时间、级别、状态、来源、关键字筛选
• 查看报警详情
• 确认报警

3. 接口一：分页查询报警日志

3.1 接口定义

GET /api/alarm-logs

3.2 请求参数

建议使用 QueryString 方式传参。

参数名	类型	必填	说明
pageNumber	number	是	页码，从 1 开始
pageSize	number	是	每页条数，当前前端固定传 20
startTime	string	否	开始时间
endTime	string	否	结束时间
severity	string	否	报警级别
status	string	否	处理状态
source	string	否	报警来源
keyword	string	否	关键字搜索

3.3 枚举值说明

severity 可选值：

• critical：严重
• warning：警告
• info：提示

status 可选值：

• active：未处理
• acknowledged：已确认
• resolved：已恢复

source 可选值：

• robot：机器人
• system：系统
• charging：充电桩
• storage：库位

3.4 请求示例

GET /api/alarm-logs?pageNumber=1&pageSize=20&startTime=2026-05-21T00:00&endTime=2026-05-21T23:59&severity=critical&status=active&source=robot&keyword=RBT-01

3.5 返回格式

推荐返回结构如下：

{
  "success": true,
  "data": [
    {
      "id": "alarm-001",
      "alarmCode": "ALM-20260521-001",
      "title": "机器人急停触发",
      "content": "RBT-01 在入库线边站触发急停，需人工复位后恢复运行。",
      "severity": "critical",
      "status": "active",
      "source": "robot",
      "targetCode": "RBT-01",
      "targetName": "搬运机器人 01",
      "occurredAt": "2026-05-21T08:35:00+08:00",
      "acknowledged": false,
      "acknowledgedBy": null,
      "acknowledgedAt": null,
      "recoveredAt": null,
      "recoveryNote": null
    }
  ],
  "pageInfo": {
    "pageNumber": 1,
    "pageSize": 20,
    "totalCount": 87,
    "totalPages": 5
  }
}

3.6 字段说明

字段名	类型	说明
id	string	报警记录主键
alarmCode	string	报警编码
title	string	报警标题
content	string	报警内容
severity	string	报警级别
status	string	处理状态
source	string	报警来源
targetCode	string	对象编号，例如机器人编号、库位编号
targetName	string	对象名称
occurredAt	string	报警发生时间
acknowledged	boolean	是否已确认
acknowledgedBy	`string \	null`
acknowledgedAt	`string \	null`
recoveredAt	`string \	null`
recoveryNote	`string \	null`

3.7 前端兼容说明

前端当前兼容以下列表字段名：

• data
• Data
• items
• Items

前端当前兼容以下分页字段名：

• pageInfo
• PageInfo

但建议后端统一返回：

• 列表字段使用 data
• 分页字段使用 pageInfo

这样结构最清晰，也便于后续接口统一。

4. 接口二：确认报警

4.1 接口定义

POST /api/alarm-logs/{id}/acknowledge

4.2 路径参数

参数名	类型	必填	说明
id	string	是	报警记录主键

4.3 请求体

请求体可为空，也可以支持一个可选备注字段。

{
  "note": "值班人员已确认，等待现场处理"
}

4.4 返回格式

成功示例：

{
  "success": true,
  "message": "报警确认成功"
}

失败示例：

{
  "success": false,
  "message": "报警不存在或已被确认"
}

4.5 返回要求

建议约定如下：

• 成功返回 HTTP 200
• 业务失败返回 HTTP 4xx
• 返回体中统一提供 message

当前前端在错误场景下会优先读取：

• message
• Message

5. 时间格式要求

所有时间字段建议统一返回 ISO 8601 字符串，例如：

2026-05-21T08:35:00+08:00

推荐字段包括：

• occurredAt
• acknowledgedAt
• recoveredAt
• 查询参数中的 startTime
• 查询参数中的 endTime

这样可以避免前端解析时出现时区偏差问题。

6. 前端当前使用字段映射

前端页面当前实际依赖的数据结构如下：

type AlarmLogItem = {
  id: string
  alarmCode: string
  title: string
  content: string
  severity: 'critical' | 'warning' | 'info'
  status: 'active' | 'acknowledged' | 'resolved'
  source: 'robot' | 'system' | 'charging' | 'storage'
  targetCode: string
  targetName: string
  occurredAt: string
  acknowledged: boolean
  acknowledgedBy?: string
  acknowledgedAt?: string
  recoveredAt?: string
  recoveryNote?: string
}

7. 可选扩展接口

以下接口不是当前页面必需，但建议后续补齐。

7.1 获取报警详情

GET /api/alarm-logs/{id}

适用场景：

• 点击详情时，从后端拉取最新明细
• 展示比列表更完整的报警信息

可选增加字段：

• rawMessage
• deviceIp
• stackTrace
• operatorRecords

7.2 导出报警日志

POST /api/alarm-logs/export

请求体建议复用查询条件：

{
  "startTime": "2026-05-21T00:00",
  "endTime": "2026-05-21T23:59",
  "severity": "warning",
  "status": "resolved",
  "source": "robot",
  "keyword": "RBT"
}

适用场景：

• 后端导出 Excel
• 导出全量筛选结果，而不是仅当前页

8. 后端联调建议

建议后端优先按以下顺序实现：

1. 先实现 GET /api/alarm-logs
2. 再实现 POST /api/alarm-logs/{id}/acknowledge
3. 若需要增强，再补详情和导出接口

联调时建议先确保以下最小闭环：

1. 页面能查询到报警日志列表
2. 分页能正常工作
3. 筛选参数能正确生效
4. 点击“确认报警”后，状态从 active 变为 acknowledged
5. 再次刷新后状态保持一致

9. 可直接发给后端的简版说明

请补两个接口：

1. GET /api/alarm-logs
查询参数：
pageNumber, pageSize, startTime, endTime, severity, status, source, keyword

返回：
{
  "success": true,
  "data": [
    {
      "id": "string",
      "alarmCode": "string",
      "title": "string",
      "content": "string",
      "severity": "critical|warning|info",
      "status": "active|acknowledged|resolved",
      "source": "robot|system|charging|storage",
      "targetCode": "string",
      "targetName": "string",
      "occurredAt": "ISO时间字符串",
      "acknowledged": true,
      "acknowledgedBy": "string|null",
      "acknowledgedAt": "ISO时间字符串|null",
      "recoveredAt": "ISO时间字符串|null",
      "recoveryNote": "string|null"
    }
  ],
  "pageInfo": {
    "pageNumber": 1,
    "pageSize": 20,
    "totalCount": 0,
    "totalPages": 1
  }
}

2. POST /api/alarm-logs/{id}/acknowledge
请求体可为空，或支持：
{
  "note": "string"
}

成功返回：
{
  "success": true,
  "message": "报警确认成功"
}