425 lines
17 KiB
Markdown
425 lines
17 KiB
Markdown
# SecMPS 整合方案 v3.0
|
||
|
||
> 版本: 3.0
|
||
> 日期: 2025-05-17
|
||
> 状态: 草稿
|
||
|
||
---
|
||
|
||
## 1. 背景与目标
|
||
|
||
SecMPS 需要将多套异构子系统（视频监控、IoT动环、门禁道闸、报警）统一整合到 Vol.Pro 管理端。v2.0 采用 Vol.Pro 直接对接各子系统 API，存在紧耦合、协议适配散落、扩展困难等问题。
|
||
|
||
v3.0 引入 **IntegrationGateway（整合网关）** 作为统一中间层，面向子系统做协议适配，面向 Vol.Pro 提供标准化 REST API，实现"适配一次，多处复用"。
|
||
|
||
### 1.1 核心原则
|
||
|
||
| 原则 | 说明 |
|
||
|------|------|
|
||
| 适配器隔离 | 每个子系统一个 Adapter，实现统一接口，互不干扰 |
|
||
| 懒加载 | 适配器按需初始化，不阻塞网关启动 |
|
||
| 分页语义统一 | 统一 page/size 分页，适配器内部转换 skip/limit |
|
||
| 字段分治 | 网关负责"来源标识+在线状态"，Vol.Pro 负责"设备名称+扩展属性"，首次入库全量，后续仅更新网关字段 |
|
||
|
||
### 1.2 子系统清单
|
||
|
||
| 子系统 | 对接方式 | 适配器 | 核心能力 |
|
||
|--------|----------|--------|----------|
|
||
| Owl + ZLMediaKit | REST API | OwlAdapter | 视频设备发现、实时流、PTZ、录像回放、截图 |
|
||
| MC4.0 | REST API | MC4Adapter | 对象树、实时点值、设备控制、告警查询/确认/结束 |
|
||
|
||
---
|
||
|
||
## 2. 架构总览
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────┐
|
||
│ Vol.Pro 管理端 │
|
||
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────┐ │
|
||
│ │ gateway_nodes│ │ base_device │ │ device_manager │ │
|
||
│ │ Controller │ │ Controller │ │ (前端页面) │ │
|
||
│ │ A1-A4 │ │ GetRegion..│ │ RegionTree + │ │
|
||
│ │ │ │ GetDevices │ │ DeviceTable │ │
|
||
│ └──────┬───────┘ └──────┬───────┘ └────────┬────────┘ │
|
||
│ │ │ │ │
|
||
│ │ GatewayClient │ │ HTTP │
|
||
│ └────────┬────────┘ │ │
|
||
│ │ B3 (REST) │ │
|
||
└──────────────────┼─────────────────────────────┼──────────┘
|
||
│ │
|
||
┌──────────────────┼─────────────────────────────┼──────────┐
|
||
│ IntegrationGateway (net8.0) │ │
|
||
│ │ │ │
|
||
│ ┌───────────────┴──────────────────────────────┴───────┐ │
|
||
│ │ AdapterRegistry │ │
|
||
│ │ ┌─────────────┐ ┌─────────────┐ │ │
|
||
│ │ │ OwlAdapter │ │ MC4Adapter │ ... │ │
|
||
│ │ │ IHasFlat.. │ │ IHasOwnTree │ │ │
|
||
│ │ │ IHasStreams │ │ IHasPoints │ │ │
|
||
│ │ │ IHasPtz │ │ IHasAlarms │ │ │
|
||
│ │ └──────┬──────┘ └──────┬──────┘ │ │
|
||
│ └─────────┼────────────────┼───────────────────────────┘ │
|
||
│ │ │ │
|
||
│ ┌────────┴────────┐ ┌───┴──────────┐ │
|
||
│ │ Owl + ZLMediaKit│ │ MC4.0 │ │
|
||
│ │ (视频监控) │ │ (动环/IoT) │ │
|
||
│ └─────────────────┘ └──────────────┘ │
|
||
└──────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.1 数据流
|
||
|
||
```
|
||
MC4.0 对象树 → Mc4Adapter.GetObjectTree()
|
||
→ SyncEngine.ProcessMc4Tree()
|
||
→ type=1 节点 → warehouse_regions (区域匹配)
|
||
→ type=2 节点 → base_device (Upsert, 字段分治)
|
||
```
|
||
|
||
### 2.2 网关端口约定
|
||
|
||
| 服务 | 端口 | 说明 |
|
||
|------|------|------|
|
||
| IntegrationGateway | 5100 | 设备管理 REST API |
|
||
| Owl + ZLMediaKit | 15123 | 视频流/录像 |
|
||
| MC4.0 | 3000 | 动环数据/告警 |
|
||
| Vol.Pro | 9991 | 管理端后端 |
|
||
|
||
---
|
||
|
||
## 3. 核心接口体系
|
||
|
||
### 3.1 能力接口（Capability Interfaces）
|
||
|
||
```csharp
|
||
// 适配器按需实现，网关通过反射或接口判断自动发现能力
|
||
|
||
interface IHasFlatDevices { Task<PagedResult<StandardDevice>> GetDevicesAsync(int page, int size, string? keyword); }
|
||
interface IHasOwnDeviceTree { Task<List<DeviceTreeNode>> GetObjectTreeAsync(); }
|
||
interface IHasStreams { Task<StreamUrls> GetLiveUrlAsync(string channelId); Task<StreamUrls> GetPlaybackUrlAsync(string channelId, DateTime start, DateTime end); }
|
||
interface IHasPtz { Task PtzControlAsync(string channelId, string direction, float speed); }
|
||
interface IHasRecordings { Task<PagedResult<StandardRecording>> GetRecordingsAsync(string channelId, DateTime start, DateTime end, int page, int size); }
|
||
interface IHasPoints { Task<List<PointValue>> GetRealtimeValuesAsync(string sourceDeviceId); Task SetPointValueAsync(string sourceDeviceId, int pointIndex, double value); }
|
||
interface IHasAlarms { Task<PagedResult<StandardAlarm>> GetAlarmsAsync(int page, int size, DateTime from, DateTime to, ...); Task ConfirmAlarmAsync(string alarmId); Task EndAlarmAsync(string alarmId); }
|
||
interface IAcceptsMetadataPush { Task<MetadataPushResult> PushMetadataAsync(string sourceDeviceId, MetadataChangeSet changes); }
|
||
```
|
||
|
||
### 3.2 网关统一模型
|
||
|
||
```csharp
|
||
class StandardDevice {
|
||
int DeviceId; // Vol.Pro 侧主键（同步后回填）
|
||
string AdapterCode; // "Owl:main" / "MC4:31ku"
|
||
string SourceId; // 子系统原始 ID
|
||
string DeviceName;
|
||
string DeviceCategory; // 摄像机/温湿度变送器/...
|
||
string DeviceGroup; // 视频设备/IoT设备/门禁设备/...
|
||
bool IsParent;
|
||
string ParentSourceId;
|
||
bool IsOnline;
|
||
string IpAddress;
|
||
int? Port;
|
||
Dictionary<string,object?> Extra; // 子系统扩展属性
|
||
}
|
||
|
||
class StandardAlarm {
|
||
string AlarmId;
|
||
string DeviceId;
|
||
string AdapterCode;
|
||
string Level; // 提示/普通/重要/紧急
|
||
string Title;
|
||
string Content;
|
||
DateTime OccurTime;
|
||
string Status; // 未确认/已确认/已结束
|
||
double? ActualValue;
|
||
double? ThresholdValue;
|
||
}
|
||
|
||
class DeviceTreeNode {
|
||
string SourceId;
|
||
string Name;
|
||
int NodeType; // 1=区域, 2=设备
|
||
int ObjectType;
|
||
string Tag;
|
||
Dictionary<string,object?> Option;
|
||
List<DeviceTreeNode> Children;
|
||
}
|
||
```
|
||
|
||
### 3.3 订阅接口（B3，供 Vol.Pro 回调）
|
||
|
||
| 路由 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/gateway/register` | POST | 网关注册 (Upsert) |
|
||
| `/api/gateway/heartbeat` | POST | 心跳 |
|
||
| `/api/gateway/sync/devices` | POST | 设备数据同步 |
|
||
| `/api/gateway/sync/alarms` | POST | 告警同步 |
|
||
|
||
### 3.4 网关暴露接口
|
||
|
||
| 路由 | 适配器能力 | 说明 |
|
||
|------|-----------|------|
|
||
| `GET /devices?adapter={code}&page=&size=` | IHasFlatDevices | 分页获取设备列表 |
|
||
| `GET /tree?adapter={code}` | IHasOwnDeviceTree | 获取对象树 |
|
||
| `GET /streams/{adapter}/{deviceId}/live` | IHasStreams | 获取实时流地址 |
|
||
| `GET /streams/{adapter}/{deviceId}/playback` | IHasStreams | 获取回放地址 |
|
||
| `POST /streams/{adapter}/{deviceId}/snapshot` | IHasStreams | 获取截图 |
|
||
| `POST /streams/{adapter}/{deviceId}/ptz` | IHasPtz | 云台控制 |
|
||
| `GET /recordings/{adapter}/{deviceId}` | IHasRecordings | 获取录像列表 |
|
||
| `GET /points/{adapter}/{deviceId}` | IHasPoints | 获取实时点值 |
|
||
| `POST /points/{adapter}/{deviceId}` | IHasPoints | 控制写值 |
|
||
| `GET /alarms/{adapter}` | IHasAlarms | 分页获取告警 |
|
||
| `POST /alarms/{adapter}/{id}/confirm` | IHasAlarms | 确认告警 |
|
||
| `POST /alarms/{adapter}/{id}/end` | IHasAlarms | 结束告警 |
|
||
| `GET /health` | - | 适配器健康状态 |
|
||
|
||
---
|
||
|
||
## 4. 数据库设计
|
||
|
||
### 4.1 新增表（5 张，Vol.Pro 侧）
|
||
|
||
```sql
|
||
-- 网关节点表
|
||
CREATE TABLE gateway_nodes (
|
||
NodeId INT IDENTITY PRIMARY KEY,
|
||
NodeCode NVARCHAR(50) NOT NULL,
|
||
NodeName NVARCHAR(100),
|
||
NodeToken NVARCHAR(200),
|
||
AdapterTypes NVARCHAR(200), -- "Owl:main,MC4:31ku"
|
||
BaseUrl NVARCHAR(500),
|
||
IsOnline NVARCHAR(10), -- 在线/离线
|
||
Enable NVARCHAR(10), -- 启用/禁用
|
||
LastHeartbeat DATETIME,
|
||
CreateDate DATETIME,
|
||
CreateID INT,
|
||
Creator NVARCHAR(50),
|
||
ModifyDate DATETIME,
|
||
ModifyID INT,
|
||
Modifier NVARCHAR(50)
|
||
);
|
||
|
||
-- 统一设备表
|
||
CREATE TABLE base_device (
|
||
DeviceId INT IDENTITY,
|
||
AdapterCode NVARCHAR(50) NOT NULL, -- 联合主键
|
||
DeviceName NVARCHAR(100),
|
||
SourceId NVARCHAR(100) NOT NULL, -- 联合主键 (AdapterCode + SourceId = 唯一)
|
||
DeviceCategory NVARCHAR(50), -- 摄像机/硬盘录像机/温湿度变送器/...
|
||
DeviceGroup NVARCHAR(50), -- 视频设备/IoT设备/门禁设备/...
|
||
PointId INT NULL, -- FK → warehouse_devicepoint
|
||
GatewayNodeId INT NULL, -- FK → gateway_nodes
|
||
IsParent NVARCHAR(10),
|
||
ParentDeviceId INT NULL,
|
||
IsOnline NVARCHAR(10),
|
||
Enable NVARCHAR(10),
|
||
Protocol NVARCHAR(50),
|
||
IpAddress NVARCHAR(50),
|
||
Port INT NULL,
|
||
LastSyncTime DATETIME,
|
||
MapModelId NVARCHAR(100),
|
||
MapModelScale NVARCHAR(50),
|
||
MapModelRotation NVARCHAR(200),
|
||
ExtraData NVARCHAR(MAX), -- JSON 扩展属性
|
||
CreateDate DATETIME,
|
||
CreateID INT,
|
||
Creator NVARCHAR(50),
|
||
ModifyDate DATETIME,
|
||
ModifyID INT,
|
||
Modifier NVARCHAR(50),
|
||
PRIMARY KEY (DeviceId, AdapterCode)
|
||
);
|
||
|
||
-- 数据归档表
|
||
CREATE TABLE iot_devicedata (
|
||
DataId INT IDENTITY PRIMARY KEY,
|
||
DeviceId INT NULL,
|
||
AdapterCode NVARCHAR(50),
|
||
PointIndex INT,
|
||
Value FLOAT,
|
||
UpdateTime DATETIME,
|
||
CreateDate DATETIME
|
||
);
|
||
|
||
-- 告警记录表
|
||
CREATE TABLE iot_alarm (
|
||
AlarmId INT IDENTITY PRIMARY KEY,
|
||
SourceAlarmId NVARCHAR(100),
|
||
DeviceId INT NULL,
|
||
AdapterCode NVARCHAR(50),
|
||
AlarmLevel NVARCHAR(20),
|
||
AlarmDesc NVARCHAR(500),
|
||
AlarmValue FLOAT,
|
||
ThresholdValue FLOAT,
|
||
StartTime DATETIME,
|
||
EndTime DATETIME,
|
||
ConfirmTime DATETIME,
|
||
State NVARCHAR(20), -- 未确认/已确认/已结束
|
||
ConfirmUser NVARCHAR(50),
|
||
CreateDate DATETIME
|
||
);
|
||
|
||
-- 视频通道表（base_device 子表）
|
||
CREATE TABLE video_channel (
|
||
ChannelId INT NOT NULL,
|
||
DeviceId INT NOT NULL, -- FK → base_device
|
||
ChannelNo NVARCHAR(50),
|
||
SourceId NVARCHAR(100),
|
||
ChannelName NVARCHAR(100),
|
||
IsOnline NVARCHAR(10),
|
||
CreateDate DATETIME,
|
||
PRIMARY KEY (ChannelId, DeviceId)
|
||
);
|
||
|
||
-- 录像文件表
|
||
CREATE TABLE video_record (
|
||
RecordId INT IDENTITY PRIMARY KEY,
|
||
ChannelId INT NULL,
|
||
FilePath NVARCHAR(500),
|
||
Size BIGINT,
|
||
StartTime DATETIME,
|
||
EndTime DATETIME,
|
||
Duration FLOAT,
|
||
CreateDate DATETIME
|
||
);
|
||
```
|
||
|
||
### 4.2 字典初始化
|
||
|
||
```sql
|
||
-- 设备分类字典
|
||
INSERT INTO Sys_Dictionary (DicName, DicValue, DicNo, Config) VALUES
|
||
('设备分组', '视频设备', 'device_group_1', '视频设备'),
|
||
('设备分组', 'IoT设备', 'device_group_2', 'IoT设备'),
|
||
('设备分组', '门禁设备', 'device_group_3', '门禁设备'),
|
||
('设备分组', '道闸设备', 'device_group_4', '道闸设备'),
|
||
('设备分组', '报警设备', 'device_group_5', '报警设备');
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 管理端前端
|
||
|
||
### 5.1 页面结构
|
||
|
||
```
|
||
/web.vite/src/views/warehouse/DeviceManager/
|
||
├── index.vue 左右分栏主页面
|
||
├── api/
|
||
│ └── deviceManager.js API 封装
|
||
└── components/
|
||
├── RegionTree.vue 区域→点位树 (左侧)
|
||
├── DeviceTable.vue 设备列表 (右侧)
|
||
├── VideoDeviceActions.vue 视频设备操作按钮组
|
||
├── DeviceLivePreview.vue 实时预览弹窗
|
||
├── PtzControlPanel.vue 云台方向键面板
|
||
├── MapBindingPanel.vue 地图绑定面板
|
||
└── DeviceEditDialog.vue 设备编辑弹窗
|
||
```
|
||
|
||
### 5.2 路由
|
||
|
||
```
|
||
/device-manager → DeviceManager/index.vue
|
||
```
|
||
|
||
### 5.3 功能矩阵
|
||
|
||
| 功能 | 触发条件 | 组件 | 说明 |
|
||
|------|---------|------|------|
|
||
| 区域树展开 | 页面加载 | RegionTree | 调 GetRegionTree API |
|
||
| 设备列表 | 点击点位 | DeviceTable | 调 GetDevicesByPoint API |
|
||
| 实时预览 | 视频设备→预览 | DeviceLivePreview | WS-FLV 播放 |
|
||
| 云台控制 | 视频设备→云台 | PtzControlPanel | ↑↓←→ + ZOOM |
|
||
| 查看回放 | 视频设备→回放 | (待实现) | 录像时间轴 |
|
||
| 获取快照 | 视频设备→快照 | (待实现) | JPEG 快照 |
|
||
| 地图绑定 | 任意设备→地图 | MapBindingPanel | 模型 ID/缩放/旋转 |
|
||
| 编辑设备 | 非视频设备→编辑 | DeviceEditDialog | 名称/种类/分组/启用 |
|
||
|
||
---
|
||
|
||
## 6. 实施计划
|
||
|
||
### Phase 0: 基础设施（Day 1-2）
|
||
|
||
| Day | 内容 | 产出 |
|
||
|-----|------|------|
|
||
| 1 | 网关项目骨架 (net8.0) | IntegrationGateway.sln, Core/Host 项目, 7 个能力接口, 10 个统一模型, 3 个基础设施 (Registry/RateLimiter/HttpClientFactory) |
|
||
| 2 | Vol.Pro 侧集成 | GatewayClient, gateway_nodesController(A1-A4骨架), base_deviceController(骨架), Quartz Job, db_init.sql, 代码生成器产物 |
|
||
|
||
### Phase 1: Owl 适配器 + 管理端（Day 3-5）
|
||
|
||
| Day | 内容 | 产出 |
|
||
|-----|------|------|
|
||
| 3 | OwlAdapter | RSA 加密登录, 3 个接口实现 (IHasFlatDevices + IHasStreams + IAcceptsMetadataPush) |
|
||
| 4 | DeviceManager 页面框架 | RegionTree + DeviceTable + router |
|
||
| 5 | 视频组件 | 预览/云台/地图绑定/编辑弹窗 |
|
||
|
||
### Phase 2: MC4 适配器 + 联调（Day 6-11）
|
||
|
||
| Day | 内容 | 产出 |
|
||
|-----|------|------|
|
||
| 6 | 联调验证 (Owl + MC4) | 需子系统就绪 |
|
||
| 7 | MC4Adapter | Token 认证, IHasOwnDeviceTree + IHasPoints + IHasAlarms |
|
||
| 8 | 区域自动匹配 | SyncEngine, 字段分治, parentSourceId 映射 |
|
||
| 9 | 物联网操作接口 | 实时值读取, 控制写值 API |
|
||
| 10 | 告警集成 + SignalR | 告警查询/确认/结束, SignalR 实时推送 |
|
||
| 11 | 地图绑定 + Quartz | MapBindingPanel, SyncDevicesJob, HeartbeatMonitorJob |
|
||
|
||
### Phase 3: Warehouse 端（Day 12-17）
|
||
|
||
| Day | 内容 | 产出 |
|
||
|-----|------|------|
|
||
| 12 | 钥匙柜管理 | 钥匙柜设备 + 钥匙借还流程 |
|
||
| 13 | 巡更管理 | 巡更路径/点位/排班 |
|
||
| 14 | 门禁管理 | 门禁一体机 + 授权 |
|
||
| 15 | 道闸管理 | 人行道闸 + 车辆道闸 |
|
||
| 16 | 报警管理 | 紧急报警 + 离线报警 |
|
||
| 17 | 仓库页面整合 | 菜单 + 权限 |
|
||
|
||
### Phase 4: 验证发布（Day 18-20）
|
||
|
||
| Day | 内容 | 产出 |
|
||
|-----|------|------|
|
||
| 18 | 系统测试 | 功能测试 + 边界测试 |
|
||
| 19 | 性能优化 | 流性能 + 并发 + 缓存 |
|
||
| 20 | 文档 + 发布 | 部署手册, Dockerfile |
|
||
|
||
---
|
||
|
||
## 7. 风险与约束
|
||
|
||
| 风险 | 缓解措施 |
|
||
|------|----------|
|
||
| Vol.Pro 框架 API 与自主代码不兼容 | 网关层独立编译（dotnet build），Vol.Pro 后端逻辑骨架化，联调时一边调一边补 |
|
||
| Owl 接口不稳定 | 统一 2 QPS 限流 + 重试 |
|
||
| MC4 字段映射复杂 | 对象树 Option 弹性 JSON 字段，扩容不破坏现有映射 |
|
||
| 设备数量大导致同步慢 | 增量同步 + 批量 Upsert |
|
||
|
||
---
|
||
|
||
## 8. 环境配置
|
||
|
||
### 8.1 网关 appsettings.json
|
||
|
||
```json
|
||
{
|
||
"Owl": {
|
||
"BaseUrl": "http://owl_host:15123",
|
||
"Username": "admin",
|
||
"Password": "your_owl_password"
|
||
},
|
||
"MC4": {
|
||
"BaseUrl": "http://mc4_host:3000"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8.2 启动顺序
|
||
|
||
1. Owl + ZLMediaKit → 端口 15123
|
||
2. MC4.0 → 端口 3000
|
||
3. IntegrationGateway → 端口 5100 (`dotnet run --project src/IntegrationGateway.Host`)
|
||
4. Vol.Pro 后端 → 端口 9991
|
||
5. web.vite 前端 → 端口 9000 (`npm run dev`)
|