From 69a18d38d33089a46d2df35631858edfb3631e42 Mon Sep 17 00:00:00 2001
From: g82tt <snow82@vip.qq.com>
Date: Sat, 16 May 2026 12:56:12 +0800
Subject: [PATCH] Phase0_gateway_api_specs

---
 doc/整合方案/SecMPS_最终整合方案_v2.0.md | 74 +++++++++++++++++++-----
 1 file changed, 59 insertions(+), 15 deletions(-)

diff --git a/doc/整合方案/SecMPS_最终整合方案_v2.0.md b/doc/整合方案/SecMPS_最终整合方案_v2.0.md
index 91b2af5..f07f37d 100644
--- a/doc/整合方案/SecMPS_最终整合方案_v2.0.md
+++ b/doc/整合方案/SecMPS_最终整合方案_v2.0.md
@@ -82,25 +82,69 @@ Vol.Pro Job: IsOnline=在线 且 LastHeartbeat < now-30s → IsOnline=离线 →
 | PushToSource | Vol.Pro→第三方 | 告警确认/控制 | 元数据/PTZ |
 | Bidirectional | 先写第三方再更新本地 | 告警确认 | — |
 
-### 2.5 Gateway API
+### 2.5 对接 API 规范
+
+网关与 Vol.Pro 之间有两组接口，调用方向不同。
+
+#### A. 网关 → Vol.Pro（网关主动调用）
+
+| # | 接口 | 说明 |
+|---|------|------|
+| A1 | `POST /api/gateway/register` | 网关启动注册，上报身份与能力，获取所管设备列表 |
+| A2 | `POST /api/gateway/heartbeat` | 心跳（每 15s），Vol.Pro 更新在线状态 |
+| A3 | `POST /api/gateway/sync/devices` | 上送设备数据（新增/变更/离线） |
+| A4 | `POST /api/gateway/sync/alarms` | 上送告警数据 |
+
+**A1 注册** — 认证: NodeToken
 
 ```
-# 注册与心跳
-POST /api/gateway/register  { nodeCode, token, adapterTypes, baseUrl }
-POST /api/gateway/heartbeat  { nodeCode, token }
-
-# 设备与数据
-GET  /api/gateway/devices?adapter=&page=&size=
-GET  /api/gateway/devices/sync?adapter=
-GET  /api/gateway/realtime/{adapter}/{deviceId}
-POST /api/gateway/realtime/{adapter}/control
-GET  /api/gateway/streams/{adapter}/{id}/live
-POST /api/gateway/streams/{adapter}/{id}/ptz
-GET  /api/gateway/alarms/{adapter}?from=&to=
-POST /api/gateway/alarms/{adapter}/{id}/confirm
-GET  /api/gateway/health
+Request:  { nodeCode, token, adapterTypes, baseUrl }
+Response: { nodeId, devices: [ base_device 列表(当前网关负责的顶层设备) ] }
+Error:    401 认证失败
 ```
 
+**A2 心跳** — 认证: NodeToken
+
+```
+Request:  { nodeCode, token }
+Response: { status: "ok" }
+```
+
+**A3 设备同步** — 认证: NodeToken
+
+```
+Request:  { nodeCode, token, devices: [{ adapterCode, sourceId, name, category, group,
+            isParent, parentSourceId, isOnline, ipAddress, port, extraData }] }
+Response: { added, updated, removed }
+```
+> 网关只发自己负责的字段（ExtraData 中的适配器属性 + 公共状态字段），不碰管理员字段（DeviceName/Category/Location/MapModelId…）。Vol.Pro 首次入库写全量，后续仅更新网关负责的列。
+
+**A4 告警同步** — 认证: NodeToken
+
+```
+Request:  { nodeCode, token, alarms: [{ sourceAlarmId, deviceSourceId, adapterCode,
+            level, desc, value, startTime }] }
+Response: { added }
+```
+
+---
+
+#### B. Vol.Pro / 管理端 → 网关（查询与控制）
+
+| # | 接口 | 说明 |
+|---|------|------|
+| B1 | `GET /api/gateway/health` | 网关及所有适配器状态 |
+| B2 | `GET /api/gateway/devices?adapter=&page=&size=` | 设备列表（实时查第三方） |
+| B3 | `POST /api/gateway/devices/sync?adapter=` | 手动触发全量同步 |
+| B4 | `GET /api/gateway/realtime/{adapter}/{deviceId}` | 实时点位值 |
+| B5 | `POST /api/gateway/realtime/{adapter}/control` | 反向控制 { deviceSourceId, pointIndex, value } |
+| B6 | `GET /api/gateway/streams/{adapter}/{channelId}/live` | 取流地址 → { wsFlv, httpFlv, hls, webrtc } |
+| B7 | `POST /api/gateway/streams/{adapter}/{channelId}/ptz` | 云台控制 { direction, speed } |
+| B8 | `GET /api/gateway/alarms/{adapter}?from=&to=&page=&size=` | 告警查询 |
+| B9 | `POST /api/gateway/alarms/{adapter}/{alarmId}/confirm` | 告警确认（写回第三方） |
+
+> B 组接口由管理端或 Vol.Pro 后端直接调用网关，认证方式为内网直连或网关侧 IP 白名单。
+
 ---
 
 ## 三、数据模型（6 张表）