diff --git a/doc/整合方案/SecMPS_整合项目实施手册_v3.0.md b/doc/整合方案/SecMPS_整合项目实施手册_v3.0.md index b2937c5..9ff4b87 100644 --- a/doc/整合方案/SecMPS_整合项目实施手册_v3.0.md +++ b/doc/整合方案/SecMPS_整合项目实施手册_v3.0.md @@ -8,6 +8,39 @@ --- +## 网关代码兼容性评估 + +> 基于 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 行新增代码,不改动现有接口和模型。 + +--- + ## 分支管理策略 ``` @@ -17,36 +50,14 @@ master ──────────────────────── └── infrastructure └── owl-video └── mc4-iot └── ``` -**规则**:每个 Phase 从 `master` 切分支 → 开发完成 → `git merge --squash` 合并回 `master`(一个提交)。出错直接删分支重切,零代价。 - -### 项目约定 - -``` -SecMPS/ -├── api_sqlsugar/ ← Vol.Pro 后端 -├── web.vite/ ← 管理端 -├── warehouse/ ← 用户大屏端 -├── owl_zlmediakit/ ← Owl+ZLM 部署包 (Owl管理端口:15123) -├── doc/ ← 文档 -└── gateway/ ← IntegrationGateway(独立顶层文件夹) -``` - ### 每个 Phase 标准流程 ```bash -# 开始 git checkout master git checkout -b phase/{n}-{name} - -# 开发(随时提交) -git add -A && git commit -m "具体改动描述" - -# 完成后合并 -git checkout master -git merge --squash phase/{n}-{name} -git commit -m "Phase {n}: {标题}" -git push -git tag phase-{n}-done +# 开发 + 提交 +git checkout master && git merge --squash phase/{n}-{name} +git commit -m "Phase {n}: {标题}" && git push && git tag phase-{n}-done ``` --- @@ -55,8 +66,8 @@ git tag phase-{n}-done | # | 检查项 | 验证方式 | 阻塞 | |---|--------|----------|------| -| 1 | Owl+ZLM 部署运行 | 浏览器访问 http://owl_ip:15123 管理端 | Phase 1 | -| 2 | 至少1台 GB28181 设备注册到 Owl | Owl `/devices` 有数据 | Phase 1 | +| 1 | Owl+ZLM 部署运行 | 浏览器 http://owl_ip:15123 | Phase 1 | +| 2 | 至少1台 GB28181 设备注册到 Owl | Owl /devices 有数据 | Phase 1 | | 3 | MC4.0 网关可访问 | curl :3000 /api/central/auth/conf/get | Phase 2 | | 4 | MC4.0 有设备接入 | 对象树有 type=2 节点 | Phase 2 | | 5 | 代码生成器可用 | 新建测试表→生成→确认 | Phase 0 | @@ -67,227 +78,95 @@ git tag phase-{n}-done ## Phase 0:基础设施(Day 1-2) -```bash -git checkout master && git checkout -b phase/0-infrastructure +### Day 1 — 网关代码修正 + 数据库 + +**任务 1.1**: 修正 gateway/ 代码(5 处改动,约 200 行) + +1. 重写 `appsettings.json`: +```json +{ + "VolProBaseUrl": "http://localhost:9100", + "NodeCode": "gw-31ku", + "NodeToken": "xxxxxxxxxx", + "Urls": "http://*:5100" +} ``` -### Day 1 — Gateway 骨架 + 数据库 +2. 新增 `RegisterController.cs`: +- `POST /api/gateway/register` — 网关启动注册(Upsert 数据库) +- `POST /api/gateway/heartbeat` — 网关每 15s 心跳 -**任务 1.1**: 在 `gateway/` 下创建 IntegrationGateway 解决方案。验证: `dotnet build`。 +3. `StreamsController.cs` 增加: +- `GET {adapter}/{channelId}/playback?start=&end=` — 回放取流 -**任务 1.2**: Core 层 7 接口 + 10 模型 + AdapterRegistry/TokenManager/RateLimiter。验证: 单元测试 mock 适配器。 +4. `Program.cs` 增加: +```csharp +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); +``` -**任务 1.3**: Host 层 6 Controller (Health/Devices/Points/Streams/Alarms/Sync) + RegisterController。验证: `GET /api/gateway/health` → 200。 +5. 新增 `GatewayClient.cs`: +网关调用 Vol.Pro API 的封装类(注册/心跳/同步设备/同步告警) -**任务 1.4**: 6 张表 DDL 执行(base_device/video_channel/video_record/iot_devicedata/iot_alarm/gateway_nodes)。验证: 唯一索引存在。 +验证: `dotnet build` 零错误 + Gateway `/health` 200 -**任务 1.5**: 代码生成器跑 6 张表。验证: 管理端 6 个新菜单可 CRUD。 +**任务 1.2**: 执行 db_init.sql(6张表)。验证: 唯一索引存在。 -### Day 2 — Vol.Pro 侧 + 字典初始化 +**任务 1.3**: Vol.Pro 侧 GatewayClient 实现 + `GatewayNodeController.cs`(A1/A2/A3/A4 服务端)。验证: 可成功注册并心跳。 -**任务 2.1**: `GatewayClient.cs` (IDependency) + `GatewayNodeController.cs` (注册/心跳)。验证: 注入 HealthCheckAsync() → true。 +### Day 2 — 代码生成 + 字典初始化 -**任务 2.2**: `DeviceManagerController.cs` (Partial/) — GetRegionTree / GetDevicesByPoint / PUT。验证: Postman 返回 JSON。 +**任务 2.1**: 代码生成器跑 6 张表。 -**任务 2.3**: `SyncDevicesJob` (Quartz) + 心跳超时检测 Job。验证: Quartz 面板看到 Job。 +**任务 2.2**: `DeviceManagerController.cs` (Partial/)。 -**任务 2.4**: ★ 数据字典初始化(8个字典): +**任务 2.3**: 字典初始化(8个)。 -| 字典名称 | 字典值 | -|----------|--------| -| 设备种类 | 门磁/空调/智能断路器/人行道闸/车辆道闸/... (18个) | -| 设备分组 | 视频设备/IoT设备/门禁设备/道闸设备/报警设备 | -| 是否父设备 | 是/否 | -| 在线状态 | 在线/离线 | -| 启用状态 | 启用/禁用 | -| 是否控制点 | 只读/可写 | -| 告警等级 | 提示/普通/重要/紧急 | -| 告警状态 | 未确认/已确认/已结束 | - -**验证**: 在 base_device 编辑表单中 DeviceCategory 下拉框可选到字典值。 +**任务 2.4**: `SyncDevicesJob` + 心跳超时检测 Job。 ### 合并 ```bash git add -A && git commit -m "Phase 0 完成" git checkout master && git merge --squash phase/0-infrastructure -git commit -m "Phase 0: Gateway骨架 + 6张表 + 代码生成 + 字典初始化" +git commit -m "Phase 0: 网关修正 + 6张表 + 代码生成 + 字典" git push && git tag phase-0-done ``` --- -## Phase 1:Owl 适配器 + 管理端视频设备页(Day 3-6) +## Phase 1:Owl 适配器 + 视频设备页(Day 3-6) -```bash -git checkout master && git checkout -b phase/1-owl-video -``` +Owl 端口: **15123**(非 80)。PTZ 仅方向键(continuous+stop),不支持预设位。 ### Day 3 — OwlAdapter - -创建 `Adapters.Owl` 项目,实现 `IHasFlatDevices+IHasStreams+IAcceptsMetadataPush`。 - -关键实现细节: -- Token: 调 `GET /login/key` → RSA加密 → `POST /login` → 缓存 JWT(3天有效) -- 设备同步: `GET /devices` + `GET /channels` → OwlDevice[] → StandardDevice[] -- Owl 管理端口: **15123**(非 80) - -验证(Postman → Gateway): -``` -GET /health → {"owl":true} -GET /devices?adapter=owl → Owl设备列表 -GET /streams/owl/{id}/live → WS-FLV地址 -``` - -端到端同步 → `SELECT * FROM base_device WHERE AdapterCode LIKE 'Owl%'` 有数据。 +创建 Adapters.Owl,实现 IHasFlatDevices+IHasStreams+IAcceptsMetadataPush。Token: GET /login/key → RSA → POST /login。 ### Day 4 — 管理端设备页面框架 - -`DeviceManager/index.vue`(左右分栏) + `RegionTree.vue`(el-tree: 区域→点位→设备) + `DeviceTable.vue`(el-table 可展开)。 - -验证: `/device-manager` 页面可用。 +DeviceManager/index.vue + RegionTree.vue + DeviceTable.vue。 ### Day 5 — 视频操作 + Jessibuca +VideoDeviceActions.vue + 播放弹窗 + 方向键云台面板。 -`VideoDeviceActions.vue`(按钮组)+ `DeviceLivePreview.vue`(Jessibuca 弹窗)+ 云台控制面板(仅方向键 ↑↓←→ + 停止,不包含预置位)。 - -验证: 实时预览播放画面、方向键控制。 - -### Day 6 — 联调 + 边界测试 - -| 测试 | 预期 | -|------|------| -| 设备同步 | 表格数据刷新,不重复 | -| 实时预览 | Jessibuca 播放正常(首发有 1-3s 延迟) | -| 云台控制 | 方向键有效,预置位不存在 | -| 多路播放(4路) | 不卡顿 | -| 离线设备 | 状态显示「离线」 | -| 框架隔离 | 重跑生成器,DeviceManager/ 文件未丢失 | - -#### [可选] Owl AI 事件接入 - -OwlAdapter 可选实现 IHasAlarms → 将 Owl `GET /events` 的 YOLO 检测事件映射为 StandardAlarm → 走 A4 告警同步。 - -### 合并 - -```bash -git add -A && git commit -m "Phase 1 完成" -git checkout master && git merge --squash phase/1-owl-video -git commit -m "Phase 1: OwlAdapter + 管理端视频设备页 (RegionTree+Jessibuca)" -git push && git tag phase-1-done -``` +### Day 6 — 联调 + [可选]AI事件接入 --- -## Phase 2:MC4.0 适配器 + IoT 管理(Day 7-11) +## Phase 2:MC4.0 + IoT(Day 7-11) -```bash -git checkout master && git checkout -b phase/2-mc4-iot -``` - -### Day 7 — Mc4Adapter - -实现 `IHasOwnDeviceTree+IHasPoints+IHasAlarms`。验证: Postman 调 Gateway `/health`、`/sync`、`/realtime`、`/control`、`/alarms`、`/confirm` 全部通过。 - -### Day 8 — 区域自动匹配 - -SyncEngine.ProcessTreeNode: type=1 → MatchOrCreateRegion, type=2 → UpsertDevice。 - -验证: 同步后 `warehouse_regions` 有 MC4.0 区域,`base_device.PointId` 正确。 - -### Day 9 — IoT 操作 + 实时数据 - -`IoTDeviceActions.vue` + 实时数据弹窗(含开关/滑块控件)。 - -验证: 拖动滑块 → 设备实际值改变。 - -### Day 10 — 告警 + 地图绑定 - -编辑弹窗告警 tab + `MapBindingPanel.vue`。 - -验证: 地图绑定保存后值持久化。 - -### Day 11 — SignalR + Quartz - -`IoTDataHub.cs` + `RealtimePollJob`(5s) + `AlarmPollJob`(10s)。 - -验证: warehouse 端 SignalR 收到实时数据和告警。 - -### 合并 - -```bash -git add -A && git commit -m "Phase 2 完成" -git checkout master && git merge --squash phase/2-mc4-iot -git commit -m "Phase 2: Mc4Adapter + SyncEngine + SignalR + Quartz + 地图绑定" -git push && git tag phase-2-done -``` +同上 v2.1 手册,增加 MC4.0 skip/limit 分页转换。 --- -## Phase 3:warehouse 端 + 全链路联调(Day 12-17) +## Phase 3:warehouse 联调(Day 12-17) +## Phase 4:验证发布(Day 18-20) -```bash -git checkout master && git checkout -b phase/3-warehouse -``` - -### Day 12-13 — 视频播放器 - -Live.vue / History.vue / VideoWall.vue 假数据→真实 API + Jessibuca。 - -验证: 全功能可用。 - -### Day 14-15 — IoT 面板 - -实时数据看板(SignalR) / 控制面板 / 告警面板。 - -验证: warehouse IoT 功能可用。 - -### Day 16-17 — 全链路联调 - -设备同步→入库、区域→点位→设备树、实时预览→播放、云台→转动(仅方向)、实时数据→更新、控制→响应、告警→弹窗(<15s)、确认→双向写回。 - -性能: 9路视频≥15fps, 100设备轮询<3s, 500设备同步<30s。 - -### 合并 - -```bash -git add -A && git commit -m "Phase 3 完成" -git checkout master && git merge --squash phase/3-warehouse -git commit -m "Phase 3: warehouse视频+IoT面板 + 全链路联调" -git push && git tag phase-3-done -``` - ---- - -## Phase 4:验证 + 发布(Day 18-20) - -```bash -git checkout master && git checkout -b phase/4-verify -``` - -### Day 18 — 代码隔离验证 - -重跑生成器 → Partial/extension/DeviceManager 目录未被覆盖。 - -### Day 19 — 异常场景 - -Owl/MC4.0/Gateway 宕机不崩溃,Token 过期自动刷新,网关重启 NodeId 复用,并发同步互不干扰。 - -### Day 20 — 文档收尾 - -API 文档、部署手册、组件说明。 - -### 合并 + 发布 - -```bash -git add -A && git commit -m "Phase 4 完成" -git checkout master && git merge --squash phase/4-verify -git commit -m "Phase 4: 代码隔离验证 + 异常测试 + 文档" -git push && git tag phase-4-done - -git tag -a v3.0.0 -m "SecMPS v3.0: IntegrationGateway + 统一设备管理" -git push origin v3.0.0 -``` +同上 v2.1 手册,发布标签 v3.0.0。 --- @@ -295,13 +174,11 @@ git push origin v3.0.0 ``` □ 新增 C# 服务实现 IDependency -□ Controller 写在 Partial/ 目录 +□ Controller 在 Partial/ 目录 □ 前端在 extension/ 目录 □ 未修改自动生成文件 -□ MC4.0 经 RateLimiter -□ Owl Token 用 TokenManager -□ 网关同步走字段分治(管理员字段不覆盖) -□ parentSourceId 已映射为 ParentDeviceId +□ 网关同步走字段分治 +□ parentSourceId 已映射 □ 实时数据未写 IoT_DeviceData □ dotnet build 零错误 ``` @@ -315,15 +192,14 @@ git push origin v3.0.0 | web.vite | 9000 | | warehouse | 9200 | | Owl 管理端 | **15123** | -| ZLMediaKit (由Owl管理) | 8000 | | MC4.0 | 3000 | -## 附录 C:里程碑标签 +## 附录 C:里程碑 | 标签 | 指向 | |------|------| -| `phase-0-done` | Gateway 骨架 + 6张表 + 字典初始化 | -| `phase-1-done` | OwlAdapter + 视频设备页 | +| `phase-0-done` | 网关修正 + 6张表 + 字典 | +| `phase-1-done` | OwlAdapter + 视频页 | | `phase-2-done` | Mc4Adapter + IoT + SignalR | | `phase-3-done` | warehouse + 联调 | | `phase-4-done` | 验证 + 文档 | @@ -331,5 +207,4 @@ git push origin v3.0.0 --- -> **文档结束** -> **取代**: SecMPS_整合项目实施手册_v2.1.md +> 取代: SecMPS_整合项目实施手册_v2.1.md