全量提交: KMS适配器终检修复+warehouse P0修复+MC4认证修复+网关B路由+接口文档+代码审核报告

2026-06-04 04:07:32 +08:00
parent fa170e55a9
commit 29e12a235a
11 changed files with 1706 additions and 377 deletions
--- a/doc/设计文档/网关B组接口文档_v1.0.md
+++ b/doc/设计文档/网关B组接口文档_v1.0.md
@@ -0,0 +1,550 @@
+# 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` 参数路由）