light-databoard/docs/fault_api.md

故障管理 API 文档

接口说明

本文档描述了数字灯网AI平台故障管理相关的 API 接口。所有接口都遵循 JSON-RPC 2.0 规范。

基础信息

• 基础URL: /api
• 请求方式: POST
• 数据格式: JSON
• 认证方式: Token (在请求头中携带)

通用响应格式

{
    "jsonrpc": "2.0",
    "result": {
    // 具体数据
    },
    "error": {
    "code": 200,
    "message": "success"
    }
}

错误码说明

错误码	说明
200	成功
400	请求参数错误
401	未授权
403	权限不足
404	资源不存在
500	服务器内部错误

API 列表

1. 获取故障列表

请求

{
    "jsonrpc": "2.0",
  "method": "fault.list",
  "params": {
    "page": 1,
    "pageSize": 10,
    "status": "all", // all, pending, processing, resolved
    "startTime": "2024-04-01 00:00:00",
    "endTime": "2024-04-26 23:59:59",
    "deviceId": "optional_device_id"
    }
}

响应

{
    "jsonrpc": "2.0",
    "result": {
    "total": 100,
    "items": [
      {
        "id": "fault_001",
        "deviceId": "device_001",
        "deviceName": "路灯-001",
        "type": "power_failure",
        "level": "high",
        "status": "pending",
        "description": "设备断电",
        "location": {
          "longitude": 120.123456,
          "latitude": 30.123456
        },
        "createTime": "2024-04-26 10:00:00",
        "updateTime": "2024-04-26 10:00:00"
      }
    ]
    },
    "error": {
    "code": 200,
    "message": "success"
    }
}

2. 获取故障详情

请求

{
    "jsonrpc": "2.0",
  "method": "fault.detail",
  "params": {
    "id": "fault_001"
    }
}

响应

{
    "jsonrpc": "2.0",
    "result": {
    "id": "fault_001",
    "deviceId": "device_001",
    "deviceName": "路灯-001",
    "type": "power_failure",
    "level": "high",
    "status": "pending",
    "description": "设备断电",
    "location": {
      "longitude": 120.123456,
      "latitude": 30.123456
    },
    "createTime": "2024-04-26 10:00:00",
    "updateTime": "2024-04-26 10:00:00",
    "history": [
      {
        "time": "2024-04-26 10:00:00",
        "action": "create",
        "operator": "system",
        "comment": "系统自动检测到故障"
      }
    ]
    },
    "error": {
    "code": 200,
    "message": "success"
    }
}

3. 更新故障状态

请求

{
    "jsonrpc": "2.0",
  "method": "fault.update",
  "params": {
    "id": "fault_001",
    "status": "processing",
    "comment": "开始处理故障"
    }
}

响应

{
    "jsonrpc": "2.0",
  "result": {
    "id": "fault_001",
    "status": "processing",
    "updateTime": "2024-04-26 10:30:00"
  },
    "error": {
    "code": 200,
    "message": "success"
    }
}

4. 获取故障统计

请求

{
    "jsonrpc": "2.0",
  "method": "fault.statistics",
  "params": {
    "startTime": "2024-04-01 00:00:00",
    "endTime": "2024-04-26 23:59:59",
    "type": "all" // all, daily, weekly, monthly
    }
}

响应

{
    "jsonrpc": "2.0",
    "result": {
    "total": 100,
    "pending": 20,
    "processing": 30,
    "resolved": 50,
    "byType": {
      "power_failure": 40,
      "communication_error": 30,
      "hardware_failure": 20,
      "other": 10
    },
    "byLevel": {
      "high": 30,
      "medium": 50,
      "low": 20
    },
    "trend": [
      {
        "date": "2024-04-26",
        "count": 10
            }
        ]
    },
    "error": {
    "code": 200,
    "message": "success"
    }
}

故障类型说明

类型	说明
power_failure	电源故障
communication_error	通信故障
hardware_failure	硬件故障
sensor_error	传感器故障
other	其他故障

故障等级说明

等级	说明
high	高优先级
medium	中优先级
low	低优先级

故障状态说明

状态	说明
pending	待处理
processing	处理中
resolved	已解决
closed	已关闭

注意事项

1. 所有时间字段使用 ISO 8601 格式
2. 分页参数 page 从 1 开始
3. 坐标使用 WGS84 坐标系
4. 故障 ID 格式为 "fault_" + 6位数字
5. 设备 ID 格式为 "device_" + 6位数字

更新日志

v1.0.0 (2024-04-26)

• 初始版本发布
• 实现基础故障管理功能
• 添加故障统计功能