# IntegrationGateway B 组接口文档

> **版本**: 1.0
> **日期**: 2026-06-04
> **基址**: `http://{host}:{port}`（默认 `http://localhost:5100`）
> **内容类型**: `application/json`（除标注外）
> **认证**: 可选 `X-Gateway-Key` 请求头（与 Gateway 段配置一致时生效）
> **通用错误码**: 见 §5

---

## 目录

1. [健康检查](#1-健康检查) — B1
2. [设备管理](#2-设备管理) — B2, B3, B3-sync
3. [视频与流媒体](#3-视频与流媒体) — B6a, B6b, 截图, B7
4. [IoT 实时数据](#4-iot-实时数据) — B4, B4-batch, B5
5. [告警管理](#5-告警管理) — B8, B9-confirm, B9-end
6. [录像查询](#6-录像查询)
7. [设备控制 (通用)](#7-设备控制-通用) — B10
8. [业务记录查询](#8-业务记录查询) — B11
9. [数据同步](#9-数据同步) — B12, B13
10. [错误代码](#10-错误代码)

---

## 1. 健康检查

### B1: 查询所有适配器健康状态

```
GET /api/gateway/health
```

**请求参数**: 无

**返回参数**:

| 字段 | 类型 | 说明 |
|------|------|------|
| `[].adapterCode` | string | 适配器编码，如 `Owl:main`、`MC4:31ku`、`KMS:main` |
| `[].displayName` | string | 人类可读的适配器名称 |
| `[].healthy` | bool | `true` = 适配器在线，`false` = 离线或不可达 |
| `[].capabilities` | object | 适配器能力声明 |

**capabilities 字段**:

| 字段 | 类型 | 说明 |
|------|------|------|
| `hasFlatDevices` | bool | 是否支持扁平设备列表 |
| `hasOwnDeviceTree` | bool | 是否支持层级对象树 |
| `hasStreams` | bool | 是否支持视频取流 |
| `hasPoints` | bool | 是否支持 IoT 实时点位 |
| `hasAlarms` | bool | 是否支持告警查询 |
| `hasRecordings` | bool | 是否支持录像查询 |

**返回示例**:
```json
[
  {
    "adapterCode": "Owl:main",
    "displayName": "Owl (Owl:main)",
    "healthy": true,
    "capabilities": { "hasFlatDevices": true, "hasStreams": true, "hasAlarms": true, "hasRecordings": true }
  }
]
```

---

## 2. 设备管理

### B2: 分页获取扁平设备列表

```
GET /api/gateway/devices?adapter={adapterCode}&page={page}&size={size}&keyword={keyword}
```

**请求参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|:--:|------|------|
| `adapter` | string | ✅ | — | 适配器编码，如 `Owl:main` |
| `page` | int | ❌ | 1 | 页码（从 1 开始） |
| `size` | int | ❌ | 20 | 每页条数 |
| `keyword` | string | ❌ | null | 设备名称模糊搜索 |

**返回参数**:

| 字段 | 类型 | 说明 |
|------|------|------|
| `items` | array | 设备列表 |
| `total` | int | 总设备数 |

**items[].StandardDevice**:

| 字段 | 类型 | 说明 |
|------|------|------|
| `sourceId` | string | 子系统设备原始 ID |
| `name` | string | 设备名称 |
| `category` | string | 设备种类（如 `硬盘录像机`、`摄像头`、`智能钥匙柜`、`钥匙位`） |
| `group` | string | 设备分组（`视频设备`/`IoT设备`/`门禁设备`） |
| `isParent` | bool | 是否父设备（含下级子设备） |
| `parentSourceId` | string? | 上级设备 SourceId |
| `isOnline` | bool | 是否在线 |
| `ipAddress` | string? | IP 地址 |
| `port` | int? | 端口号 |
| `extra` | object? | 子系统特有扩展属性 |

**返回示例**:
```json
{
  "items": [
    { "sourceId": "locker_25", "name": "10位智能公共钥匙柜", "category": "智能钥匙柜", "group": "门禁设备", "isParent": true, "isOnline": true },
    { "sourceId": "lockhole_25_1", "name": "仓库大门钥匙", "category": "钥匙位", "group": "门禁设备", "isParent": false, "isOnline": true, "parentSourceId": "locker_25" }
  ],
  "total": 11
}
```

### B3: 获取层级对象树

```
GET /api/gateway/tree?adapter={adapterCode}
```

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `adapter` | string | ✅ | 适配器编码，如 `MC4:31ku` |

**返回参数**: `DeviceTreeNode[]`

| 字段 | 类型 | 说明 |
|------|------|------|
| `sourceId` | string | 节点 ID |
| `name` | string | 节点名称 |
| `tag` | string | 节点标签（如 `区域`/`设备组`/`IoT设备`） |
| `type` | int | 节点类型：1=父节点, 0=叶子节点 |
| `children` | array | 子节点列表（递归） |
| `option` | object? | 扩展配置 |

### B3-sync: 手动触发设备同步

```
POST /api/gateway/devices/sync?adapter={adapterCode}
```

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `adapter` | string | ✅ | 适配器编码 |

**返回参数**:

| 字段 | 类型 | 说明 |
|------|------|------|
| `deviceCount` | int | 同步设备数（扁平设备） |
| `nodeCount` | int | 同步节点数（对象树） |
| `message` | string | 同步结果描述 |

---

## 3. 视频与流媒体

### B6a: 获取实时流地址

```
GET /api/gateway/streams/{adapter}/{deviceId}/live
```

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `adapter` | string | ✅ | 适配器编码，如 `Owl:main` |
| `deviceId` | string | ✅ | 通道 SourceId |

**返回参数 (StreamUrls)**:

| 字段 | 类型 | 说明 |
|------|------|------|
| `wsFlv` | string? | WebSocket-FLV 地址（推荐，低延迟） |
| `httpFlv` | string? | HTTP-FLV 地址 |
| `hls` | string? | HLS (m3u8) 地址 |
| `webrtc` | string? | WebRTC 地址 |
| `rtmp` | string? | RTMP 地址 |

### B6b: 获取录像回放地址

```
GET /api/gateway/streams/{adapter}/{deviceId}/playback?start={start}&end={end}
```

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `adapter` | string | ✅ | 适配器编码 |
| `deviceId` | string | ✅ | 通道 SourceId |
| `start` | DateTime | ✅ | 回放起始时间 (ISO 8601) |
| `end` | DateTime | ✅ | 回放结束时间 (ISO 8601) |

**返回**: 同 `StreamUrls`

### 截图: 获取通道实时截图

```
POST /api/gateway/streams/{adapter}/{deviceId}/snapshot
```

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `adapter` | string | ✅ | 适配器编码 |
| `deviceId` | string | ✅ | 通道 SourceId |

**返回**: JPEG 图片 Base64 或 URL

### B7: 云台控制

```
POST /api/gateway/streams/{adapter}/{deviceId}/ptz
```

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `adapter` | string | ✅ | 适配器编码 |
| `deviceId` | string | ✅ | 通道 SourceId |

**请求体 (PtzRequest)**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `direction` | string | ❌ | 方向：`up`/`down`/`left`/`right`/`zoom_in`/`zoom_out` |
| `action` | string | ✅ | 动作：`continuous`(持续)/`stop`(停止)/`preset`/`patrol` |
| `speed` | float | ❌ | 速度 (0.1~1.0)，默认 0.5 |

---

## 4. IoT 实时数据

### B4: 获取设备实时点位值

```
GET /api/gateway/realtime/{adapter}/{deviceId}
```

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `adapter` | string | ✅ | 适配器编码，如 `MC4:31ku` |
| `deviceId` | string | ✅ | 设备 SourceId |

**返回参数**: `PointValue[]`

| 字段 | 类型 | 说明 |
|------|------|------|
| `pointIndex` | int | 点位索引 |
| `pointName` | string | 点位名称 |
| `value` | decimal | 当前值 |
| `unit` | string? | 单位（如 `℃`、`%`） |
| `updateTime` | DateTime | 更新时间 |
| `interval` | int | 采集间隔（秒） |

### B4-batch: 批量获取实时点位值

```
POST /api/gateway/realtime/{adapter}/batch
```

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `adapter` | string | ✅ | 适配器编码 |

**请求体 (BatchRealtimeRequest)**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `deviceIds` | string[] | ✅ | 设备 SourceId 列表 |

**返回**: `Dictionary<string, PointValue[]>` — 以 deviceId 为键的实时值字典

### B5: 设备反向控制

```
POST /api/gateway/realtime/{adapter}/control
```

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `adapter` | string | ✅ | 适配器编码 |

**请求体 (ControlRequest)**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `deviceId` | string | ✅ | 设备 SourceId |
| `pointIndex` | int | ✅ | 目标点位索引 |
| `value` | double | ✅ | 目标值（如开关 0/1，温度设定值等） |

---

## 5. 告警管理

### B8: 分页查询告警列表

```
GET /api/gateway/alarms/{adapter}?page={page}&size={size}&from={from}&to={to}&level={level}&state={state}
```

**请求参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|:--:|------|------|
| `adapter` | string | ✅ | — | 适配器编码 |
| `page` | int | ❌ | 1 | 页码 |
| `size` | int | ❌ | 20 | 每页条数 |
| `from` | DateTime | ❌ | MinValue | 告警起始时间 |
| `to` | DateTime | ❌ | MinValue | 告警结束时间 |
| `level` | string | ❌ | null | 告警等级过滤 |
| `state` | string | ❌ | null | 告警状态过滤：`未确认`/`已确认`/`已结束` |

**返回参数**:

| 字段 | 类型 | 说明 |
|------|------|------|
| `items` | array | 告警列表 |
| `total` | int | 总告警数 |

**items[].StandardAlarm**:

| 字段 | 类型 | 说明 |
|------|------|------|
| `alarmId` | string | 告警 ID |
| `adapterCode` | string | 适配器编码 |
| `deviceId` | string? | 关联设备 ID |
| `level` | string | 告警等级：`提示`/`普通`/`重要`/`紧急` |
| `title` | string | 告警标题 |
| `content` | string? | 告警详细内容 |
| `occurTime` | DateTime | 发生时间 |
| `status` | string | 状态：`未确认`/`已确认`/`已结束` |
| `actualValue` | string? | 实际值（超标告警） |
| `thresholdValue` | string? | 阈值（超标告警） |

### B9-confirm: 确认告警

```
POST /api/gateway/alarms/{adapter}/{alarmId}/confirm
```

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `adapter` | string | ✅ | 适配器编码 |
| `alarmId` | string | ✅ | 告警 ID（子系统告警源 ID） |

### B9-end: 结束告警

```
POST /api/gateway/alarms/{adapter}/{alarmId}/end
```

**请求参数**: 同 B9-confirm

---

## 6. 录像查询

```
GET /api/gateway/recordings/{adapter}/{deviceId}?start={start}&end={end}&page={page}&size={size}
```

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `adapter` | string | ✅ | 适配器编码 |
| `deviceId` | string | ✅ | 通道 SourceId |
| `start` | DateTime | ✅ | 录像起始时间 |
| `end` | DateTime | ✅ | 录像结束时间 |
| `page` | int | ❌ | 页码，默认 1 |
| `size` | int | ❌ | 每页条数，默认 20 |

**返回**: 录像文件列表（含文件名、起止时间、时长、大小）

---

## 7. 设备控制 (通用)

### B10: 下发控制指令

```
POST /api/gateway/control/{adapter}
```

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `adapter` | string | ✅ | 适配器编码，如 `KMS:main` |

**请求体 (GatewayControlRequest)**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `deviceId` | string | ✅ | 设备 SourceId |
| `command` | string | ✅ | 指令名：`open`(开门)/`close`(关门)/`authorize`(授权) |
| `parameters` | object | ❌ | 指令参数，如 `{"staffIds": [1,2], "lockholeSort": 3}` |

**返回 (ControlResult)**:

| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | bool | 操作是否成功 |
| `message` | string? | 失败时的错误信息 |

---

## 8. 业务记录查询

### B11: 查询子系统业务记录

```
GET /api/gateway/logs/{adapter}?logType={logType}&from={from}&to={to}&page={page}&size={size}
```

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `adapter` | string | ✅ | 适配器编码 |
| `logType` | string | ✅ | 记录类型：`borrow`(借还)/`handover`(交接)/`permission`(授权) |
| `from` | DateTime | ❌ | 起始时间 |
| `to` | DateTime | ❌ | 结束时间 |
| `page` | int | ❌ | 页码，默认 1 |
| `size` | int | ❌ | 每页条数，默认 20 |

**返回参数**:

| 字段 | 类型 | 说明 |
|------|------|------|
| `items` | array | 业务记录列表 |
| `total` | int | 总记录数 |

**items[].BusinessLogEntry**:

| 字段 | 类型 | 说明 |
|------|------|------|
| `logId` | string | 记录唯一 ID |
| `logType` | string | 记录类型 |
| `deviceSourceId` | string? | 关联设备 SourceId |
| `staffName` | string? | 关联员工姓名 |
| `description` | string? | 记录描述 |
| `createdAt` | DateTime? | 记录时间 |
| `extra` | object? | 扩展属性 |

---

## 9. 数据同步

### B12: 向子系统写入数据

```
POST /api/gateway/sync/{adapter}
```

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `adapter` | string | ✅ | 适配器编码 |

**请求体 (SyncRequest)**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `dataType` | string | ✅ | 数据类型，当前支持 `staff`（员工） |
| `items` | object[] | ✅ | 待同步数据列表 |

**返回 (SyncResult)**:

| 字段 | 类型 | 说明 |
|------|------|------|
| `successCount` | int | 成功数量 |
| `failCount` | int | 失败数量 |
| `message` | string? | 错误信息 |

### B13: 从子系统删除数据

```
DELETE /api/gateway/sync/{adapter}
```

**请求参数**: 同 B12

**请求体 (SyncDeleteRequest)**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `dataType` | string | ✅ | 数据类型，当前支持 `staff` |
| `ids` | string[] | ✅ | 待删除 ID 列表 |

**返回**: 同 `SyncResult`

---

## 10. 错误代码

### 通用 HTTP 状态码

| 状态码 | 含义 | 触发条件 |
|:---:|------|------|
| 200 | OK | 请求成功 |
| 400 | Bad Request | 请求参数格式错误 |
| 401 | Unauthorized | `X-Gateway-Key` 缺失或不匹配 |
| 404 | Not Found | 适配器不存在或不支持该能力 |
| 500 | Internal Server Error | 适配器内部异常 |
| 502 | Bad Gateway | 子系统返回错误或不可达 |

### 业务错误码

所有非 200 响应包含 JSON body：

| 字段 | 类型 | 说明 |
|------|------|------|
| `error` | string | 错误码 |
| `message` | string? | 人类可读的错误详情 |

| error 值 | HTTP | 说明 |
|------|:---:|------|
| `ADAPTER_NOT_FOUND` | 404 | 指定适配器编码不存在 |
| `CAPABILITY_NOT_SUPPORTED` | 404 | 适配器不支持该接口能力 |
| — (control 接口) | 502 | `ControlResult.Success=false` 时返回 `ControlResult.Message` |

---

> **接口总数**: 19 个 REST 端点
> **适配器**: Owl / MC4 / KMS（通过 `adapter` 参数路由）