# 网关 ↔ Vol.Pro 自动注册机制检查报告 2026-06-03

> **日期**: 2026-06-03
> **检查范围**: `gateway/src/IntegrationGateway.Host/Program.cs` A1 注册段 + `VolPro gateway_nodesController.cs` A1-A4 + 相关 Service
> **方法**: 逐行比对网关发送体 ↔ Vol.Pro 接收体 ↔ 数据库 Schema

---

## 1. 数据流追踪

```
网关 Program.cs (line 82-105)
  ├─ InitializeAllAsync()               ← 适配器初始化
  ├─ RegisterAsync(registerReq)         ← A1: POST /api/gateway/register
  └─ (无后续调用)                        ← A2/A3 未触发

Vol.Pro gateway_nodesController
  ├─ [POST] /api/gateway/register       ← RegisterGateway → RegisterNodeAsync
  ├─ [POST] /api/gateway/heartbeat      ← GatewayHeartbeat → UpdateHeartbeatAsync
  ├─ [POST] /api/gateway/sync/devices   ← SyncDevices → SyncDevicesAsync
  └─ [POST] /api/gateway/sync/alarms    ← SyncAlarms → UpsertAlarmAsync
```

---

## 2. 发现的问题

### 2.1 🔴 网关不调用 A3 设备同步 — 注册后设备列表为空

**现状**: 网关 Program.cs 在 A1 注册后**不调用** `clientFactory.SyncDevicesAsync()`。Vol.Pro 的 `RegisterGateway` 返回设备列表时调用 `GetDevicesByGatewayNodeAsync(node.NodeId)`，查询 `WHERE NodeId=xxx AND ParentDeviceId IS NULL`。

**后果**: 首次注册返回的设备列表永远为空（数据库尚无此网关的设备记录）。设备必须等 Vol.Pro 的 Quartz `SyncDevicesJob`（每 5 分钟触发一次）才有机会同步。

**修复**: A1 注册后立即遍历适配器同步设备，整体流程改为：

```csharp
// A1 注册
var registerResult = await clientFactory.RegisterAsync(registerReq);
// A3 同步设备（Owl → GetDevicesAsync, MC4 → GetObjectTreeAsync）
foreach (var adapter in registry.All)
{
    var devices = adapter switch
    {
        IHasFlatDevices f => (await f.GetDevicesAsync(1, 1000)).Items,
        IHasOwnDeviceTree t => FlattenTree(await t.GetObjectTreeAsync()),
        _ => new()
    };
    if (devices.Any())
        await clientFactory.SyncDevicesAsync(nodeCode, nodeToken, devices.Select(d => new { ... }).ToList());
}
```

### 2.2 🔴 网关 A1 BaseUrl 硬编码 `localhost`

**现状**: 
```csharp
BaseUrl = $"http://localhost:{app.Urls.FirstOrDefault()?.Split(':').LastOrDefault() ?? "5100"}"
```

**后果**: 网关部署在 `192.168.1.100` 时，Vol.Pro 存的 BaseUrl 仍是 `http://localhost:5100`。Vol.Pro 端的 GatewayClient 和 Quartz Job 用此地址回调网关时全部失败。

**修复**: 改为读取配置或使用 `app.Configuration["Gateway:SelfUrl"]`，不填时降级为 `localhost`：

```csharp
BaseUrl = gwCfg["SelfUrl"] ?? $"http://localhost:{port}"
```

### 2.3 🟠 网关不调用 A2 心跳 — 无持续在线状态更新

**现状**: 网关只在 A1 注册时上报一次在线状态，之后不再调 A2 心跳。

**后果**: Vol.Pro 的 `gateway_nodes.LastHeartbeat` 停留在注册时刻，`HeartbeatMonitorJob`（每 15s）会在注册后 30s 将网关标记离线。

**修复**: 注册完成后启动后台心跳循环：

```csharp
_ = Task.Run(async () => {
    while (true)
    {
        await Task.Delay(TimeSpan.FromSeconds(15));
        try { await clientFactory.HeartbeatAsync(new GatewayHeartbeatRequest { NodeCode = nodeCode, Token = nodeToken }); }
        catch { Console.Error.WriteLine("[Gateway] 心跳失败"); }
    }
});
```

### 2.4 🟠 Vol.Pro — RegisterNodeAsync 使用旧 Queryable 语法

**现状**: 
```csharp
var existing = _repository.DbContext.Queryable<gateway_nodes>()
    .First(x => x.NodeCode == nodeCode);
```

`DbContext.Queryable` 是 SqlSugar 原始方式，项目中其他 Service 使用 `FindAsIQueryable`（Vol.Pro 封装）。

**后果**: 不影响功能但风格不一致。且 `.First()` 可能抛异常（找不到记录时），而 `.FirstOrDefault()` + null 检查更安全。

**修复**: 改为 `FindAsIQueryable(x => x.NodeCode == nodeCode).FirstOrDefaultAsync()`。

### 2.5 🟡 A1 返回结果未被网关使用

**现状**: 
```csharp
var registerResult = await clientFactory.RegisterAsync(registerReq);
// registerResult 未使用
```

`RegisterGateway` 返回 `{ nodeId, devices: [...] }`，网关不读取也不使用。

**后果**: 网关不知道自己的 NodeId，后续 A2/A3 需要 nodeCode + token 而非 nodeId。GatewayClientFactory 的 A2/A3 方法也用的是 nodeCode + token，所以不依赖 nodeId。

**评估**: **不需要修复** — 当前设计合理（nodeCode 是天然业务主键）。

### 2.6 🟡 base_deviceService 与 gateway_nodesService 重复实现设备同步

**现状**: 
- `gateway_nodesService.SyncDevicesAsync` — 完整的设备同步（新增+更新）
- `base_deviceService.UpsertDeviceAsync` — 单设备 Upsert（被 Controller 调用但实际未被使用）

`gateway_nodesController.SyncDevices` 调的是 `gateway_nodesService.SyncDevicesAsync` 而非 `base_deviceService.UpsertDeviceAsync`。

**后果**: `base_deviceService.UpsertDeviceAsync` 是死代码。

**修复**: 保留 `gateway_nodesService.SyncDevicesAsync`（批量处理更高效），移除或标记 `base_deviceService.UpsertDeviceAsync` 为 `[Obsolete]`。

---

## 3. 调用链完整性矩阵

| 接口 | Vol.Pro 端 | 网关调用 | 状态 |
|------|:---:|:---:|:--:|
| A1 /api/gateway/register | ✅ RegisterGateway | ✅ 已调用 | ⚠️ BaseUrl=localhost / 不返设备 |
| A2 /api/gateway/heartbeat | ✅ GatewayHeartbeat | ❌ 未调用 | 🔴 30秒后被标记离线 |
| A3 /api/gateway/sync/devices | ✅ SyncDevices | ❌ 未调用 | 🔴 首次注册设备列表为空 |
| A4 /api/gateway/sync/alarms | ✅ SyncAlarms | ❌ 未调用 | ⚪ 告警由 Vol.Pro Quartz 拉取 |

---

## 4. 修复优先级

| 编号 | 问题 | 严重度 | 预计 |
|:---:|------|:---:|:---:|
| 1 | A3 设备同步未触发 | 🔴 | 30min |
| 2 | A1 BaseUrl=localhost | 🔴 | 10min |
| 3 | A2 心跳未循环 | 🟠 | 15min |
| 4 | RegisterNodeAsync 语法不一致 | 🟠 | 5min |
| 5 | 重复的设备 Upsert 逻辑 | 🟡 | 10min |