# VolPro.WebApi 网关相关接口文档

> **版本**: 1.0
> **日期**: 2026-06-04
> **基址**: `http://{host}:{port}`（默认 `http://localhost:9100`）
> **内容类型**: `application/json`
> **接口来源**: `api_sqlsugar/VolPro.WebApi/Controllers/Warehouse/`

---

## 目录

1. [A 组 — 网关注册通信](#1-a-组--网关注册通信)
   - A1: 网关注册 `POST /api/gateway/register`
   - A2: 心跳上报 `POST /api/gateway/heartbeat`
   - A3: 设备同步 `POST /api/gateway/sync/devices`
   - A4: 告警同步 `POST /api/gateway/sync/alarms`
2. [设备管理](#2-设备管理)
   - 区域树 `GET /api/DeviceManager/GetRegionTree`
   - 点位设备 `GET /api/DeviceManager/GetDevicesByPoint`
3. [定时任务](#3-定时任务)
   - 设备同步任务 `POST /api/task/syncDevices`
   - 心跳监控任务 `POST /api/task/heartbeatMonitor`
   - 实时轮询任务 `POST /api/task/realtimePoll`
   - 规则引擎任务 `POST /api/task/ruleEngine`
4. [错误代码](#4-错误代码)

---

## 1. A 组 — 网关注册通信

> A 组接口是 VolPro 向网关暴露的管理端点，由网关主动调用。所有 A 组使用 `[AllowAnonymous]` + `NodeToken` 二次认证，不走 VolPro JWT 体系。
>
> **实现文件**: `Controllers/Warehouse/Partial/gateway_nodesController.cs`

### A1: 网关注册（Upsert）

```
POST /api/gateway/register
```

网关启动时调用，注册自身节点信息。NodeCode 已存在则更新，不存在则插入。返回当前网关的已有设备列表供网关对比差异。

**请求头**: `Content-Type: application/json`

**请求体 (GatewayRegisterRequest)**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `NodeCode` | string | ✅ | 网关节点编码，如 `gw-31ku` |
| `Token` | string | ✅ | 认证令牌（由环境变量 `SECMPS_GATEWAY_TOKEN` 注入） |
| `AdapterTypes` | string | ✅ | 适配器类型列表（逗号分隔），如 `Owl:main,MC4:31ku` |
| `BaseUrl` | string | ✅ | 网关自身地址，如 `http://192.168.1.10:5100` |

**返回参数**:

| 字段 | 类型 | 说明 |
|------|------|------|
| `nodeId` | int | 网关节点 ID（base_device.NodeId 外键） |
| `devices` | array | 该网关已有的设备列表 |

**devices[] 条目**:

| 字段 | 类型 | 说明 |
|------|------|------|
| `deviceId` | int | 设备自增 ID |
| `deviceName` | string | 设备名称 |
| `adapterCode` | string | 适配器编码 |
| `sourceId` | string | 子系统设备原始 ID |
| `deviceCategory` | string | 设备种类 |
| `deviceGroup` | string | 设备分组 |
| `isParent` | string | 是否父设备（"是"/"否"） |
| `isOnline` | string | 是否在线（"在线"/"离线"） |
| `extraData` | string? | 扩展数据 JSON |

**返回示例**:
```json
{
  "nodeId": 1,
  "devices": [
    { "deviceId": 10, "deviceName": "NVR-1", "adapterCode": "Owl:main", "sourceId": "nvr_001", "deviceCategory": "硬盘录像机", "deviceGroup": "视频设备", "isParent": "是", "isOnline": "在线" }
  ]
}
```

**错误响应**:

| HTTP | 说明 |
|:---:|------|
| 400 | `NodeCode` 或 `Token` 为空 |
| 401 | `NodeToken` 不匹配（已有节点 Token 变更） |

---

### A2: 心跳上报

```
POST /api/gateway/heartbeat
```

网关每 15s 调用一次，更新 `LastHeartbeat` 字段。连续失败 ≥3 次（45s）后网关自动触发 A1+A3 重注册。

**请求体 (GatewayHeartbeatRequest)**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `NodeCode` | string | ✅ | 网关节点编码 |
| `Token` | string | ✅ | 认证令牌 |

**返回参数**:

| 字段 | 类型 | 说明 |
|------|------|------|
| `status` | string | 固定 `"ok"` |
| `serverTime` | string | 服务器时间 (`yyyy-MM-dd HH:mm:ss`) |

**错误响应**:

| HTTP | 说明 |
|:---:|------|
| 400 | `NodeCode` 或 `Token` 为空 |
| 401 | NodeCode+Token 组合不匹配 |

---

### A3: 设备数据同步

```
POST /api/gateway/sync/devices
```

网关每次设备变更后调用，将全量设备列表推送到 VolPro。采用字段分治策略：首次入库写全量，后续只更新网关字段。

**请求体 (SyncDevicesRequest)**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `NodeCode` | string | ✅ | 网关节点编码 |
| `Token` | string | ✅ | 认证令牌 |
| `Devices` | array | ✅ | 设备列表 |

**Devices[].SyncDeviceItemDto**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `AdapterCode` | string | ✅ | 适配器编码 |
| `SourceId` | string | ✅ | 子系统设备原始 ID |
| `Name` | string? | ❌ | 设备名称 |
| `Category` | string? | ❌ | 设备种类 |
| `Group` | string? | ❌ | 设备分组 |
| `IsParent` | bool | ❌ | 是否父设备 |
| `ParentSourceId` | string? | ❌ | 父设备 SourceId（用于解析 ParentDeviceId） |
| `IsOnline` | bool | ❌ | 是否在线 |
| `IpAddress` | string? | ❌ | IP 地址 |
| `Port` | int? | ❌ | 端口号 |
| `ExtraDataJson` | string? | ❌ | 扩展数据 JSON |

**返回参数**:

| 字段 | 类型 | 说明 |
|------|------|------|
| `added` | int | 新增设备数 |
| `updated` | int | 更新设备数 |
| `removed` | int | 固定 `0`（当前版本不移除下线设备） |

**错误响应**:

| HTTP | 说明 |
|:---:|------|
| 400 | `NodeCode` 或 `Token` 为空 |
| 401 | NodeCode+Token 认证失败 |

---

### A4: 告警数据同步

```
POST /api/gateway/sync/alarms
```

网关检测到新告警后调用，推送告警列表到 VolPro。通过 `SourceAlarmId` 去重（同一告警不重复入库）。

**请求体 (SyncAlarmsRequest)**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `NodeCode` | string | ✅ | 网关节点编码 |
| `Token` | string | ✅ | 认证令牌 |
| `Alarms` | array | ✅ | 告警列表 |

**Alarms[].SyncAlarmItemDto**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `SourceAlarmId` | string | ✅ | 子系统告警唯一 ID（用于去重） |
| `DeviceSourceId` | string | ✅ | 关联设备 SourceId（用于映射 DeviceId） |
| `AdapterCode` | string | ✅ | 适配器编码 |
| `Level` | string | ✅ | 告警等级：`提示`/`普通`/`重要`/`紧急` |
| `Desc` | string | ✅ | 告警描述 |
| `Value` | double? | ❌ | 告警实际值 |
| `StartTime` | string | ✅ | 告警发生时间 |

**返回参数**:

| 字段 | 类型 | 说明 |
|------|------|------|
| `added` | int | 新增告警数 |

**错误响应**:

| HTTP | 说明 |
|:---:|------|
| 400 | `NodeCode` 或 `Token` 为空 |
| 401 | NodeCode+Token 认证失败 |

---

## 2. 设备管理

> **实现文件**: `Controllers/Warehouse/Partial/base_deviceController.cs`

### 区域树

```
GET /api/DeviceManager/GetRegionTree
```

返回 区域→点位 的层级结构，供管理端左侧树形控件使用。

**请求参数**: 无

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

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 节点 ID（`r_{regionId}` 或 `p_{pointId}`） |
| `label` | string | 节点显示名称 |
| `type` | string | 节点类型：`region`(区域) 或 `point`(点位) |
| `deviceCount` | int | 该节点下的设备数量 |
| `children` | array? | 子节点列表（仅 region 节点有） |

**返回示例**:
```json
[
  {
    "id": "r_1", "label": "库房A区", "type": "region", "deviceCount": 3,
    "children": [
      { "id": "p_10", "label": "温湿度监测点1", "type": "point", "deviceCount": 5 },
      { "id": "p_11", "label": "门禁点1", "type": "point", "deviceCount": 2 }
    ]
  }
]
```

---

### 点位设备列表

```
GET /api/DeviceManager/GetDevicesByPoint?pointId={pointId}&page={page}&size={size}
```

获取指定点位下的设备列表（含子设备），支持分页。

**请求参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|:--:|------|------|
| `pointId` | int | ✅ | — | 点位 ID |
| `page` | int | ❌ | 1 | 页码 |
| `size` | int | ❌ | 20 | 每页条数 |

**返回参数**:

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

**items[] 条目**:

| 字段 | 类型 | 说明 |
|------|------|------|
| `deviceId` | int | 设备自增 ID |
| `deviceName` | string | 设备名称 |
| `adapterCode` | string | 适配器编码 |
| `sourceId` | string | 子系统设备原始 ID |
| `deviceCategory` | string | 设备种类 |
| `deviceGroup` | string | 设备分组（`视频设备`/`IoT设备`/`门禁设备`） |
| `isParent` | string | 是否父设备（"是"/"否"） |
| `parentDeviceId` | int? | 父设备 ID |
| `isOnline` | string | 是否在线（"在线"/"离线"） |
| `ipAddress` | string? | IP 地址 |
| `port` | int? | 端口号 |
| `location` | string? | 位置描述 |
| `extraData` | string? | 扩展数据 JSON |
| `lastSyncTime` | DateTime? | 最后同步时间 |
| `mapModelId` | string? | 3D 地图模型 ID |
| `mapModelScale` | decimal? | 模型缩放比例 |
| `mapModelRotation` | string? | 模型旋转参数 JSON |
| `enable` | string | 启用状态（"启用"/"停用"） |

---

## 3. 定时任务

> VolPro 框架通过 `Sys_QuartzOptions` 表配置 URL+Cron 定时调用。每个端点加 `[ApiTask]` 属性以允许框架匿名调用。
>
> **实现文件**: `Controllers/Warehouse/TaskController.cs`

### 设备同步任务

```
POST /api/task/syncDevices
```

遍历所有在线网关，触发全量设备同步至 VolPro。

**Cron**: `0 */5 * * * ?`（每 5 分钟）

**请求参数**: 无

**返回参数**:

| 字段 | 类型 | 说明 |
|------|------|------|
| `time` | DateTime | 执行时间 |
| `status` | string | 固定 `"ok"` |

**错误响应**:

| HTTP | 说明 |
|:---:|------|
| 500 | `gateway_nodesService` 未注册 |

---

### 心跳监控任务

```
POST /api/task/heartbeatMonitor
```

扫描心跳超时 ≥30s 的网关节点，标记离线并级联标记该节点下所有设备离线。

**Cron**: `0/15 * * * * ?`（每 15 秒）

**请求参数**: 无

**返回**: 同设备同步任务

---

### 实时轮询任务

```
POST /api/task/realtimePoll
```

轮询所有在线 MC4 IoT 设备的实时值，写入 `iot_devicedata` 表。

**Cron**: `0/10 * * * * ?`（每 10 秒）

**请求参数**: 无

**返回**: 同设备同步任务

---

### 规则引擎任务

```
POST /api/task/ruleEngine
```

加载启用规则 → 从网关批量获取实时值 → 逐规则评估条件 → 触发动作（控制/告警/通知）。

**Cron**: `0/10 * * * * ?`（每 10 秒）

**请求参数**: 无

**返回**: 同设备同步任务

**当前状态**: 桩实现。`RuleEngineService.EvaluateAllAsync()` 抛出 `NotImplementedException`，需先执行 SQL ALTER TABLE + 代码生成器。

---

## 4. 错误代码

### HTTP 状态码

| 状态码 | 含义 | 触发条件 |
|:---:|------|------|
| 200 | OK | 请求成功 |
| 400 | Bad Request | 必填参数缺失（`NodeCode`/`Token`/`pointId`） |
| 401 | Unauthorized | A 组接口 NodeToken 认证失败 |
| 500 | Internal Server Error | 服务未注册或内部异常 |

### A 组认证错误

所有 A 组接口在认证失败时返回：

```json
{ "message": "认证失败：Token 无效" }
```

或

```json
{ "message": "认证失败" }
```

### 定时任务错误

定时任务在服务未注册时返回：

```json
{ "error": "服务未注册: gateway_nodesService" }
```

---

> **接口总数**: 10 个端点（A 组 4 + 设备管理 2 + 定时任务 4）
> **实现位置**: `api_sqlsugar/VolPro.WebApi/Controllers/Warehouse/`