# SecMPS 网关与 Vol.Pro 对接 API 手册

> **版本**: v1.0  
> **日期**: 2026-05-16  
> **基于**: SecMPS_最终整合方案_v3.0.md  
> **接口数量**: 13 个（A 组 4 个 + B 组 9 个）

---

## 1. 引言

### 1.1 目标与范围

本手册定义 IntegrationGateway（网关）与 Vol.Pro 后端之间所有 HTTP API 的接口规范。供网关开发、Vol.Pro 后端开发、前端开发和 AI Agent 编码时参考。

### 1.2 基本约定

| 约定 | 说明 |
|------|------|
| 请求方法 | A 组使用 **POST**，B 组使用 **GET / POST** |
| 数据格式 | **JSON**，`Content-Type: application/json` |
| 字符编码 | **UTF-8** |
| 认证方式 | A 组: `NodeToken`（请求体中携带），B 组: 内网直连，无认证 |
| 网关端口 | **5100**（默认） |
| Vol.Pro 端口 | **9100**（默认） |

### 1.3 响应格式

**成功**:
```json
{
  // 具体数据，见各接口定义
}
```
HTTP Status: 200

**失败**:
```json
{
  "message": "错误描述"
}
```
HTTP Status: 400（业务错误）/ 401（认证失败）/ 500（服务器错误）

---

## 2. A 组接口：网关 → Vol.Pro

> 调用方: 网关  
> 接收方: Vol.Pro 后端  
> 端口: 9100

---

### 2.1 A1 — 网关注册

网关启动时调用，上报身份与能力，获取所管理的顶层设备列表。

- **Endpoint**: `POST /api/gateway/register`
- **认证**: NodeToken
- **逻辑**: Upsert — NodeCode 匹配则更新，不匹配则插入

#### 请求体

