diff --git a/doc/整合方案/SecMPS_整合项目实施手册_v3.0.md b/doc/整合方案/SecMPS_整合项目实施手册_v3.0.md index 9ff4b87..153efa2 100644 --- 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(); -var http = app.Services.GetRequiredService(); -await RegisterWithVolPro(registry, http, app.Configuration); +builder.Services.AddSingleton(); +builder.Services.AddSingleton(); +// 启动后自动调 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 ```