v3.0_manual_fresh_gateway

2026-05-16 15:51:59 +08:00
parent 07dd459705
commit 5790d3e8bf
1 changed files with 102 additions and 59 deletions
--- a/doc/整合方案/SecMPS_整合项目实施手册_v3.0.md
+++ b/doc/整合方案/SecMPS_整合项目实施手册_v3.0.md
@@ -8,39 +8,6 @@

 ---

-## 网关代码兼容性评估
-
-> 基于 v3.0 方案对 Phase 0 已生成的 gateway/ 代码进行评估
-
-| 组件 | 状态 | 说明 |
-|------|:---:|------|
-| Core/Abstractions (7接口) | ✅ 可用 | 与 v3.0 完全兼容 |
-| Core/Models (10模型) | ✅ 可用 | 与 v3.0 完全兼容 |
-| Core/Infrastructure (AdapterRegistry/TokenManager/RateLimiter) | ✅ 可用 | 无变更 |
-| Host/Program.cs | ⚠️ 需微调 | 增加 HttpClient 注册 |
-| Host/HealthController | ✅ 可用 | B1 接口无变更 |
-| Host/DevicesController | ✅ 可用 | B2 接口无变更 |
-| Host/PointsController | ✅ 可用 | B4/B5 接口无变更 |
-| Host/AlarmsController | ✅ 可用 | B8/B9 接口无变更 |
-| Host/SyncController | ✅ 可用 | B3 接口无变更 |
-| Host/StreamsController | ⚠️ 需增加 | 缺少 B6b playback 端点 |
-| Host/RegisterController | ❌ 缺失 | 需新建 A1/A2 接口 |
-| appsettings.json | ❌ 需重写 | 需改为 v3.0 格式 |
-| IGatewayClient (调用Vol.Pro) | ❌ 缺失 | 需新建 |
-
-### 结论
-
-**现有代码 70% 可用**，需 5 处改动：
-1. 重写 `appsettings.json`（删除适配器硬编码，改为 VolProUrl/NodeCode/NodeToken）
-2. 新增 `RegisterController.cs`（A1 注册 + A2 心跳）
-3. `StreamsController.cs` 增加 B6b playback 端点
-4. `Program.cs` 增加 `HttpClient` 注册 + 网关启动时调 Vol.Pro 注册
-5. 新增 `GatewayClient.cs`（网关调用 Vol.Pro API 的 HTTP 封装）
-
-预计改动量：约 200 行新增代码，不改动现有接口和模型。
-
---
-
 ## 分支管理策略

 ```
@@ -78,11 +45,56 @@ git commit -m "Phase {n}: {标题}" && git push && git tag phase-{n}-done

 ## Phase 0：基础设施（Day 1-2）

-### Day 1 — 网关代码修正 + 数据库
+### Day 1 — 从头搭建网关 + 数据库

-**任务 1.1**: 修正 gateway/ 代码（5 处改动，约 200 行）
+**任务 1.1 — 创建 Gateway 解决方案**

-1. 重写 `appsettings.json`:
+在 `gateway/` 目录下:
+```
+dotnet new sln -n IntegrationGateway
+dotnet new webapi -n IntegrationGateway.Host -f net8.0
+dotnet new classlib -n IntegrationGateway.Core -f net8.0
+dotnet sln add src/IntegrationGateway.Host src/IntegrationGateway.Core
+dotnet add src/IntegrationGateway.Host reference src/IntegrationGateway.Core
+dotnet add src/IntegrationGateway.Core package Microsoft.Extensions.Caching.Memory
+```
+验证: `dotnet build` 零错误。
+
+**任务 1.2 — Core 层（接口 + 模型 + 基础设施）**
+
+`Abstractions/` — 7 个分型接口:
+- `IIntegrationAdapter` (基础: AdapterCode/HealthCheck/Initialize)
+- `IHasOwnDeviceTree` (MC4)、`IHasFlatDevices` (Owl)、`IHasPoints` (MC4)
+- `IHasStreams` (Owl)、`IHasAlarms` (通用)、`IAcceptsMetadataPush` (Owl)
+
+`Models/` — 10 个标准化模型:
+- `StandardDevice/DeviceTreeNode/StandardPoint/PointValue/StandardAlarm`
+- `StreamUrls/SyncReport/PagedResult/AdapterCapabilities/StandardRecording`
+
+`Infrastructure/` — 3 个基础设施:
+- `AdapterRegistry` (适配器注册与发现)
+- `TokenManager` (通用内存 Token 缓存)
+- `RateLimiter` (SemaphoreSlim 频率控制)
+
+验证: `dotnet build` 零错误 + 单元测试 mock 适配器通过。
+
+**任务 1.3 — Host 层 Controller（7 个）**
+
+| Controller | 对应 API | 说明 |
+|------------|----------|------|
+| `HealthController` | B1 | 健康检查 |
+| `DevicesController` | B2 | 设备列表 |
+| `PointsController` | B4/B5 | 实时数据+控制 |
+| `StreamsController` | B6a/B6b/B7 | 取流+回放+云台 |
+| `AlarmsController` | B8/B9 | 告警查询+确认 |
+| `SyncController` | B3 | 手动同步 |
+| `RegisterController` | A1/A2 | 网关注册+心跳 |
+
+验证: 启动 Host，`GET /api/gateway/health` → 200。
+
+**任务 1.4 — 网关配置 + 启动注册**
+
+`appsettings.json`:
 ```json
 {
  "VolProBaseUrl": "http://localhost:9100",
@@ -92,49 +104,80 @@ git commit -m "Phase {n}: {标题}" && git push && git tag phase-{n}-done
 }
 ```

-2. 新增 `RegisterController.cs`:
- `POST /api/gateway/register` — 网关启动注册（Upsert 数据库）
- `POST /api/gateway/heartbeat` — 网关每 15s 心跳
-
-3. `StreamsController.cs` 增加:
- `GET {adapter}/{channelId}/playback?start=&end=` — 回放取流
-
-4. `Program.cs` 增加:
+`Program.cs` 启动逻辑:
 ```csharp
