light-databoard/docs/fault_api.md

# 故障管理 API 文档

## 接口说明

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

## 基础信息

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

## 通用响应格式

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

## 错误码说明

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

## API 列表

### 1. 获取故障列表

#### 请求

```json
{
    "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"
    }
}
```

#### 响应

```json
{
    "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. 获取故障详情

#### 请求

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

#### 响应

```json
{
    "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. 更新故障状态

#### 请求

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

#### 响应

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

### 4. 获取故障统计

#### 请求

```json
{
    "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
    }
}
```

#### 响应

```json
{
    "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)
- 初始版本发布
- 实现基础故障管理功能
- 添加故障统计功能