```json
{
  "nodeCode": "gw-31ku",
  "token": "a1b2c3d4e5f6",
  "adapterTypes": "MC4,Owl",
  "baseUrl": "http://192.168.1.100:5100"
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| nodeCode | string | ✅ | 网关唯一编码，管理端生成 |
| token | string | ✅ | 认证令牌，管理端生成 |
| adapterTypes | string | ✅ | 支持的适配器类型，逗号分隔，例如 "MC4,Owl" |
| baseUrl | string | ✅ | 网关自身地址（含端口），供管理端回调 |

#### 响应体（成功）

```json
{
  "nodeId": 1,
  "devices": [
    {
      "deviceId": 10,
      "deviceName": "动环采集器",
      "adapterCode": "MC4:31ku",
      "sourceId": "1001",
      "deviceCategory": "动环采集器",
      "deviceGroup": "IoT设备",
      "isParent": "是",
      "parentSourceId": null,
      "isOnline": "在线",
      "ipAddress": "10.0.1.100",
      "port": 3000,
      "extraData": {
        "mc4DeviceId": 1001
      }
    }
  ]
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| nodeId | int | 网关在 Vol.Pro 中的 NodeId |
| devices | array | 当前网关负责的顶层设备列表（base_device 中 GatewayNodeId=本网关 且 ParentDeviceId IS NULL 的记录） |
| devices[].deviceId | int | Vol.Pro 内部设备ID |
| devices[].adapterCode | string | 双段标识 "MC4:31ku" |
| devices[].sourceId | string | 第三方原始设备ID |
| devices[].extraData | object | 适配器扩展数据 |

#### 响应体（失败）

```json
// HTTP 401
{
  "message": "认证失败"
}
```

#### 请求示例

```bash
curl -X POST http://localhost:9100/api/gateway/register \
  -H "Content-Type: application/json" \
  -d '{"nodeCode":"gw-31ku","token":"a1b2c3d4e5f6","adapterTypes":"MC4,Owl","baseUrl":"http://192.168.1.100:5100"}'
```

---

### 2.2 A2 — 网关心跳

网关每 15 秒调用，Vol.Pro 更新 LastHeartbeat 和 IsOnline。

- **Endpoint**: `POST /api/gateway/heartbeat`
- **认证**: NodeToken
- **频率**: 每 15 秒

#### 请求体

```json
{
  "nodeCode": "gw-31ku",
  "token": "a1b2c3d4e5f6"
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| nodeCode | string | ✅ | 网关唯一编码 |
| token | string | ✅ | 认证令牌 |

#### 响应体

```json
{
  "status": "ok",
  "serverTime": "2026-05-16 15:30:00"
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| status | string | 固定 "ok" |
| serverTime | string | Vol.Pro 当前时间，供网关校时 |

#### 请求示例

```bash
curl -X POST http://localhost:9100/api/gateway/heartbeat \
  -H "Content-Type: application/json" \
  -d '{"nodeCode":"gw-31ku","token":"a1b2c3d4e5f6"}'
```

---

### 2.3 A3 — 设备数据同步

网关发现新设备或设备状态变更后，上送到 Vol.Pro。

- **Endpoint**: `POST /api/gateway/sync/devices`
- **认证**: NodeToken
- **字段分治**: 首次入库写全量，已有记录仅更新网关字段

#### 请求体

```json
{
  "nodeCode": "gw-31ku",
  "token": "a1b2c3d4e5f6",
  "devices": [
    {
      "adapterCode": "MC4:31ku",
      "sourceId": "1001",
      "name": "动环采集器",
      "category": "动环采集器",
      "group": "IoT设备",
      "isParent": true,
      "parentSourceId": null,
      "isOnline": true,
      "ipAddress": "10.0.1.100",
      "port": 3000,
      "extraData": {
        "mc4DeviceId": 1001
      }
    },
    {
      "adapterCode": "MC4:31ku",
      "sourceId": "1001_0",
      "name": "温湿度变送器",
      "category": "温湿度变送器",
      "group": "IoT设备",
      "isParent": false,
      "parentSourceId": "1001",
      "isOnline": true,
      "ipAddress": null,
      "port": null,
      "extraData": {
        "mc4DeviceId": 1001,
        "pointIndex": 0,
        "unit": "℃"
      }
    }
  ]
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| nodeCode | string | ✅ | 网关编码 |
| token | string | ✅ | 认证令牌 |
| devices | array | ✅ | 设备列表 |
| devices[].adapterCode | string | ✅ | 双段标识 |
| devices[].sourceId | string | ✅ | 第三方原始ID |
| devices[].name | string | ✅ | 设备名称（仅首次写入） |
| devices[].category | string | ✅ | 设备种类（仅首次写入） |
| devices[].group | string | ✅ | 设备分组（仅首次写入） |
| devices[].isParent | bool | ✅ | 是否父设备 |
| devices[].parentSourceId | string? | | 父设备第三方ID，Vol.Pro 解析为 ParentDeviceId |
| devices[].isOnline | bool | ✅ | 在线状态 |
| devices[].ipAddress | string? | | IP 地址 |
| devices[].port | int? | | 端口 |
| devices[].extraData | object | | 适配器扩展数据 |

**字段分治规则**:
- **首次入库**（DeviceId=0）: 所有字段写入
- **已有记录**: 仅更新 isOnline、isParent、parentDeviceId（解析后）、extraData、ipAddress、port、lastSyncTime
- deviceName、category、group、pointId、location、lat/lng、mapModelId 仅在首次写入

#### 响应体

```json
{
  "added": 2,
  "updated": 0,
  "removed": 0
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| added | int | 新增设备数 |
| updated | int | 更新设备数 |
| removed | int | 删除设备数（FullReplace 模式下可能 >0） |

#### 请求示例

```bash
curl -X POST http://localhost:9100/api/gateway/sync/devices \
  -H "Content-Type: application/json" \
  -d '{"nodeCode":"gw-31ku","token":"a1b2c3d4e5f6","devices":[...]}'
```

---

### 2.4 A4 — 告警数据同步

网关发现新告警后上送。

- **Endpoint**: `POST /api/gateway/sync/alarms`
- **认证**: NodeToken

#### 请求体

```json
{
  "nodeCode": "gw-31ku",
  "token": "a1b2c3d4e5f6",
  "alarms": [
    {
      "sourceAlarmId": "2183fda3-9e32-48ae-b433-f807cc81a237",
      "deviceSourceId": "1001_0",
      "adapterCode": "MC4:31ku",
      "level": "重要",
      "desc": "温度超限: [温湿度变送器][45℃]",
      "value": 45.0,
      "startTime": "2026-05-16 14:30:00"
    }
  ]
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| nodeCode / token | string | ✅ | 认证信息 |
| alarms | array | ✅ | 告警列表 |
| alarms[].sourceAlarmId | string | ✅ | 源系统告警ID（用于去重） |
| alarms[].deviceSourceId | string | ✅ | 告警所属设备的第三方ID |
| alarms[].adapterCode | string | ✅ | 双段标识 |
| alarms[].level | string | ✅ | 告警等级(字典: 提示/普通/重要/紧急) |
| alarms[].desc | string | ✅ | 告警描述 |
| alarms[].value | double | | 触发值 |
| alarms[].startTime | string | ✅ | 告警开始时间 "yyyy-MM-dd HH:mm:ss" |

#### 响应体

```json
{
  "added": 1
}
```

---

## 3. B 组接口：Vol.Pro / 管理端 → 网关

> 调用方: Vol.Pro 后端 / 管理端 / warehouse 端  
> 接收方: 网关  
> 端口: 5100  
> 认证: 内网直连（无认证）

---

### 3.1 B1 — 健康检查

- **Endpoint**: `GET /api/gateway/health`

#### 响应体

```json
{
  "gateway": "ok",
  "adapters": {
    "MC4:31ku": true,
    "Owl:main": true
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| gateway | string | 固定 "ok" |
| adapters | object | key=AdapterCode, value=true(在线)/false(离线) |

#### 请求示例

```bash
curl http://localhost:5100/api/gateway/health
```

---

### 3.2 B2 — 设备列表

获取指定适配器下的设备列表（实时查询第三方）。

- **Endpoint**: `GET /api/gateway/devices`
- **适配器**: IHasFlatDevices

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| adapter | string | ✅ | AdapterCode，例如 "Owl:main" |
| page | int | | 页码，默认 1 |
| size | int | | 每页大小，默认 50 |
| keyword | string | | 名称/ID 模糊搜索 |

#### 响应体

```json
{
  "items": [
    {
      "sourceId": "gb_34020000001320000001",
      "adapterCode": "Owl:main",
      "name": "NVR-01",
      "category": "硬盘录像机",
      "group": "视频设备",
      "isOnline": true,
      "isParent": true,
      "ipAddress": "192.168.1.100",
      "port": 5060,
      "channelCount": 4,
      "extraData": {
        "owlDeviceId": "gb_34020000001320000001",
        "protocol": "GB28181",
        "transport": "UDP"
      }
    }
  ],
  "total": 50
}
```

---

### 3.3 B3 — 手动触发同步

管理端手动触发全量设备同步。

- **Endpoint**: `POST /api/gateway/devices/sync`
- **适配器**: 所有实现了 IHasFlatDevices 或 IHasOwnDeviceTree 的适配器

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| adapter | string | ✅ | AdapterCode |

#### 响应体

```json
{
  "adapterCode": "Owl:main",
  "added": 5,
  "updated": 3,
  "removed": 1,
  "errors": [],
  "startTime": "2026-05-16T15:30:00",
  "endTime": "2026-05-16T15:30:05"
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| adapterCode | string | 适配器编码 |
| added | int | 新增数 |
| updated | int | 更新数 |
| removed | int | 删除数 |
| errors | array | 错误信息列表 |
| startTime / endTime | string | 同步起止时间 |

---

### 3.4 B4 — 实时点位值

获取设备所有点位的实时值。

- **Endpoint**: `GET /api/gateway/realtime/{adapter}/{deviceSourceId}`
- **适配器**: IHasPoints (MC4.0)

#### 路径参数

| 参数 | 说明 |
|------|------|
| adapter | AdapterCode，例如 "MC4:31ku" |
| deviceSourceId | 设备在第三方系统中的 ID |

#### 响应体

```json
{
  "deviceSourceId": "1001",
  "points": [
    {
      "pointIndex": 0,
      "name": "温度",
      "value": 26.5,
      "unit": "℃",
      "updateTime": "2026-05-16 15:30:00",
      "isValid": true
    },
    {
      "pointIndex": 1,
      "name": "湿度",
      "value": 55.0,
      "unit": "%",
      "updateTime": "2026-05-16 15:30:00",
      "isValid": true
    }
  ]
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| deviceSourceId | string | 设备ID |
| points[].pointIndex | int | 点位索引 |
| points[].name | string | 点位名称 |
| points[].value | double | 当前值 |
| points[].unit | string | 单位 |
| points[].updateTime | string | 数据更新时间 |
| points[].isValid | bool | 数据是否有效（false=传感器异常） |

---

### 3.5 B5 — 设备控制

反向控制设备（调空调温度、开关阀门等）。

- **Endpoint**: `POST /api/gateway/realtime/{adapter}/control`
- **适配器**: IHasPoints (MC4.0)

#### 路径参数 + 请求体

```json
// POST /api/gateway/realtime/MC4:31ku/control
{
  "deviceSourceId": "1001",
  "pointIndex": 2,
  "value": 1
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| deviceSourceId | string | ✅ | 第三方设备ID |
| pointIndex | int | ✅ | 点位索引 |
| value | double | ✅ | 设置值（开关: 0/1, 模拟量: 实际数值） |

#### 响应体

```json
{
  "status": "sent"
}
```

> 注意: 响应仅表示指令已发送，不保证设备已执行。如需确认，应再次调 B4 查询实时值。

---

### 3.6 B6a — 实时取流

获取实时播放流地址。

- **Endpoint**: `GET /api/gateway/streams/{adapter}/{channelId}/live`
- **适配器**: IHasStreams (Owl)

#### 响应体

```json
{
  "wsFlv": "ws://192.168.1.108/proxy/sms/rtp/gb_xxx.live.flv",
  "httpFlv": "http://192.168.1.108/proxy/sms/rtp/gb_xxx.live.flv",
  "hls": "http://192.168.1.108/proxy/sms/rtp/gb_xxx/hls.fmp4.m3u8",
  "webrtc": "webrtc://192.168.1.108/proxy/sms/index/api/webrtc?app=rtp&stream=gb_xxx&type=play",
  "rtmp": "rtmp://192.168.1.108:1935/rtp/gb_xxx",
  "rtsp": "rtsp://192.168.1.108:554/rtp/gb_xxx"
}
```

| 协议 | 建议用途 | 延迟 |
|------|----------|:---:|
| wsFlv | Web 实时预览（首选） | <1s |
| httpFlv | 兼容旧浏览器 | 1-2s |
| hls | iOS Safari / 回放 | 3-5s |
| webrtc | 超低延迟场景 | <500ms |

> 注意: GB28181 首次拉流有 1-3 秒 SIP 信令延迟。建议前端播放器在 3 秒内无画面时自动重试一次。

---

### 3.7 B6b — 回放取流

获取历史录像 HLS 播放地址。

- **Endpoint**: `GET /api/gateway/streams/{adapter}/{channelId}/playback`
- **适配器**: IHasStreams (Owl)

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| start | string | ✅ | 开始时间 "yyyy-MM-dd HH:mm:ss" |
| end | string | ✅ | 结束时间 "yyyy-MM-dd HH:mm:ss" |

#### 响应体

```json
{
  "hls": "http://192.168.1.108/recordings/channels/gb_xxx/index.m3u8?start_ms=1714982400000&end_ms=1714982700000&token=xxx"
}
```

> 回放使用 HLS (VOD) 格式，Owl 将指定时间范围内的 MP4 片段动态拼接为 m3u8 播放列表。

---

### 3.8 B7 — 云台控制

控制摄像机云台转动。

- **Endpoint**: `POST /api/gateway/streams/{adapter}/{channelId}/ptz`
- **适配器**: IHasStreams (Owl)

#### 请求体

```json
{
  "direction": "left",
  "speed": 0.5
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| direction | string | ✅ | **仅支持**: `up` / `down` / `left` / `right` / `zoom_in` / `zoom_out` / `stop` |
| speed | float | | 速度 0.0~1.0，默认 0.5 |

> ⚠️ Owl 当前版本仅实现了方向移动 (`continuous`) 和停止 (`stop`)，**不支持**预设位操作 (`preset/set/goto/remove`) 和绝对/相对定位。ONVIF PTZ 未实现。

#### 响应体

```json
{
  "status": "ok"
}
```

---

### 3.9 B8 — 告警查询

查询告警列表。

- **Endpoint**: `GET /api/gateway/alarms/{adapter}`
- **适配器**: IHasAlarms

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| from | string | ✅ | 开始时间 "yyyy-MM-dd HH:mm:ss" |
| to | string | ✅ | 结束时间 |
| page | int | | 页码，默认 1 |
| size | int | | 每页大小，默认 50 |
| confirmState | int | | MC4.0: 0=所有, 1=未确认, 2=已确认 |
| level | string | | 告警等级: 提示/普通/重要/紧急 |

#### 响应体

```json
{
  "items": [
    {
      "alarmId": "2183fda3-9e32-48ae-b433-f807cc81a237",
      "deviceId": "1001",
      "adapterCode": "MC4:31ku",
      "level": "重要",
      "title": "温度超限",
      "content": "[温湿度变送器][45℃]",
      "occurTime": "2026-05-16 14:30:00",
      "status": "未确认",
      "thresholdValue": 40.0,
      "actualValue": 45.0
    }
  ],
  "total": 120
}
```

---

### 3.10 B9 — 告警确认

确认告警，写回第三方系统。

- **Endpoint**: `POST /api/gateway/alarms/{adapter}/{alarmId}/confirm`
- **适配器**: IHasAlarms

#### 路径参数

| 参数 | 说明 |
|------|------|
| adapter | AdapterCode |
| alarmId | 源系统告警 ID |

#### 响应体

```json
{
  "status": "confirmed"
}
```

> Vol.Pro 在收到成功响应后，同步更新本地 `iot_alarm.State='已确认'` 和 `ConfirmTime=当前时间`。

---

## 4. 错误码对照表

| HTTP Status | 含义 | 说明 |
|:----------:|------|------|
| 200 | 成功 | 正常响应 |
| 400 | 请求错误 | 参数缺失或格式错误 |
| 401 | 认证失败 | A 组接口 NodeCode 或 Token 不正确 |
| 404 | 未找到 | 适配器不存在或设备不存在 |
| 500 | 服务器错误 | 网关或 Vol.Pro 内部异常 |
| 502 | 第三方错误 | 网关调用 Owl/MC4.0 失败 |

---

## 5. 数据类型约定

| 类型 | JSON 示例 | 说明 |
|------|-----------|------|
| string | "hello" | 字符串 |
| int | 42 | 整数 |
| double | 26.5 | 浮点数 |
| bool | true / false | 布尔值 |
| object | { "key": "value" } | JSON 对象 |
| array | [ ... ] | JSON 数组 |
| datetime | "2026-05-16 15:30:00" | 日期时间字符串，格式 yyyy-MM-dd HH:mm:ss |

---

## 6. 对接检查清单

网关开发和 Vol.Pro 开发完成后，按以下清单逐项验证：

```
□ A1: 网关启动 → 注册成功 → 返回 nodeId + 设备列表
□ A2: 网关心跳 → Vol.Pro gateway_nodes.LastHeartbeat 更新
□ A3: 首次同步 → 设备入库，字段分治规则正确（管理员字段不覆盖）
□ A3: 二次同步 → 仅网关字段更新，DeviceName 不变
□ A3: parentSourceId → Vol.Pro 正确解析为 ParentDeviceId
□ A4: 告警上报 → iot_alarm 表有数据
□ B1: 健康检查 → 返回所有适配器状态
□ B2: 设备列表 → 分页 + 关键字搜索正常
□ B3: 手动同步 → 返回 added/updated/removed 统计
□ B4: 实时数据 → 返回点位值和更新时间
□ B5: 设备控制 → 指令发送成功，设备实际响应
□ B6a: 实时取流 → 返回 6 种协议地址，前端可播放
□ B6b: 回放取流 → 返回 HLS 地址，前端可播放历史录像
□ B7: 云台控制 → 方向键有效，stop 有效
□ B8: 告警查询 → 分页 + 筛选正常
□ B9: 告警确认 → 第三方确认成功 + Vol.Pro 本地 State 更新
```

---

> **文档结束**