+builder.Services.AddControllers();
+builder.Services.AddMemoryCache();
 builder.Services.AddHttpClient("VolPro", c => {
    c.BaseAddress = new Uri(builder.Configuration["VolProBaseUrl"]);
 });
-// 启动后自动注册
-var registry = app.Services.GetRequiredService<AdapterRegistry>();
-var http = app.Services.GetRequiredService<IHttpClientFactory>();
-await RegisterWithVolPro(registry, http, app.Configuration);
+builder.Services.AddSingleton<AdapterRegistry>();
+builder.Services.AddSingleton<TokenManager>();
+// 启动后自动调 Vol.Pro 注册
+app.Lifetime.ApplicationStarted.Register(() => {
+    Task.Run(() => RegisterWithVolPro(app));
+});
 ```

-5. 新增 `GatewayClient.cs`:
-网关调用 Vol.Pro API 的封装类（注册/心跳/同步设备/同步告警）
+新增 `GatewayClient.cs` — 封装网关→Vol.Pro 的 HTTP 调用（A1注册/A2心跳/A3设备同步/A4告警同步）。

-验证: `dotnet build` 零错误 + Gateway `/health` 200
+验证: 网关启动后调 Vol.Pro 的 A1 端点成功，返回 nodeId。

-**任务 1.2**: 执行 db_init.sql（6张表）。验证: 唯一索引存在。
+**任务 1.5 — 执行 db_init.sql（6张表）**

-**任务 1.3**: Vol.Pro 侧 GatewayClient 实现 + `GatewayNodeController.cs`（A1/A2/A3/A4 服务端）。验证: 可成功注册并心跳。
+验证: `SELECT COUNT(*) FROM base_device` → 0，唯一索引 `(AdapterCode, SourceId)` 存在。

-### Day 2 — 代码生成 + 字典初始化
+### Day 2 — Vol.Pro 侧集成 + 代码生成 + 字典

-**任务 2.1**: 代码生成器跑 6 张表。
+**任务 2.1 — Vol.Pro GatewayClient** (后端调网关的 HTTP 封装)

-**任务 2.2**: `DeviceManagerController.cs` (Partial/)。
+新增 `api_sqlsugar/VolPro.Core/Infrastructure/GatewayClient.cs` (IDependency)。
+封装: 注册/心跳/设备同步/告警同步/实时数据/取流/云台/告警确认。

-**任务 2.3**: 字典初始化（8个）。
+**任务 2.2 — Vol.Pro GatewayNodeController** (A组接口服务端)

-**任务 2.4**: `SyncDevicesJob` + 心跳超时检测 Job。
+新增 `Controllers/Warehouse/Partial/GatewayNodeController.cs`:
+- `POST /api/gateway/register` (A1) — Upsert gateway_nodes, 返回设备列表
+- `POST /api/gateway/heartbeat` (A2) — 更新 LastHeartbeat
+- `POST /api/gateway/sync/devices` (A3) — 设备同步(字段分治+parentSourceId映射)
+- `POST /api/gateway/sync/alarms` (A4) — 告警同步
+
+验证: Postman 模拟网关调 A1 注册，返回 nodeId+设备列表。
+
+**任务 2.3 — DeviceManagerController**
+
+新增 `Controllers/Warehouse/Partial/DeviceManagerController.cs`:
+- `GET GetRegionTree` — 区域→点位→设备树
+- `GET GetDevicesByPoint?pointId=` — 点位下设备列表(含子设备)
+- `PUT {deviceId}` — 更新设备(含地图绑定)
+
+验证: Postman `GET /api/DeviceManager/GetRegionTree` → JSON。
+
+**任务 2.4 — 代码生成器**
+
+对 6 张表运行 Vol.Pro 代码生成器。
+
+验证: 管理端 6 个新菜单可 CRUD。
+
+**任务 2.5 — 字典初始化**
+
+在 Vol.Pro 管理端创建 8 个数据字典（设备种类/设备分组/是否父设备/在线状态/启用状态/是否控制点/告警等级/告警状态）。
+
+验证: base_device 编辑表单中 DeviceCategory 下拉可选到字典值。
+
+**任务 2.6 — Quartz Job**
+
+- `SyncDevicesJob` — 定时调网关同步
+- `HeartbeatMonitorJob` — 超 30s 无心跳级联设备离线
+
+验证: Quartz 面板看到已注册 Job。

 ### 合并

 ```bash
 git add -A && git commit -m "Phase 0 完成"
 git checkout master && git merge --squash phase/0-infrastructure
-git commit -m "Phase 0: 网关修正 + 6张表 + 代码生成 + 字典"
+git commit -m "Phase 0: 网关骨架 + 6张表 + 代码生成 + 字典 + API"
 git push && git tag phase-0-done
 ```