电网设备风险检测 API 文档

1. API 简介

本API旨在分析指定日期下，特定电网设备的SOE（Sequence of Events，事件顺序记录）数据，以评估其运行风险。API通过读取MySQL数据库中的SOE分区表，分析设备在一天内的所有事件记录，并根据一系列计算逻辑，最终判断出设备的故障严重等级。

核心计算逻辑：

根据事件的严重程度进行扣分，严重事件扣分更多。
未恢复的故障将导致最严重的扣分。
设备宕机（失压）时间越长，扣分越多。
最终分数将映射为四个风险等级：CRITICAL, HIGH, MEDIUM, LOW。

2. 请求说明

URL

API的请求地址为：

http://api.omhost.net/risk/v1.0/

请求方法：GET,POST

请求参数

参数名	必填	类型	说明
`dev_list`	是	String	设备的唯一标识符（OID）列表。多个OID之间请使用英文逗号 (`,`) 分隔。
`date`	否	String	指定查询的日期，格式为 `YYYY-MM-DD`。如果未提供此参数，API将默认使用当前服务器日期。该日期直接对应后台的SOE数据表（例如 `date=2025-07-17` 对应 `soe_data_20250717` 数据表）。如果指定日期的数据表不存在，API将返回空结果。

3. 请求示例

查询设备 OID 为 6473929362309121 和 6473925471698945 在 2025-07-17 当天的风险情况。

http://api.omhost.net/risk/v1.0/?dev_list=6473929362309121,6473925471698945&date=2025-07-17

4. 响应说明

API的响应结果为JSON格式。包含分析的总体信息以及每个设备的详细风险评估结果。

4.1 顶层结构字段

字段名	类型	说明
`date`	String	本次分析对应的日期。
`success`	Integer	请求是否成功。`1` 代表成功，其他值代表失败。
`devices`	Object	一个包含所有被分析设备详细信息的对象。对象的键（key）是设备的OID。
`analyzed_devices`	Integer	成功分析的设备数量。
`total_devices`	Integer	请求中包含的总设备数量。
`table_name`	String	本次分析实际查询的数据库表名。

4.2 设备详情字段 (`devices` 对象内)

字段名	类型	说明
`dev_oid`	String	设备的唯一标识符 OID。
`dev_name`	String	设备名称。
`st_name`	String	设备所属的站所名称。
`risk_level`	String	最终评估的风险等级。可能的值见下文“风险等级说明”。
`summary`	String	对设备当天状态的简要文字总结。
`event_count`	Integer	当天记录到的总事件数量，包含正常操作事件和故障事件。
`fault_count`	Integer	当天记录到的故障事件总数。此数值通常小于或等于 `event_count`。
`unrecovered_fault_count`	Integer	当天未恢复的故障数量。这是评估风险的关键指标。
`critical_fault_count`	Integer	严重（Critical）级别故障的数量。
`high_fault_count`	Integer	高（High）级别故障的数量。
`total_downtime_minutes`	String	当天设备总的宕机（失压）时长，单位为分钟。
`fault_details`	Array	一个包含所有故障详情的数组。如果无故障，则为空数组。
`health_score`	String	健康度分数。这是一个用于计算风险等级的内部中间变量，客户可忽略。

4.3 故障详情字段 (`fault_details` 数组内)

字段名	类型	说明
`fault_id`	Integer	故障的唯一ID。
`event_name`	String	触发故障的事件名称。
`start_time`	String	故障开始的时间。
`end_time`	String	故障结束的时间。如未结束此项为空。
`duration_minutes`	Integer	故障持续的时间。如未结束此项为空。
`severity`	String	该次故障的严重性，如 `HIGH`, `MEDIUM`。
`status`	String	故障当前的状态。`ACTIVE` 表示未恢复，`RECOVERED` 表示已恢复。

5. 响应示例

{
  "date": "2025-07-17",
  "success": 1,
  "devices": {
    "6473929362309121": {
      "fault_count": 3,
      "st_name": "110kV茂兰变",
      "critical_fault_count": 0,
      "total_downtime_minutes": "0.0",
      "dev_oid": "6473929362309121",
      "risk_level": "CRITICAL",
      "high_fault_count": 1,
      "summary": "存在3个未恢复故障，共记录3次故障事件",
      "event_count": 5,
      "unrecovered_fault_count": 3,
      "fault_details": [
        {
          "event_name": "终端电源交流失压",
          "start_time": "2025-07-10 03:27:20",
          "fault_id": "0",
          "severity": "HIGH",
          "status": "ACTIVE"
        },
        {
          "status": "ACTIVE",
          "severity": "MEDIUM",
          "fault_id": 1,
          "start_time": "2025-07-10 03:27:27",
          "event_name": "开关电源侧有压"
        },
        {
          "severity": "MEDIUM",
          "status": "ACTIVE",
          "fault_id": 2,
          "start_time": "2025-07-10 03:27:27",
          "event_name": "开关负荷侧有压"
        }
      ],
      "health_score": "0.0",
      "dev_name": "10kV茂洞线129号杆1290开关"
    },
    "6473925471698945": {
      "fault_count": 0,
      "st_name": "35kV塘边变",
      "critical_fault_count": 0,
      "dev_oid": "6473925471698945",
      "total_downtime_minutes": "0.0",
      "risk_level": "LOW",
      "high_fault_count": 0,
      "summary": "设备运行正常，无明显故障记录",
      "event_count": 2,
      "fault_details": [],
      "unrecovered_fault_count": 0,
      "health_score": "100.0",
      "dev_name": "10kV塘柏线新店支线1号杆A01开关"
    }
  },
  "analyzed_devices": 2,
  "total_devices": 2,
  "table_name": "soe_data_20250717"
}

6. 核心逻辑解析

6.1 风险等级 (Risk Level) 判定规则

API根据以下逻辑顺序确定最终的 risk_level：

风险等级	判定条件	状态描述
CRITICAL	`unrecovered_fault_count > 2` 或 `critical_fault_count > 2`	设备状态很差
HIGH	`health_score < 40` 或 `critical_fault_count > 0`	设备状态较差
MEDIUM	`health_score < 70` 或 `high_fault_count > 0`	设备状态一般
LOW	以上条件均不满足	设备状态良好/优秀

重要提示：存在未恢复的故障 (unrecovered_fault_count > 2) 将直接导致风险等级被评定为最高的 CRITICAL。

6.2 纳入分析的电气事件

本API专注于分析明确的电气事故表现。一些状态不明或属于正常操作范畴的事件（如“控制器上电标志”）将不被计为故障。下表列出了所有纳入故障分析的事件，并按照故障等级从高到低排序：

事件名称	触发条件 (SOE原始值)	故障等级	说明
开关事故总	值为 '1'	CRITICAL	影响供电连续性的严重故障。
过流I段动作	值为 '1'	CRITICAL	检测到快速过电流，为严重故障。
断路器分闸 (BR)	值为 '0'	CRITICAL	表示断路器处于断开状态，供电中断。
过负荷告警	值为 '1'	HIGH	可能导致停电的高风险故障。
终端电源交流失压	值为 '1'	HIGH	设备自身供电中断，可能导致功能异常。
Y时限失压闭锁	值为 '1'	MEDIUM	保护动作，但可能未造成停电。
闭锁总	值为 '1'	MEDIUM	通用闭锁告警，限制设备操作。
开关电源侧有压	值为 '0'	MEDIUM	表示电源侧失压，即上级线路停电。
开关负荷侧有压	值为 '0'	MEDIUM	表示负荷侧失压，即下级线路停电。