# 网关自动注册机制整改 — 任务清单

> **版本**: 1.0
> **日期**: 2026-06-03
> **基准**: `doc/设计文档/网关自动注册机制整改方案_v1.0.md` + `doc/设计文档/网关自动注册机制检查报告20260603.md`
> **原则**: 分阶段分步骤执行，每步骤完成编译复查后提交，不合并主分支

---

## 阶段 G1: Gateway 端修复（3 步骤）

### 步骤 G1.1 — 修复 BaseUrl 硬编码

- [ ] 编辑 `gateway/src/IntegrationGateway.Host/Program.cs`
- [ ] 将 `BaseUrl = $"http://localhost:..."` 改为读取 `gwCfg["SelfUrl"]`，不填降级 localhost
- [ ] 编辑 `gateway/src/IntegrationGateway.Host/appsettings.json`，Gateway 段新增 `"SelfUrl": null`
- [ ] `dotnet build gateway/IntegrationGateway.slnx` → 0 错误
- [ ] 复查：`BaseUrl` 不再硬编码 localhost，可从配置注入真实 IP

> **G1.1 提交点**: `Fix-G1.1: Gateway A1 BaseUrl 改为读取 SelfUrl 配置`

### 步骤 G1.2 — A1 注册后追加 A3 设备同步

- [ ] 编辑 `gateway/src/IntegrationGateway.Host/Program.cs`
- [ ] A1 注册成功后：遍历 `registry.All`，`IHasFlatDevices` → `GetDevicesAsync`，`IHasOwnDeviceTree` → `GetObjectTreeAsync` + 展平
- [ ] 新增 `FlattenTree` 辅助函数（MC4 对象树展平）
- [ ] 调 `clientFactory.SyncDevicesAsync(nodeCode, nodeToken, allDevices)`
- [ ] `dotnet build` → 0 错误
- [ ] 复查：A1 成功后立即执行 A3，注册完成时 Vol.Pro 已有设备数据

> **G1.2 提交点**: `Fix-G1.2: A1注册后立即A3同步全部适配器设备列表`

### 步骤 G1.3 — 启动 A2 心跳 + 自动重注册

- [ ] 编辑 `gateway/src/IntegrationGateway.Host/Program.cs`
- [ ] A1/A3 完成后启动 `Task.Run` 心跳循环
- [ ] `PeriodicTimer` 每 15s → `clientFactory.HeartbeatAsync`
- [ ] 连续失败 ≥ 3 次 → 触发 A1+A3 重注册
- [ ] 新增 `SyncAllDevicesAsync` 辅助函数（复用 A3 逻辑）
- [ ] `dotnet build` → 0 错误
- [ ] 复查：心跳成功重置 `failCount`，失败累积到 3 次自动恢复

> **G1.3 提交点**: `Fix-G1.3: A2心跳+自动重注册(连续3次失败触发A1+A3)`

---

## 阶段 G2: Vol.Pro 端修复（2 步骤）

### 步骤 G2.1 — RegisterNodeAsync 语法规范化

- [ ] 编辑 `api_sqlsugar/Warehouse/Services/device_manager/Partial/gateway_nodesService.cs`
- [ ] `RegisterNodeAsync`：`DbContext.Queryable.First()` → `FindAsIQueryable.FirstOrDefaultAsync()`
- [ ] `UpdateHeartbeatAsync`：同样替换
- [ ] `dotnet build api_sqlsugar/Warehouse` → 0 错误
- [ ] 复查：两个方法使用统一 Vol.Pro 查询语法，`.First()` 不抛异常

> **G2.1 提交点**: `Fix-G2.1: gateway_nodesService 统一 FindAsIQueryable 语法`

### 步骤 G2.2 — 标记 UpsertDeviceAsync 为废弃

- [ ] 编辑 `api_sqlsugar/Warehouse/Services/device_manager/Partial/base_deviceService.cs`
- [ ] `UpsertDeviceAsync` 加 `[Obsolete]` 标记 + 注释说明
- [ ] 检查接口文件 `Ibase_deviceService` 是否暴露此方法，同步标记
- [ ] `dotnet build` → 0 错误（允许 [Obsolete] 警告）
- [ ] 复查：重复逻辑已标记，新代码不会误用

> **G2.2 提交点**: `Fix-G2.2: base_deviceService.UpsertDeviceAsync 标记 [Obsolete]`

---

## 阶段 G3: 全量验证（1 步骤）

### 步骤 G3.1 — 全量编译 + 联调场景验证

- [ ] `dotnet build gateway/IntegrationGateway.slnx` → 0 错误
- [ ] `dotnet build api_sqlsugar/VolPro.WebApi` → 0 错误
- [ ] 网关启动 → 控制台输出 A1 注册 → A3 同步 N 台 → A2 心跳启动
- [ ] `gateway_nodes` 表有记录，`LastHeartbeat` 持续更新
- [ ] `base_device` 表有对应设备
- [ ] 网关先启动（Vol.Pro 未启动）→ 45 秒后自动恢复
- [ ] 复查：全链路 A1→A3→A2 闭环正常

> **G3.1 提交点**: `Fix-G3: 全量编译验证通过 注册机制闭环完成`

---

## 任务总览

| 阶段 | 步骤 | 文件 | 预计 |
|:---:|:---:|------|:---:|
| G1 | G1.1 BaseUrl 修复 | Program.cs + appsettings.json | 10min |
| G1 | G1.2 A3 设备同步 | Program.cs | 30min |
| G1 | G1.3 心跳+重注册 | Program.cs | 20min |
| G2 | G2.1 语法规范化 | gateway_nodesService.cs | 5min |
| G2 | G2.2 标记废弃方法 | base_deviceService.cs | 10min |
| G3 | G3.1 全量验证 | 全项目 | 15min |
| **合计** | **6 步骤** | **5 文件** | **~1.5h** |