SecMPS/doc/设计文档/网关B组接口文档_v1.0.md

IntegrationGateway B 组接口文档

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

---

目录

1. 健康检查 — B1
2. 设备管理 — B2, B3, B3-sync
3. 视频与流媒体 — B6a, B6b, 截图, B7
4. IoT 实时数据 — B4, B4-batch, B5
5. 告警管理 — B8, B9-confirm, B9-end
6. 录像查询
7. 设备控制 (通用) — B10
8. 业务记录查询 — B11
9. 数据同步 — B12, B13
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	是否支持录像查询

返回示例:

[
  {
    "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?	子系统特有扩展属性

返回示例:

{
  "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 参数路由）