Compare commits
27 Commits
phase/0-in
...
943bab875a
| Author | SHA1 | Date | |
|---|---|---|---|
| 943bab875a | |||
| 5790d3e8bf | |||
| 07dd459705 | |||
| fcd1d39641 | |||
| 65f4b793d3 | |||
| 1c2d33b341 | |||
| fe90fbea3a | |||
| 30e4187e34 | |||
| eda8572005 | |||
| 69a18d38d3 | |||
| b5195aa4d4 | |||
| 7801cf5730 | |||
| bf3cbc71ae | |||
| d669b56569 | |||
| 8a9a9a7338 | |||
| d2071a610b | |||
| a8507aaa12 | |||
| 906700e0fe | |||
| 7c69d9c55f | |||
| 839d05f75c | |||
| 65cfa40e1f | |||
| 4cbe12ee5d | |||
| d204727a07 | |||
| d92c3da89a | |||
| 8d6cc6fd23 | |||
| 8dde75f7ec | |||
| 29fedc8701 |
Binary file not shown.
309
doc/db_init.sql
309
doc/db_init.sql
@@ -1,168 +1,165 @@
|
||||
|
||||
-- ============================================
|
||||
-- SecMPS v2.0 数据库建表脚本
|
||||
-- SecMPS v3.0 数据库建表脚本（6张表）
|
||||
-- 数据库: gljs_main
|
||||
-- 扩展表已合并到 Base_Device.ExtraData(JSON)
|
||||
-- ============================================
|
||||
|
||||
USE gljs_main;
|
||||
|
||||
-- ============================================
|
||||
-- 1. 统一设备主表
|
||||
CREATE TABLE IF NOT EXISTS Base_Device (
|
||||
DeviceId CHAR(36) NOT NULL PRIMARY KEY,
|
||||
DeviceName NVARCHAR(100) NOT NULL,
|
||||
AdapterCode NVARCHAR(50) NOT NULL,
|
||||
SourceId NVARCHAR(100) NOT NULL,
|
||||
DeviceCategory INT NOT NULL DEFAULT 1,
|
||||
DeviceType NVARCHAR(50),
|
||||
RegionId INT NULL,
|
||||
IsParent TINYINT NOT NULL DEFAULT 0,
|
||||
ParentDeviceId CHAR(36) NULL,
|
||||
IsOnline TINYINT NOT NULL DEFAULT 0,
|
||||
IpAddress NVARCHAR(50),
|
||||
Port INT,
|
||||
Location NVARCHAR(200),
|
||||
Lat DOUBLE,
|
||||
Lng DOUBLE,
|
||||
MapModelId NVARCHAR(100),
|
||||
MapModelScale FLOAT DEFAULT 1.0,
|
||||
MapModelRotation NVARCHAR(100),
|
||||
ExtraData TEXT,
|
||||
LocalOverrides TEXT,
|
||||
SyncVersion BIGINT DEFAULT 0,
|
||||
LastSyncTime DATETIME,
|
||||
Enable TINYINT DEFAULT 1,
|
||||
Remark NVARCHAR(500),
|
||||
CreateID INT,
|
||||
Creator NVARCHAR(50),
|
||||
CreateDate DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
ModifyID INT,
|
||||
Modifier NVARCHAR(50),
|
||||
ModifyDate DATETIME,
|
||||
UNIQUE INDEX IX_Base_Device_Adapter_Source (AdapterCode, SourceId),
|
||||
INDEX IX_Base_Device_RegionId (RegionId),
|
||||
INDEX IX_Base_Device_ParentId (ParentDeviceId)
|
||||
);
|
||||
-- ExtraData(JSON) 承载所有适配器特有字段
|
||||
-- DeviceGroup 路由到正确的网关Adapter和前端按钮组
|
||||
-- ============================================
|
||||
DROP TABLE IF EXISTS base_device;
|
||||
CREATE TABLE base_device (
|
||||
DeviceId INT AUTO_INCREMENT COMMENT '设备ID',
|
||||
DeviceName NVARCHAR(100) NOT NULL COMMENT '设备名称',
|
||||
AdapterCode NVARCHAR(50) NOT NULL COMMENT '来源适配器(类型:实例)',
|
||||
SourceId NVARCHAR(100) NOT NULL COMMENT '源系统设备ID',
|
||||
DeviceCategory NVARCHAR(50) NOT NULL COMMENT '设备种类(数据字典：门磁/空调/智能断路器/人行道闸/车辆道闸/485钥匙柜/网络钥匙柜/紧急报警按钮/红外报警器/门禁一体机/除湿_恒湿机/空调控制器/烟雾报警器/气体报警器/温湿度变送器/摄像机/硬盘录像机/动环采集器)',
|
||||
DeviceGroup NVARCHAR(20) NOT NULL COMMENT '设备分组(数据字典：视频设备/IoT设备/门禁设备/道闸设备/报警设备)',
|
||||
PointId INT NULL COMMENT '所属点位ID',
|
||||
GatewayNodeId INT NULL COMMENT '所属网关节点ID',
|
||||
IsParent NVARCHAR(20) NOT NULL DEFAULT '否' COMMENT '是否父设备(数据字典：是/否)',
|
||||
ParentDeviceId INT NULL COMMENT '父设备ID(自引用,子设备挂父设备下)',
|
||||
IsOnline NVARCHAR(20) NOT NULL DEFAULT '离线' COMMENT '在线状态(数据字典：在线/离线)',
|
||||
IpAddress NVARCHAR(50) COMMENT 'IP地址',
|
||||
Port INT COMMENT '端口',
|
||||
Location NVARCHAR(200) COMMENT '安装位置',
|
||||
Lat DOUBLE COMMENT '纬度',
|
||||
Lng DOUBLE COMMENT '经度',
|
||||
MapModelId NVARCHAR(100) COMMENT '三维地图模型ID',
|
||||
MapModelScale FLOAT DEFAULT 1.0 COMMENT '模型缩放比例',
|
||||
MapModelRotation NVARCHAR(100) COMMENT '模型旋转角度(JSON)',
|
||||
ExtraData TEXT COMMENT '适配器扩展数据JSON(Owl/MC4/门禁字段均存于此)',
|
||||
LastSyncTime DATETIME COMMENT '上次同步时间',
|
||||
Enable NVARCHAR(20) DEFAULT '启用' COMMENT '启用状态(数据字典：启用/禁用)',
|
||||
Remark NVARCHAR(500) COMMENT '备注',
|
||||
CreateID INT COMMENT '创建人ID',
|
||||
Creator NVARCHAR(50) COMMENT '创建人',
|
||||
CreateDate DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||||
ModifyID INT COMMENT '修改人ID',
|
||||
Modifier NVARCHAR(50) COMMENT '修改人',
|
||||
ModifyDate DATETIME COMMENT '修改时间',
|
||||
PRIMARY KEY (DeviceId),
|
||||
INDEX IX_Sync (AdapterCode, SourceId),
|
||||
INDEX IX_Point (PointId),
|
||||
INDEX IX_Parent (ParentDeviceId),
|
||||
INDEX IX_Gateway (GatewayNodeId),
|
||||
INDEX IX_Group (DeviceGroup)
|
||||
) COMMENT '统一设备主表';
|
||||
|
||||
-- 2. 视频设备扩展表
|
||||
CREATE TABLE IF NOT EXISTS Device_Video_Ext (
|
||||
ExtId CHAR(36) NOT NULL PRIMARY KEY,
|
||||
DeviceId CHAR(36) NOT NULL,
|
||||
OwlDeviceId NVARCHAR(64) NOT NULL,
|
||||
Protocol INT DEFAULT 1,
|
||||
Manufacturer NVARCHAR(100),
|
||||
Model NVARCHAR(100),
|
||||
ChannelCount INT DEFAULT 0,
|
||||
OwlStatus NVARCHAR(500),
|
||||
CreateDate DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
UNIQUE INDEX IX_VideoExt_Owl (OwlDeviceId),
|
||||
INDEX IX_VideoExt_Device (DeviceId)
|
||||
);
|
||||
-- ============================================
|
||||
-- 2. 视频通道表
|
||||
-- DeviceId(INT) → base_device.DeviceId
|
||||
-- ============================================
|
||||
DROP TABLE IF EXISTS video_channel;
|
||||
CREATE TABLE video_channel (
|
||||
ChannelId INT AUTO_INCREMENT COMMENT '通道记录ID',
|
||||
OwlChannelId NVARCHAR(64) NOT NULL COMMENT 'Owl系统通道ID',
|
||||
DeviceId INT NOT NULL COMMENT '关联Base_Device设备ID',
|
||||
OwlStreamApp NVARCHAR(50) COMMENT 'Owl流应用名',
|
||||
OwlStreamName NVARCHAR(100) COMMENT 'Owl流名称',
|
||||
HasPtz TINYINT DEFAULT 0 COMMENT '是否支持云台',
|
||||
HasRecording TINYINT DEFAULT 0 COMMENT '是否支持录像',
|
||||
RecordMode INT DEFAULT 0 COMMENT '录像模式',
|
||||
SnapshotUrl NVARCHAR(500) COMMENT '快照地址',
|
||||
CreateDate DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||||
PRIMARY KEY (ChannelId),
|
||||
INDEX IX_Device (DeviceId),
|
||||
INDEX IX_Owl (OwlChannelId)
|
||||
) COMMENT '视频通道表';
|
||||
|
||||
-- 3. 视频通道表
|
||||
CREATE TABLE IF NOT EXISTS Video_Channel (
|
||||
ChannelId CHAR(36) NOT NULL PRIMARY KEY,
|
||||
OwlChannelId NVARCHAR(64) NOT NULL,
|
||||
DeviceId CHAR(36) NOT NULL,
|
||||
ChannelName NVARCHAR(100) NOT NULL,
|
||||
ChannelNo INT DEFAULT 0,
|
||||
OwlStreamApp NVARCHAR(50),
|
||||
OwlStreamName NVARCHAR(100),
|
||||
HasPtz TINYINT DEFAULT 0,
|
||||
HasRecording TINYINT DEFAULT 0,
|
||||
RecordMode INT DEFAULT 0,
|
||||
IsOnline TINYINT DEFAULT 0,
|
||||
SnapshotUrl NVARCHAR(500),
|
||||
Location NVARCHAR(200),
|
||||
Lat DOUBLE,
|
||||
Lng DOUBLE,
|
||||
Enable TINYINT DEFAULT 1,
|
||||
CreateDate DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
UNIQUE INDEX IX_Channel_Owl (OwlChannelId),
|
||||
INDEX IX_Channel_Device (DeviceId)
|
||||
);
|
||||
-- ============================================
|
||||
-- 3. 录像记录表
|
||||
-- ChannelId(INT) → video_channel.ChannelId
|
||||
-- ============================================
|
||||
DROP TABLE IF EXISTS video_record;
|
||||
CREATE TABLE video_record (
|
||||
RecordId INT AUTO_INCREMENT COMMENT '录像记录ID',
|
||||
ChannelId INT NOT NULL COMMENT '关联通道ID',
|
||||
OwlRecordId INT NOT NULL COMMENT 'Owl录像记录ID',
|
||||
App NVARCHAR(50) COMMENT '应用名',
|
||||
Stream NVARCHAR(100) COMMENT '流ID',
|
||||
StartedAt DATETIME NOT NULL COMMENT '录像开始时间',
|
||||
EndedAt DATETIME COMMENT '录像结束时间',
|
||||
Duration DOUBLE DEFAULT 0 COMMENT '录像时长(秒)',
|
||||
FilePath NVARCHAR(500) COMMENT '文件路径',
|
||||
FileSize BIGINT DEFAULT 0 COMMENT '文件大小(字节)',
|
||||
CreateDate DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||||
PRIMARY KEY (RecordId),
|
||||
INDEX IX_Channel (ChannelId),
|
||||
INDEX IX_Time (StartedAt)
|
||||
) COMMENT '录像记录表';
|
||||
|
||||
-- 4. 录像记录表
|
||||
CREATE TABLE IF NOT EXISTS Video_Record (
|
||||
RecordId CHAR(36) NOT NULL PRIMARY KEY,
|
||||
ChannelId CHAR(36) NOT NULL,
|
||||
OwlRecordId INT NOT NULL,
|
||||
App NVARCHAR(50),
|
||||
Stream NVARCHAR(100),
|
||||
StartedAt DATETIME NOT NULL,
|
||||
EndedAt DATETIME,
|
||||
Duration DOUBLE DEFAULT 0,
|
||||
FilePath NVARCHAR(500),
|
||||
FileSize BIGINT DEFAULT 0,
|
||||
CreateDate DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
INDEX IX_Record_Channel (ChannelId),
|
||||
INDEX IX_Record_Time (StartedAt)
|
||||
);
|
||||
-- ============================================
|
||||
-- 4. 设备数据归档表
|
||||
-- DeviceId(INT) → base_device.DeviceId
|
||||
-- ============================================
|
||||
DROP TABLE IF EXISTS iot_devicedata;
|
||||
CREATE TABLE iot_devicedata (
|
||||
DataId INT AUTO_INCREMENT COMMENT '数据记录ID',
|
||||
DeviceId INT NOT NULL COMMENT '关联设备ID(子设备/点位)',
|
||||
PointValue DOUBLE COMMENT '点位数值',
|
||||
UpdateTime DATETIME NOT NULL COMMENT '数据更新时间',
|
||||
`Interval` INT DEFAULT 0 COMMENT '采集间隔(毫秒)',
|
||||
ArchiveType INT DEFAULT 1 COMMENT '归档类型(1小时/2日)',
|
||||
CreateDate DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||||
PRIMARY KEY (DataId),
|
||||
INDEX IX_Device (DeviceId),
|
||||
INDEX IX_Time (CreateDate)
|
||||
) COMMENT '设备数据归档表';
|
||||
|
||||
-- 5. IoT设备扩展表
|
||||
CREATE TABLE IF NOT EXISTS Device_IoT_Ext (
|
||||
ExtId CHAR(36) NOT NULL PRIMARY KEY,
|
||||
DeviceId CHAR(36) NOT NULL,
|
||||
Mc4DeviceId INT NOT NULL,
|
||||
ObjectType INT,
|
||||
Tag NVARCHAR(100),
|
||||
ParentId INT,
|
||||
Mc4Option NVARCHAR(500),
|
||||
CreateDate DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
UNIQUE INDEX IX_IoTExt_Mc4 (Mc4DeviceId),
|
||||
INDEX IX_IoTExt_Device (DeviceId)
|
||||
);
|
||||
-- ============================================
|
||||
-- 5. 告警记录表（通用）
|
||||
-- DeviceId(INT) → base_device.DeviceId
|
||||
-- ============================================
|
||||
DROP TABLE IF EXISTS iot_alarm;
|
||||
CREATE TABLE iot_alarm (
|
||||
AlarmId INT AUTO_INCREMENT COMMENT '告警ID',
|
||||
SourceAlarmId NVARCHAR(100) NOT NULL COMMENT '源系统告警ID',
|
||||
DeviceId INT NOT NULL COMMENT '关联设备ID',
|
||||
AlarmType INT DEFAULT 0 COMMENT '告警类型',
|
||||
AlarmLevel NVARCHAR(20) DEFAULT '提示' COMMENT '告警等级(数据字典：提示/普通/重要/紧急)',
|
||||
AlarmDesc NVARCHAR(500) COMMENT '告警描述',
|
||||
AlarmValue DOUBLE COMMENT '触发值',
|
||||
StartTime DATETIME NOT NULL COMMENT '告警开始时间',
|
||||
EndTime DATETIME COMMENT '告警结束时间',
|
||||
ConfirmTime DATETIME COMMENT '确认时间',
|
||||
ConfirmUser NVARCHAR(50) COMMENT '确认人',
|
||||
State NVARCHAR(20) DEFAULT '未确认' COMMENT '状态(数据字典：未确认/已确认/已结束)',
|
||||
AdapterCode NVARCHAR(50) COMMENT '来源适配器',
|
||||
CreateDate DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||||
PRIMARY KEY (AlarmId),
|
||||
INDEX IX_Device (DeviceId),
|
||||
INDEX IX_Source (SourceAlarmId),
|
||||
INDEX IX_Time (StartTime),
|
||||
INDEX IX_Level (AlarmLevel)
|
||||
) COMMENT '告警记录表';
|
||||
|
||||
-- 6. 设备点位表
|
||||
CREATE TABLE IF NOT EXISTS IoT_DevicePoint (
|
||||
PointId CHAR(36) NOT NULL PRIMARY KEY,
|
||||
DeviceId CHAR(36) NOT NULL,
|
||||
Mc4DeviceId INT NOT NULL,
|
||||
PointIndex INT NOT NULL,
|
||||
PointType INT,
|
||||
PointTag NVARCHAR(100),
|
||||
PointName NVARCHAR(100) NOT NULL,
|
||||
PointDesc NVARCHAR(200),
|
||||
Unit NVARCHAR(50),
|
||||
IsControlPoint TINYINT DEFAULT 0,
|
||||
Mc4Option NVARCHAR(500),
|
||||
Enable TINYINT DEFAULT 1,
|
||||
CreateDate DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
UNIQUE INDEX IX_Point_Mc4 (Mc4DeviceId, PointIndex),
|
||||
INDEX IX_Point_Device (DeviceId)
|
||||
);
|
||||
|
||||
-- 7. 设备数据归档表（仅存快照，实时不入库）
|
||||
CREATE TABLE IF NOT EXISTS IoT_DeviceData (
|
||||
DataId CHAR(36) NOT NULL PRIMARY KEY,
|
||||
DeviceId CHAR(36) NOT NULL,
|
||||
PointId CHAR(36) NOT NULL,
|
||||
PointValue DOUBLE,
|
||||
UpdateTime DATETIME NOT NULL,
|
||||
`Interval` INT DEFAULT 0,
|
||||
ArchiveType INT DEFAULT 1,
|
||||
CreateDate DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
INDEX IX_Data_Device (DeviceId),
|
||||
INDEX IX_Data_Time (CreateDate)
|
||||
);
|
||||
|
||||
-- 8. 告警记录表
|
||||
CREATE TABLE IF NOT EXISTS IoT_Alarm (
|
||||
AlarmId CHAR(36) NOT NULL PRIMARY KEY,
|
||||
Mc4AlarmId NVARCHAR(64) NOT NULL,
|
||||
DeviceId CHAR(36),
|
||||
PointId CHAR(36),
|
||||
AlarmType INT DEFAULT 0,
|
||||
AlarmLevel INT DEFAULT 1,
|
||||
AlarmDesc NVARCHAR(500),
|
||||
AlarmValue DOUBLE,
|
||||
StartTime DATETIME NOT NULL,
|
||||
EndTime DATETIME,
|
||||
ConfirmTime DATETIME,
|
||||
ConfirmUser NVARCHAR(50),
|
||||
State INT DEFAULT 1,
|
||||
AdapterCode NVARCHAR(50),
|
||||
CreateDate DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
UNIQUE INDEX IX_Alarm_Mc4 (Mc4AlarmId),
|
||||
INDEX IX_Alarm_Device (DeviceId),
|
||||
INDEX IX_Alarm_Time (StartTime)
|
||||
);
|
||||
-- ============================================
|
||||
-- 6. 网关节点注册表
|
||||
-- ============================================
|
||||
DROP TABLE IF EXISTS gateway_nodes;
|
||||
CREATE TABLE gateway_nodes (
|
||||
NodeId INT AUTO_INCREMENT COMMENT '网关节点ID',
|
||||
NodeCode NVARCHAR(50) NOT NULL COMMENT '网关唯一编码',
|
||||
NodeName NVARCHAR(100) NOT NULL COMMENT '网关名称',
|
||||
NodeToken NVARCHAR(100) NOT NULL COMMENT '认证令牌',
|
||||
AdapterTypes NVARCHAR(200) COMMENT '支持的适配器类型(网关上报)',
|
||||
BaseUrl NVARCHAR(200) COMMENT '网关自身地址(网关上报)',
|
||||
LastHeartbeat DATETIME COMMENT '上次心跳时间',
|
||||
IsOnline NVARCHAR(20) DEFAULT '离线' COMMENT '在线状态(数据字典：在线/离线)',
|
||||
Enable NVARCHAR(20) DEFAULT '启用' COMMENT '启用状态(数据字典：启用/禁用)',
|
||||
Remark NVARCHAR(500) COMMENT '备注',
|
||||
CreateID INT COMMENT '创建人ID',
|
||||
Creator NVARCHAR(50) COMMENT '创建人',
|
||||
CreateDate DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||||
ModifyID INT COMMENT '修改人ID',
|
||||
Modifier NVARCHAR(50) COMMENT '修改人',
|
||||
ModifyDate DATETIME COMMENT '修改时间',
|
||||
PRIMARY KEY (NodeId),
|
||||
UNIQUE INDEX IX_Code (NodeCode),
|
||||
INDEX IX_Online (IsOnline)
|
||||
) COMMENT '网关节点注册表';
|
||||
|
||||
748
doc/对接文档/网关与Vol.Pro对接API手册.md
Normal file
748
doc/对接文档/网关与Vol.Pro对接API手册.md
Normal file
@@ -0,0 +1,748 @@
|
||||
# SecMPS 网关与 Vol.Pro 对接 API 手册
|
||||
|
||||
> **版本**: v1.0
|
||||
> **日期**: 2026-05-16
|
||||
> **基于**: SecMPS_最终整合方案_v3.0.md
|
||||
> **接口数量**: 13 个（A 组 4 个 + B 组 9 个）
|
||||
|
||||
---
|
||||
|
||||
## 1. 引言
|
||||
|
||||
### 1.1 目标与范围
|
||||
|
||||
本手册定义 IntegrationGateway（网关）与 Vol.Pro 后端之间所有 HTTP API 的接口规范。供网关开发、Vol.Pro 后端开发、前端开发和 AI Agent 编码时参考。
|
||||
|
||||
### 1.2 基本约定
|
||||
|
||||
| 约定 | 说明 |
|
||||
|------|------|
|
||||
| 请求方法 | A 组使用 **POST**，B 组使用 **GET / POST** |
|
||||
| 数据格式 | **JSON**，`Content-Type: application/json` |
|
||||
| 字符编码 | **UTF-8** |
|
||||
| 认证方式 | A 组: `NodeToken`（请求体中携带），B 组: 内网直连，无认证 |
|
||||
| 网关端口 | **5100**（默认） |
|
||||
| Vol.Pro 端口 | **9100**（默认） |
|
||||
|
||||
### 1.3 响应格式
|
||||
|
||||
**成功**:
|
||||
```json
|
||||
{
|
||||
// 具体数据，见各接口定义
|
||||
}
|
||||
```
|
||||
HTTP Status: 200
|
||||
|
||||
**失败**:
|
||||
```json
|
||||
{
|
||||
"message": "错误描述"
|
||||
}
|
||||
```
|
||||
HTTP Status: 400（业务错误）/ 401（认证失败）/ 500（服务器错误）
|
||||
|
||||
---
|
||||
|
||||
## 2. A 组接口：网关 → Vol.Pro
|
||||
|
||||
> 调用方: 网关
|
||||
> 接收方: Vol.Pro 后端
|
||||
> 端口: 9100
|
||||
|
||||
---
|
||||
|
||||
### 2.1 A1 — 网关注册
|
||||
|
||||
网关启动时调用，上报身份与能力，获取所管理的顶层设备列表。
|
||||
|
||||
- **Endpoint**: `POST /api/gateway/register`
|
||||
- **认证**: NodeToken
|
||||
- **逻辑**: Upsert — NodeCode 匹配则更新，不匹配则插入
|
||||
|
||||
#### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"nodeCode": "gw-31ku",
|
||||
"token": "a1b2c3d4e5f6",
|
||||
"adapterTypes": "MC4,Owl",
|
||||
"baseUrl": "http://192.168.1.100:5100"
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:---:|------|
|
||||
| nodeCode | string | ✅ | 网关唯一编码，管理端生成 |
|
||||
| token | string | ✅ | 认证令牌，管理端生成 |
|
||||
| adapterTypes | string | ✅ | 支持的适配器类型，逗号分隔，例如 "MC4,Owl" |
|
||||
| baseUrl | string | ✅ | 网关自身地址（含端口），供管理端回调 |
|
||||
|
||||
#### 响应体（成功）
|
||||
|
||||
```json
|
||||
{
|
||||
"nodeId": 1,
|
||||
"devices": [
|
||||
{
|
||||
"deviceId": 10,
|
||||
"deviceName": "动环采集器",
|
||||
"adapterCode": "MC4:31ku",
|
||||
"sourceId": "1001",
|
||||
"deviceCategory": "动环采集器",
|
||||
"deviceGroup": "IoT设备",
|
||||
"isParent": "是",
|
||||
"parentSourceId": null,
|
||||
"isOnline": "在线",
|
||||
"ipAddress": "10.0.1.100",
|
||||
"port": 3000,
|
||||
"extraData": {
|
||||
"mc4DeviceId": 1001
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| nodeId | int | 网关在 Vol.Pro 中的 NodeId |
|
||||
| devices | array | 当前网关负责的顶层设备列表（base_device 中 GatewayNodeId=本网关 且 ParentDeviceId IS NULL 的记录） |
|
||||
| devices[].deviceId | int | Vol.Pro 内部设备ID |
|
||||
| devices[].adapterCode | string | 双段标识 "MC4:31ku" |
|
||||
| devices[].sourceId | string | 第三方原始设备ID |
|
||||
| devices[].extraData | object | 适配器扩展数据 |
|
||||
|
||||
#### 响应体（失败）
|
||||
|
||||
```json
|
||||
// HTTP 401
|
||||
{
|
||||
"message": "认证失败"
|
||||
}
|
||||
```
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:9100/api/gateway/register \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"nodeCode":"gw-31ku","token":"a1b2c3d4e5f6","adapterTypes":"MC4,Owl","baseUrl":"http://192.168.1.100:5100"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2.2 A2 — 网关心跳
|
||||
|
||||
网关每 15 秒调用，Vol.Pro 更新 LastHeartbeat 和 IsOnline。
|
||||
|
||||
- **Endpoint**: `POST /api/gateway/heartbeat`
|
||||
- **认证**: NodeToken
|
||||
- **频率**: 每 15 秒
|
||||
|
||||
#### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"nodeCode": "gw-31ku",
|
||||
"token": "a1b2c3d4e5f6"
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:---:|------|
|
||||
| nodeCode | string | ✅ | 网关唯一编码 |
|
||||
| token | string | ✅ | 认证令牌 |
|
||||
|
||||
#### 响应体
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"serverTime": "2026-05-16 15:30:00"
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| status | string | 固定 "ok" |
|
||||
| serverTime | string | Vol.Pro 当前时间，供网关校时 |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:9100/api/gateway/heartbeat \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"nodeCode":"gw-31ku","token":"a1b2c3d4e5f6"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2.3 A3 — 设备数据同步
|
||||
|
||||
网关发现新设备或设备状态变更后，上送到 Vol.Pro。
|
||||
|
||||
- **Endpoint**: `POST /api/gateway/sync/devices`
|
||||
- **认证**: NodeToken
|
||||
- **字段分治**: 首次入库写全量，已有记录仅更新网关字段
|
||||
|
||||
#### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"nodeCode": "gw-31ku",
|
||||
"token": "a1b2c3d4e5f6",
|
||||
"devices": [
|
||||
{
|
||||
"adapterCode": "MC4:31ku",
|
||||
"sourceId": "1001",
|
||||
"name": "动环采集器",
|
||||
"category": "动环采集器",
|
||||
"group": "IoT设备",
|
||||
"isParent": true,
|
||||
"parentSourceId": null,
|
||||
"isOnline": true,
|
||||
"ipAddress": "10.0.1.100",
|
||||
"port": 3000,
|
||||
"extraData": {
|
||||
"mc4DeviceId": 1001
|
||||
}
|
||||
},
|
||||
{
|
||||
"adapterCode": "MC4:31ku",
|
||||
"sourceId": "1001_0",
|
||||
"name": "温湿度变送器",
|
||||
"category": "温湿度变送器",
|
||||
"group": "IoT设备",
|
||||
"isParent": false,
|
||||
"parentSourceId": "1001",
|
||||
"isOnline": true,
|
||||
"ipAddress": null,
|
||||
"port": null,
|
||||
"extraData": {
|
||||
"mc4DeviceId": 1001,
|
||||
"pointIndex": 0,
|
||||
"unit": "℃"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:---:|------|
|
||||
| nodeCode | string | ✅ | 网关编码 |
|
||||
| token | string | ✅ | 认证令牌 |
|
||||
| devices | array | ✅ | 设备列表 |
|
||||
| devices[].adapterCode | string | ✅ | 双段标识 |
|
||||
| devices[].sourceId | string | ✅ | 第三方原始ID |
|
||||
| devices[].name | string | ✅ | 设备名称（仅首次写入） |
|
||||
| devices[].category | string | ✅ | 设备种类（仅首次写入） |
|
||||
| devices[].group | string | ✅ | 设备分组（仅首次写入） |
|
||||
| devices[].isParent | bool | ✅ | 是否父设备 |
|
||||
| devices[].parentSourceId | string? | | 父设备第三方ID，Vol.Pro 解析为 ParentDeviceId |
|
||||
| devices[].isOnline | bool | ✅ | 在线状态 |
|
||||
| devices[].ipAddress | string? | | IP 地址 |
|
||||
| devices[].port | int? | | 端口 |
|
||||
| devices[].extraData | object | | 适配器扩展数据 |
|
||||
|
||||
**字段分治规则**:
|
||||
- **首次入库**（DeviceId=0）: 所有字段写入
|
||||
- **已有记录**: 仅更新 isOnline、isParent、parentDeviceId（解析后）、extraData、ipAddress、port、lastSyncTime
|
||||
- deviceName、category、group、pointId、location、lat/lng、mapModelId 仅在首次写入
|
||||
|
||||
#### 响应体
|
||||
|
||||
```json
|
||||
{
|
||||
"added": 2,
|
||||
"updated": 0,
|
||||
"removed": 0
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| added | int | 新增设备数 |
|
||||
| updated | int | 更新设备数 |
|
||||
| removed | int | 删除设备数（FullReplace 模式下可能 >0） |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:9100/api/gateway/sync/devices \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"nodeCode":"gw-31ku","token":"a1b2c3d4e5f6","devices":[...]}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2.4 A4 — 告警数据同步
|
||||
|
||||
网关发现新告警后上送。
|
||||
|
||||
- **Endpoint**: `POST /api/gateway/sync/alarms`
|
||||
- **认证**: NodeToken
|
||||
|
||||
#### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"nodeCode": "gw-31ku",
|
||||
"token": "a1b2c3d4e5f6",
|
||||
"alarms": [
|
||||
{
|
||||
"sourceAlarmId": "2183fda3-9e32-48ae-b433-f807cc81a237",
|
||||
"deviceSourceId": "1001_0",
|
||||
"adapterCode": "MC4:31ku",
|
||||
"level": "重要",
|
||||
"desc": "温度超限: [温湿度变送器][45℃]",
|
||||
"value": 45.0,
|
||||
"startTime": "2026-05-16 14:30:00"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:---:|------|
|
||||
| nodeCode / token | string | ✅ | 认证信息 |
|
||||
| alarms | array | ✅ | 告警列表 |
|
||||
| alarms[].sourceAlarmId | string | ✅ | 源系统告警ID（用于去重） |
|
||||
| alarms[].deviceSourceId | string | ✅ | 告警所属设备的第三方ID |
|
||||
| alarms[].adapterCode | string | ✅ | 双段标识 |
|
||||
| alarms[].level | string | ✅ | 告警等级(字典: 提示/普通/重要/紧急) |
|
||||
| alarms[].desc | string | ✅ | 告警描述 |
|
||||
| alarms[].value | double | | 触发值 |
|
||||
| alarms[].startTime | string | ✅ | 告警开始时间 "yyyy-MM-dd HH:mm:ss" |
|
||||
|
||||
#### 响应体
|
||||
|
||||
```json
|
||||
{
|
||||
"added": 1
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. B 组接口：Vol.Pro / 管理端 → 网关
|
||||
|
||||
> 调用方: Vol.Pro 后端 / 管理端 / warehouse 端
|
||||
> 接收方: 网关
|
||||
> 端口: 5100
|
||||
> 认证: 内网直连（无认证）
|
||||
|
||||
---
|
||||
|
||||
### 3.1 B1 — 健康检查
|
||||
|
||||
- **Endpoint**: `GET /api/gateway/health`
|
||||
|
||||
#### 响应体
|
||||
|
||||
```json
|
||||
{
|
||||
"gateway": "ok",
|
||||
"adapters": {
|
||||
"MC4:31ku": true,
|
||||
"Owl:main": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| gateway | string | 固定 "ok" |
|
||||
| adapters | object | key=AdapterCode, value=true(在线)/false(离线) |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```bash
|
||||
curl http://localhost:5100/api/gateway/health
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3.2 B2 — 设备列表
|
||||
|
||||
获取指定适配器下的设备列表（实时查询第三方）。
|
||||
|
||||
- **Endpoint**: `GET /api/gateway/devices`
|
||||
- **适配器**: IHasFlatDevices
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|:---:|------|
|
||||
| adapter | string | ✅ | AdapterCode，例如 "Owl:main" |
|
||||
| page | int | | 页码，默认 1 |
|
||||
| size | int | | 每页大小，默认 50 |
|
||||
| keyword | string | | 名称/ID 模糊搜索 |
|
||||
|
||||
#### 响应体
|
||||
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"sourceId": "gb_34020000001320000001",
|
||||
"adapterCode": "Owl:main",
|
||||
"name": "NVR-01",
|
||||
"category": "硬盘录像机",
|
||||
"group": "视频设备",
|
||||
"isOnline": true,
|
||||
"isParent": true,
|
||||
"ipAddress": "192.168.1.100",
|
||||
"port": 5060,
|
||||
"channelCount": 4,
|
||||
"extraData": {
|
||||
"owlDeviceId": "gb_34020000001320000001",
|
||||
"protocol": "GB28181",
|
||||
"transport": "UDP"
|
||||
}
|
||||
}
|
||||
],
|
||||
"total": 50
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3.3 B3 — 手动触发同步
|
||||
|
||||
管理端手动触发全量设备同步。
|
||||
|
||||
- **Endpoint**: `POST /api/gateway/devices/sync`
|
||||
- **适配器**: 所有实现了 IHasFlatDevices 或 IHasOwnDeviceTree 的适配器
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|:---:|------|
|
||||
| adapter | string | ✅ | AdapterCode |
|
||||
|
||||
#### 响应体
|
||||
|
||||
```json
|
||||
{
|
||||
"adapterCode": "Owl:main",
|
||||
"added": 5,
|
||||
"updated": 3,
|
||||
"removed": 1,
|
||||
"errors": [],
|
||||
"startTime": "2026-05-16T15:30:00",
|
||||
"endTime": "2026-05-16T15:30:05"
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| adapterCode | string | 适配器编码 |
|
||||
| added | int | 新增数 |
|
||||
| updated | int | 更新数 |
|
||||
| removed | int | 删除数 |
|
||||
| errors | array | 错误信息列表 |
|
||||
| startTime / endTime | string | 同步起止时间 |
|
||||
|
||||
---
|
||||
|
||||
### 3.4 B4 — 实时点位值
|
||||
|
||||
获取设备所有点位的实时值。
|
||||
|
||||
- **Endpoint**: `GET /api/gateway/realtime/{adapter}/{deviceSourceId}`
|
||||
- **适配器**: IHasPoints (MC4.0)
|
||||
|
||||
#### 路径参数
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| adapter | AdapterCode，例如 "MC4:31ku" |
|
||||
| deviceSourceId | 设备在第三方系统中的 ID |
|
||||
|
||||
#### 响应体
|
||||
|
||||
```json
|
||||
{
|
||||
"deviceSourceId": "1001",
|
||||
"points": [
|
||||
{
|
||||
"pointIndex": 0,
|
||||
"name": "温度",
|
||||
"value": 26.5,
|
||||
"unit": "℃",
|
||||
"updateTime": "2026-05-16 15:30:00",
|
||||
"isValid": true
|
||||
},
|
||||
{
|
||||
"pointIndex": 1,
|
||||
"name": "湿度",
|
||||
"value": 55.0,
|
||||
"unit": "%",
|
||||
"updateTime": "2026-05-16 15:30:00",
|
||||
"isValid": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| deviceSourceId | string | 设备ID |
|
||||
| points[].pointIndex | int | 点位索引 |
|
||||
| points[].name | string | 点位名称 |
|
||||
| points[].value | double | 当前值 |
|
||||
| points[].unit | string | 单位 |
|
||||
| points[].updateTime | string | 数据更新时间 |
|
||||
| points[].isValid | bool | 数据是否有效（false=传感器异常） |
|
||||
|
||||
---
|
||||
|
||||
### 3.5 B5 — 设备控制
|
||||
|
||||
反向控制设备（调空调温度、开关阀门等）。
|
||||
|
||||
- **Endpoint**: `POST /api/gateway/realtime/{adapter}/control`
|
||||
- **适配器**: IHasPoints (MC4.0)
|
||||
|
||||
#### 路径参数 + 请求体
|
||||
|
||||
```json
|
||||
// POST /api/gateway/realtime/MC4:31ku/control
|
||||
{
|
||||
"deviceSourceId": "1001",
|
||||
"pointIndex": 2,
|
||||
"value": 1
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:---:|------|
|
||||
| deviceSourceId | string | ✅ | 第三方设备ID |
|
||||
| pointIndex | int | ✅ | 点位索引 |
|
||||
| value | double | ✅ | 设置值（开关: 0/1, 模拟量: 实际数值） |
|
||||
|
||||
#### 响应体
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "sent"
|
||||
}
|
||||
```
|
||||
|
||||
> 注意: 响应仅表示指令已发送，不保证设备已执行。如需确认，应再次调 B4 查询实时值。
|
||||
|
||||
---
|
||||
|
||||
### 3.6 B6a — 实时取流
|
||||
|
||||
获取实时播放流地址。
|
||||
|
||||
- **Endpoint**: `GET /api/gateway/streams/{adapter}/{channelId}/live`
|
||||
- **适配器**: IHasStreams (Owl)
|
||||
|
||||
#### 响应体
|
||||
|
||||
```json
|
||||
{
|
||||
"wsFlv": "ws://192.168.1.108/proxy/sms/rtp/gb_xxx.live.flv",
|
||||
"httpFlv": "http://192.168.1.108/proxy/sms/rtp/gb_xxx.live.flv",
|
||||
"hls": "http://192.168.1.108/proxy/sms/rtp/gb_xxx/hls.fmp4.m3u8",
|
||||
"webrtc": "webrtc://192.168.1.108/proxy/sms/index/api/webrtc?app=rtp&stream=gb_xxx&type=play",
|
||||
"rtmp": "rtmp://192.168.1.108:1935/rtp/gb_xxx",
|
||||
"rtsp": "rtsp://192.168.1.108:554/rtp/gb_xxx"
|
||||
}
|
||||
```
|
||||
|
||||
| 协议 | 建议用途 | 延迟 |
|
||||
|------|----------|:---:|
|
||||
| wsFlv | Web 实时预览（首选） | <1s |
|
||||
| httpFlv | 兼容旧浏览器 | 1-2s |
|
||||
| hls | iOS Safari / 回放 | 3-5s |
|
||||
| webrtc | 超低延迟场景 | <500ms |
|
||||
|
||||
> 注意: GB28181 首次拉流有 1-3 秒 SIP 信令延迟。建议前端播放器在 3 秒内无画面时自动重试一次。
|
||||
|
||||
---
|
||||
|
||||
### 3.7 B6b — 回放取流
|
||||
|
||||
获取历史录像 HLS 播放地址。
|
||||
|
||||
- **Endpoint**: `GET /api/gateway/streams/{adapter}/{channelId}/playback`
|
||||
- **适配器**: IHasStreams (Owl)
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|:---:|------|
|
||||
| start | string | ✅ | 开始时间 "yyyy-MM-dd HH:mm:ss" |
|
||||
| end | string | ✅ | 结束时间 "yyyy-MM-dd HH:mm:ss" |
|
||||
|
||||
#### 响应体
|
||||
|
||||
```json
|
||||
{
|
||||
"hls": "http://192.168.1.108/recordings/channels/gb_xxx/index.m3u8?start_ms=1714982400000&end_ms=1714982700000&token=xxx"
|
||||
}
|
||||
```
|
||||
|
||||
> 回放使用 HLS (VOD) 格式，Owl 将指定时间范围内的 MP4 片段动态拼接为 m3u8 播放列表。
|
||||
|
||||
---
|
||||
|
||||
### 3.8 B7 — 云台控制
|
||||
|
||||
控制摄像机云台转动。
|
||||
|
||||
- **Endpoint**: `POST /api/gateway/streams/{adapter}/{channelId}/ptz`
|
||||
- **适配器**: IHasStreams (Owl)
|
||||
|
||||
#### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"direction": "left",
|
||||
"speed": 0.5
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:---:|------|
|
||||
| direction | string | ✅ | **仅支持**: `up` / `down` / `left` / `right` / `zoom_in` / `zoom_out` / `stop` |
|
||||
| speed | float | | 速度 0.0~1.0，默认 0.5 |
|
||||
|
||||
> ⚠️ Owl 当前版本仅实现了方向移动 (`continuous`) 和停止 (`stop`)，**不支持**预设位操作 (`preset/set/goto/remove`) 和绝对/相对定位。ONVIF PTZ 未实现。
|
||||
|
||||
#### 响应体
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3.9 B8 — 告警查询
|
||||
|
||||
查询告警列表。
|
||||
|
||||
- **Endpoint**: `GET /api/gateway/alarms/{adapter}`
|
||||
- **适配器**: IHasAlarms
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|:---:|------|
|
||||
| from | string | ✅ | 开始时间 "yyyy-MM-dd HH:mm:ss" |
|
||||
| to | string | ✅ | 结束时间 |
|
||||
| page | int | | 页码，默认 1 |
|
||||
| size | int | | 每页大小，默认 50 |
|
||||
| confirmState | int | | MC4.0: 0=所有, 1=未确认, 2=已确认 |
|
||||
| level | string | | 告警等级: 提示/普通/重要/紧急 |
|
||||
|
||||
#### 响应体
|
||||
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"alarmId": "2183fda3-9e32-48ae-b433-f807cc81a237",
|
||||
"deviceId": "1001",
|
||||
"adapterCode": "MC4:31ku",
|
||||
"level": "重要",
|
||||
"title": "温度超限",
|
||||
"content": "[温湿度变送器][45℃]",
|
||||
"occurTime": "2026-05-16 14:30:00",
|
||||
"status": "未确认",
|
||||
"thresholdValue": 40.0,
|
||||
"actualValue": 45.0
|
||||
}
|
||||
],
|
||||
"total": 120
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3.10 B9 — 告警确认
|
||||
|
||||
确认告警，写回第三方系统。
|
||||
|
||||
- **Endpoint**: `POST /api/gateway/alarms/{adapter}/{alarmId}/confirm`
|
||||
- **适配器**: IHasAlarms
|
||||
|
||||
#### 路径参数
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| adapter | AdapterCode |
|
||||
| alarmId | 源系统告警 ID |
|
||||
|
||||
#### 响应体
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "confirmed"
|
||||
}
|
||||
```
|
||||
|
||||
> Vol.Pro 在收到成功响应后，同步更新本地 `iot_alarm.State='已确认'` 和 `ConfirmTime=当前时间`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 错误码对照表
|
||||
|
||||
| HTTP Status | 含义 | 说明 |
|
||||
|:----------:|------|------|
|
||||
| 200 | 成功 | 正常响应 |
|
||||
| 400 | 请求错误 | 参数缺失或格式错误 |
|
||||
| 401 | 认证失败 | A 组接口 NodeCode 或 Token 不正确 |
|
||||
| 404 | 未找到 | 适配器不存在或设备不存在 |
|
||||
| 500 | 服务器错误 | 网关或 Vol.Pro 内部异常 |
|
||||
| 502 | 第三方错误 | 网关调用 Owl/MC4.0 失败 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 数据类型约定
|
||||
|
||||
| 类型 | JSON 示例 | 说明 |
|
||||
|------|-----------|------|
|
||||
| string | "hello" | 字符串 |
|
||||
| int | 42 | 整数 |
|
||||
| double | 26.5 | 浮点数 |
|
||||
| bool | true / false | 布尔值 |
|
||||
| object | { "key": "value" } | JSON 对象 |
|
||||
| array | [ ... ] | JSON 数组 |
|
||||
| datetime | "2026-05-16 15:30:00" | 日期时间字符串，格式 yyyy-MM-dd HH:mm:ss |
|
||||
|
||||
---
|
||||
|
||||
## 6. 对接检查清单
|
||||
|
||||
网关开发和 Vol.Pro 开发完成后，按以下清单逐项验证：
|
||||
|
||||
```
|
||||
□ A1: 网关启动 → 注册成功 → 返回 nodeId + 设备列表
|
||||
□ A2: 网关心跳 → Vol.Pro gateway_nodes.LastHeartbeat 更新
|
||||
□ A3: 首次同步 → 设备入库，字段分治规则正确（管理员字段不覆盖）
|
||||
□ A3: 二次同步 → 仅网关字段更新，DeviceName 不变
|
||||
□ A3: parentSourceId → Vol.Pro 正确解析为 ParentDeviceId
|
||||
□ A4: 告警上报 → iot_alarm 表有数据
|
||||
□ B1: 健康检查 → 返回所有适配器状态
|
||||
□ B2: 设备列表 → 分页 + 关键字搜索正常
|
||||
□ B3: 手动同步 → 返回 added/updated/removed 统计
|
||||
□ B4: 实时数据 → 返回点位值和更新时间
|
||||
□ B5: 设备控制 → 指令发送成功，设备实际响应
|
||||
□ B6a: 实时取流 → 返回 6 种协议地址，前端可播放
|
||||
□ B6b: 回放取流 → 返回 HLS 地址，前端可播放历史录像
|
||||
□ B7: 云台控制 → 方向键有效，stop 有效
|
||||
□ B8: 告警查询 → 分页 + 筛选正常
|
||||
□ B9: 告警确认 → 第三方确认成功 + Vol.Pro 本地 State 更新
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
> **文档结束**
|
||||
290
doc/整合方案/SecMPS_整合方案_v2.0_最终评估报告.md
Normal file
290
doc/整合方案/SecMPS_整合方案_v2.0_最终评估报告.md
Normal file
@@ -0,0 +1,290 @@
|
||||
# SecMPS 整合方案 — 最终评估报告
|
||||
|
||||
> **评估日期**: 2026-05-16
|
||||
> **评估对象**: SecMPS_最终整合方案_v2.0.md
|
||||
> **参考依据**: Owl API 文档 / Owl GitHub / ZLMediaKit 官方文档 / ZLMediaKit GitHub / 数据字典设计
|
||||
|
||||
---
|
||||
|
||||
## 一、评估方法
|
||||
|
||||
以资深架构师经验，对整合方案进行三个维度的交叉验证：
|
||||
|
||||
1. **方案自洽性**：章节间逻辑是否一致，API 定义 ↔ 数据模型 ↔ 同步策略是否闭环
|
||||
2. **对 Owl+ZLMediaKit 的准确性**：方案定义的接口和流程是否与 Owl v1.3.0 / ZLMediaKit master 实际行为匹配
|
||||
3. **工程可落地性**：是否所有细节都有明确定义，是否存在"开发时再说"的模糊地带
|
||||
|
||||
共发现 **14 个问题**，按严重程度分为 P0（阻塞实施）、P1（影响质量）、P2（优化项）。
|
||||
|
||||
---
|
||||
|
||||
## 二、P0 — 必须修复（4 项）
|
||||
|
||||
### P0-1：第四章示例代码与 A3 接口规范矛盾
|
||||
|
||||
**问题描述**：
|
||||
§四示例代码（第 263-265 行）在每次同步时写入 `DeviceName = d.Name` 和 `DeviceCategory = d.Category`。但 A3 接口规范明确说"网关不碰管理员字段，首次入库写全量，后续仅更新网关负责的列"。这导致管理员手动改过的设备名称每次同步后被网关覆盖。
|
||||
|
||||
**影响**：管理员的设备重命名操作会被同步覆盖，用户投诉
|
||||
|
||||
**解决方案**：
|
||||
```csharp
|
||||
// 区分首次入库与增量更新
|
||||
if (entity.DeviceId == 0) // 首次入库
|
||||
{
|
||||
entity.DeviceName = d.Name;
|
||||
entity.DeviceCategory = d.Category;
|
||||
entity.DeviceGroup = d.Group;
|
||||
}
|
||||
// 增量更新：只写网关负责的字段
|
||||
entity.IsOnline = d.IsOnline ? "在线" : "离线";
|
||||
entity.IsParent = d.IsParent ? "是" : "否";
|
||||
entity.ExtraData = d.ExtraDataJson;
|
||||
entity.LastSyncTime = DateTime.UtcNow;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### P0-2：A3 设备同步中 `parentSourceId` → `ParentDeviceId` 解析链路缺失
|
||||
|
||||
**问题描述**：
|
||||
A3 请求中设备携带 `parentSourceId: "1001"`（第三方 ID），但 Vol.Pro 需要 `ParentDeviceId`（本地主键）。从第三方 ID 到本地主键的映射逻辑完全未定义。
|
||||
|
||||
**影响**：子设备无法挂到父设备下，设备树断裂
|
||||
|
||||
**解决方案**：
|
||||
同步前先做映射表查询：
|
||||
```csharp
|
||||
// 批量取出当前网关所有设备
|
||||
var allIds = await _db.base_device
|
||||
.Where(x => x.GatewayNodeId == nodeId)
|
||||
.ToDictionaryAsync(x => (x.AdapterCode, x.SourceId), x => x.DeviceId);
|
||||
|
||||
// 解析 parentSourceId
|
||||
int? parentDeviceId = null;
|
||||
if (!string.IsNullOrEmpty(d.ParentSourceId))
|
||||
allIds.TryGetValue((d.AdapterCode, d.ParentSourceId), out var pid);
|
||||
parentDeviceId = pid > 0 ? pid : null;
|
||||
|
||||
entity.ParentDeviceId = parentDeviceId;
|
||||
```
|
||||
补充到 §四 代码示例中。
|
||||
|
||||
---
|
||||
|
||||
### P0-3：网关重启注册时 NodeId 分配逻辑未定义
|
||||
|
||||
**问题描述**：
|
||||
网关重启再次调用 A1 `/register`，`gateway_nodes` 表中 `NodeCode` 已存在。当前文档只说注册流程，没有说明是覆盖还是报错。如果新建 NodeId，则 `base_device.GatewayNodeId` 指向旧 ID 断裂。
|
||||
|
||||
**影响**：网关重启后设备归属丢失
|
||||
|
||||
**解决方案**：
|
||||
A1 接口改为 Upsert 逻辑：
|
||||
```
|
||||
POST /register →
|
||||
NodeCode 匹配 → 更新 AdapterTypes/BaseUrl/IsOnline=在线 → 返回已有 NodeId
|
||||
NodeCode 不匹配 → 插入新记录 → 返回新 NodeId → 401（防止未授权节点）
|
||||
```
|
||||
补充到 §2.1 流程描述和 A1 API 规范中。
|
||||
|
||||
---
|
||||
|
||||
### P0-4：Owl 管理端口错误
|
||||
|
||||
**问题描述**：
|
||||
Owl README 和 Docker Compose 明确 Owl Web 管理端口 = `15123`。方案 `appsettings.json` 和 §七部署拓扑均写 `owl_host:80`。
|
||||
|
||||
**影响**：网关无法连接 Owl，所有视频功能不可用
|
||||
|
||||
**解决方案**：
|
||||
- `appsettings.json` 中 Owl BaseUrl → `http://owl_host:15123`
|
||||
- §七部署拓扑中 Owl 端口标记为 `:15123`
|
||||
- 注意：ZLM 自身 HTTP 端口是 `8000`，但由 Owl 内部调用，网关不接触
|
||||
|
||||
---
|
||||
|
||||
## 三、P1 — 影响实施质量（6 项）
|
||||
|
||||
### P1-1：PTZ 接口仅实现 continuous + stop
|
||||
|
||||
**问题描述**：
|
||||
owl_api_research.md §6.1 和 Owl GitHub 确认：Owl 代码中仅实现了 `continuous`（持续移动）和 `stop`（停止），`preset`（预置位）、`absolute`（绝对定位）、`relative`（相对定位）均返回错误。ONVIF PTZ 标记为 TODO。
|
||||
方案 §2.3 适配器矩阵和 B7 API 没有注明此限制。
|
||||
|
||||
**影响**：开发前端云台面板时做了预置位下拉等功能，部署后不可用
|
||||
|
||||
**解决方案**：
|
||||
- B7 接口标注："仅支持 continuous (方向移动) + stop (停止)"
|
||||
- 前端云台面板：仅显示方向键（↑↓←→）+ 停止按钮，不显示预置位
|
||||
- OwlAdapter.PtzControlAsync 实现：ONVIF 设备直接返回错误
|
||||
|
||||
---
|
||||
|
||||
### P1-2：视频通道在 base_device 和 video_channel 中的双重身份不清
|
||||
|
||||
**问题描述**：
|
||||
§6 Owl 同步说 "Upsert base_device(ParentDeviceId=NVR) + video_channel"，但 §3.6 层级示例中摄像机是叶子节点没有子设备。一个 Owl 通道到底是 base_device 的子记录还是 video_channel 的独立记录？还是两者都是？
|
||||
|
||||
**影响**：开发者不清楚通道数据写入哪张表的哪个字段
|
||||
|
||||
**解决方案**：
|
||||
明确：一个 Owl 通道 = 2 条记录：
|
||||
1. `base_device` 子记录（DeviceName="通道01", DeviceCategory=摄像机, ParentDeviceId=NVR的DeviceId, ExtraData=null）
|
||||
2. `video_channel` 扩展记录（DeviceId=通道的DeviceId, OwlStreamApp, OwlStreamName, HasPtz, SnapshotUrl）
|
||||
在 §3.6 层级示例中增加通道示例：
|
||||
```
|
||||
NVR (IsParent=是)
|
||||
├── 通道01 (base_device子记录, video_channel.OwlStreamApp="rtp")
|
||||
├── 通道02 (base_device子记录, video_channel.OwlStreamApp="rtp")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### P1-3：回放取流与实时取流走不同的 Owl 端点
|
||||
|
||||
**问题描述**：
|
||||
- 实时播放：`POST /channels/:id/play`
|
||||
- 回放播放：`GET /recordings/channels/:cid/index.m3u8?start_ms=&end_ms=&token=`
|
||||
两者是 Owl 的不同端点，方案 B6 只有一个 `/live` 路径。
|
||||
|
||||
**影响**：回放功能无法对接 Owl
|
||||
|
||||
**解决方案**：
|
||||
B6 拆分为两个端点：
|
||||
```
|
||||
GET /streams/{adapter}/{channelId}/live → Owl POST /channels/:id/play
|
||||
GET /streams/{adapter}/{channelId}/playback?start=&end= → Owl GET /recordings/channels/:cid/index.m3u8
|
||||
```
|
||||
IHasStreams 接口不变（已有 GetLiveUrlAsync 和 GetPlaybackUrlAsync），只修正 B 组 API 路径。
|
||||
|
||||
---
|
||||
|
||||
### P1-4：告警确认后 Vol.Pro 本地状态更新不闭环
|
||||
|
||||
**问题描述**：
|
||||
B9 调网关确认告警写回第三方成功，但 `iot_alarm.State` 谁来更新？当前文档没有说明这个回写链路。
|
||||
|
||||
**影响**：管理端显示告警仍为"未确认"，需等下次 A4 同步才刷新
|
||||
|
||||
**解决方案**：
|
||||
B9 确认成功后，Vol.Pro 侧同步更新本地：
|
||||
```
|
||||
POST /alarms/{adapter}/{alarmId}/confirm 成功 →
|
||||
Vol.Pro 更新 iot_alarm SET State='已确认', ConfirmTime=NOW()
|
||||
```
|
||||
不需要网关二次推送。在 B9 接口规范中补充此说明。
|
||||
|
||||
---
|
||||
|
||||
### P1-5：video_record 同步策略缺失
|
||||
|
||||
**问题描述**：
|
||||
§六同步策略有设备同步、告警同步、反向控制，但没有录像记录的同步时机和频率。
|
||||
|
||||
**影响**：录像数据永远不会写入 video_record 表
|
||||
|
||||
**解决方案**：
|
||||
补充 §六：Owl 录像数据同步策略 ——
|
||||
- **方式一**（推荐）：管理端点击"查看回放"时，网关实时调 Owl `GET /recordings` → 返回给管理端 → 同时写入 video_record 表
|
||||
- **方式二**（备选）：网关定时（每 10 分钟）调 Owl `GET /recordings` → 走 A3 扩展同步 → 写入 video_record
|
||||
建议先用方式一，方式二在 Phase 3 优化时引入。
|
||||
|
||||
---
|
||||
|
||||
### P1-6：AdapterCode 双段格式无约束
|
||||
|
||||
**问题描述**：
|
||||
`"mc4:31号库房"` 中分隔符 `:` 和实例名字符集没有规范。如果实例名包含 `:` 会导致解析歧义。
|
||||
|
||||
**影响**：网关配置或同步时数据损坏
|
||||
|
||||
**解决方案**：
|
||||
定义格式规范（补充到 §2.2）：
|
||||
```
|
||||
AdapterCode = "{AdapterType}:{InstanceName}"
|
||||
AdapterType: 字母数字，对应网关注册的 Adapter 类名（如 MC4、Owl）
|
||||
InstanceName: 字母数字下划线，对应具体网关实例（如 31ku）
|
||||
分隔符: ':'
|
||||
示例: "MC4:31ku"、"Owl:main"、"HikvisionISC:center"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、P2 — 优化项（4 项）
|
||||
|
||||
### P2-1：子设备离线状态级联规则（明确即可）
|
||||
|
||||
**问题描述**：
|
||||
§2.1 说网关离线 → 设备离线，但网关在线时父设备（采集器）离线，子设备是否级联标记离线？
|
||||
|
||||
**解决方案**：
|
||||
网关在 A3 同步时如实上报每个子设备的 isOnline（MC4.0 树中已有此信息），Vol.Pro 不做推断，信任网关数据。在 §六同步策略中补充此行说明即可。
|
||||
|
||||
---
|
||||
|
||||
### P2-2：数据字典初始化运维指引（补充附录）
|
||||
|
||||
**问题描述**：
|
||||
方案依赖 7 个数据字典（DeviceCategory 18 值、DeviceGroup 5 值、IsParent/IsOnline/Enable/IsControlPoint/AlarmLevel/State），但没有初始化指引。
|
||||
|
||||
**解决方案**：
|
||||
在文档末尾增加「附录 A：字典初始化清单」，列出每个字典的 Code/Name/Value 对照表，运维人员在 Vol.Pro 管理端按表创建。
|
||||
|
||||
---
|
||||
|
||||
### P2-3：video_channel 流地址字段用途说明（补充注释）
|
||||
|
||||
**问题描述**：
|
||||
video_channel 有 `OwlStreamApp/OwlStreamName/SnapshotUrl`，B6 取流实时调网关获取。这些字段的实际用途没说。
|
||||
|
||||
**解决方案**：
|
||||
注明为缓存——首次取流后写入 video_channel，下次先查缓存，缓存过期（或 Owl 重启后）再调 B6 实时获取。在 video_channel 表注释中补充说明。
|
||||
|
||||
---
|
||||
|
||||
### P2-4：Owl AI 事件可接入告警（建议纳入 Phase 1 可选范围）
|
||||
|
||||
**问题描述**：
|
||||
Owl 有 YOLO 本地检测 + `GET /events` 接口，AI 事件可走 A4 告警同步。
|
||||
|
||||
**解决方案**：
|
||||
在 OwlAdapter 中可选实现 IHasAlarms，将 `GET /events` 的 AI 检测事件映射为 StandardAlarm（AlarmLevel=提示或普通）。在 §六同步策略中补充可选说明，建议 Phase 1 范围中列入。
|
||||
|
||||
---
|
||||
|
||||
## 五、架构正确性确认
|
||||
|
||||
以下方面经过 Owl+ZLMediaKit 双文档验证，确认正确：
|
||||
|
||||
| 验证项 | 状态 |
|
||||
|--------|:--:|
|
||||
| 三层架构（前端→网关→Owl）不直接接触 ZLM | ✅ |
|
||||
| Owl 代理播放地址 `/proxy/sms/...` | ✅ |
|
||||
| Owl RTP 收流→ZLM 转协议→多格式输出的链路 | ✅ |
|
||||
| Owl Webhook 自动配置 ZLM（启动时 SetServerConfig） | ✅ |
|
||||
| JWT Token 管理 + RSA 加密登录 | ✅ |
|
||||
| 设备/通道 CRUD 对应 Owl API | ✅ |
|
||||
| 取流端点返回 WS-FLV/HTTP-FLV/HLS/WebRTC/RTMP/RTSP | ✅ |
|
||||
| Owl↔ZLM 联动（OpenRtpServer/CloseRtpServer/AddStreamProxy 等） | ✅ |
|
||||
| 按需拉流 + 30s 无人观看自动关闭（ZLM on_stream_none_reader → Owl 通知 ZLM 关流） | ✅ |
|
||||
| 云录像由 Owl 管理（ZLM MP4 录制→Owl on_record_mp4 hook→入库） | ✅ |
|
||||
| GB28181 设备注册与心跳是 SIP 层自动完成（Vol.Pro 只查 HTTP API） | ✅ |
|
||||
| 播放地址通过 Owl `/proxy/sms/` 反向代理到 ZLM（前端不直接访问 ZLM） | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## 六、总结
|
||||
|
||||
| 优先级 | 数量 | 类型 |
|
||||
|:---:|:--:|------|
|
||||
| P0 | 4 | 阻塞性缺陷（代码矛盾、链路缺失、端口错误、注册逻辑缺失） |
|
||||
| P1 | 6 | 实施质量影响（PTZ限制、通道身份、回放端点、告警闭环、录像缺失、格式规范） |
|
||||
| P2 | 4 | 优化项（级联规则、字典指引、缓存说明、AI事件） |
|
||||
| ✅ | 12 | 已验证正确 |
|
||||
|
||||
**总体评价**：方案架构方向完全正确，Owl+ZLMediaKit 对接路径准确。14 个问题中 P0/P1 共 10 项，全部为配置级或接口路径级微调，不涉及架构推翻。修复后可直接作为实施基准。
|
||||
|
||||
---
|
||||
|
||||
> 本报告应作为 SecMPS_最终整合方案_v2.0.md 的修正依据。建议将 P0/P1 问题修复合入方案文档后再开始 Phase 1。
|
||||
@@ -1,424 +0,0 @@
|
||||
# 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`)
|
||||
321
doc/整合方案/SecMPS_整合方案_v3.0_最终评估报告.md
Normal file
321
doc/整合方案/SecMPS_整合方案_v3.0_最终评估报告.md
Normal file
@@ -0,0 +1,321 @@
|
||||
# SecMPS 整合方案 v3.0 — 最终技术评估报告
|
||||
|
||||
> **评估日期**: 2026-05-16
|
||||
> **评估对象**: SecMPS_最终整合方案_v3.0.md
|
||||
> **参考标准**: Owl v1.3.0 API / ZLMediaKit master / MC4.0 API / Vol.Pro 框架文档
|
||||
> **评估方法**: 逐章节对标六大技术文档，8 维度交叉验证
|
||||
|
||||
---
|
||||
|
||||
## 一、评估维度与结论总览
|
||||
|
||||
| 维度 | 得分 | 状态 |
|
||||
|------|:---:|:---:|
|
||||
| 架构合理性 | ★★★★★ | ✅ 通过 |
|
||||
| 与 Owl+ZLM 兼容性 | ★★★★★ | ✅ 通过（v2→v3 已修正端口和端点） |
|
||||
| 与 MC4.0 兼容性 | ★★★★★ | ✅ 通过（对象树+点位+告警全链路对齐） |
|
||||
| 与 Vol.Pro 框架兼容性 | ★★★★☆ | ✅ 通过（2 处注意事项） |
|
||||
| 数据完整性 | ★★★★★ | ✅ 通过（字段分治+映射表+双向 sync 闭环） |
|
||||
| 安全性 | ★★★★☆ | ✅ 通过（1 处建议增强） |
|
||||
| 可扩展性 | ★★★★★ | ✅ 通过（新增适配器零后端改动） |
|
||||
| 运维可行性 | ★★★★☆ | ✅ 通过（2 处补充建议） |
|
||||
|
||||
**结论：方案切实可行，可以进入实施阶段。**
|
||||
|
||||
---
|
||||
|
||||
## 二、逐章节详细评估
|
||||
|
||||
### §一 总体架构 【通过】
|
||||
|
||||
| 评估项 | 结论 |
|
||||
|--------|------|
|
||||
| 三层架构（前端→Vol.Pro→网关→第三方） | 正确。每层职责单一 |
|
||||
| 网关多实例部署 | 正确。NodeCode 唯一标识，互为独立 |
|
||||
| AdapterCode 双段标识 `MC4:31ku` | 正确。格式规范已定义 |
|
||||
| Owl 端口 15123 | 正确。与 Owl Docker Compose 一致 |
|
||||
| ZLM 不直接暴露 | 正确。Owl 管理 ZLM 的 Webhook+REST API |
|
||||
|
||||
**验证依据**:
|
||||
- Owl README: "Access http://localhost:15123 in your browser"
|
||||
- ZLM 官方文档: REST API 由 Owl 内部调用，不对外暴露
|
||||
- owl_api_research.md §8: Owl 通过 `SetServerConfig` 自动配置 ZLM Webhook
|
||||
|
||||
---
|
||||
|
||||
### §二 网关架构 【通过，1 处建议】
|
||||
|
||||
#### 2.1 注册与心跳流程
|
||||
|
||||
| 评估项 | 结论 |
|
||||
|--------|------|
|
||||
| A1 注册 Upsert 逻辑 | 正确。NodeCode 匹配即更新，不复用旧 NodeId |
|
||||
| 心跳 15s + 超时 30s | 正确。与 Owl SIP 心跳（3s×3=9s 判离线）和 MC4.0 采集周期独立 |
|
||||
| 级联设备离线 | 正确。Vol.Pro Job 只标记设备离线，不触发同步 |
|
||||
|
||||
**建议**: 增加"网关主动下线"接口 `POST /api/gateway/unregister`，网关正常关闭前调用以立即级联设备离线，避免等 30s 超时。
|
||||
|
||||
#### 2.2 网关配置
|
||||
|
||||
正确。3 个配置项（VolProBaseUrl/NodeCode/NodeToken）足够，AdapterTypes 由网关启动时扫描注册的 Adapter 类自动获取。
|
||||
|
||||
#### 2.3 适配器能力矩阵
|
||||
|
||||
**与 MC4.0 API 实际行为对照**:
|
||||
|
||||
| 方案接口 | MC4.0 对应端点 | 验证结果 |
|
||||
|----------|---------------|:---:|
|
||||
| IHasOwnDeviceTree.GetObjectTreeAsync | POST /api/central/object/tree | ✅ |
|
||||
| IHasPoints.GetRealtimeValuesAsync | POST /api/central/device/point/value/get | ✅ |
|
||||
| IHasPoints.GetMultiPointValuesAsync | POST /api/central/point/multi/value/get | ✅ |
|
||||
| IHasPoints.SetPointValueAsync | POST /api/central/point/value/set | ✅ |
|
||||
| IHasAlarms.GetAlarmsAsync | POST /api/central/alarm/query | ⚠️ 见 P1 |
|
||||
| IHasAlarms.ConfirmAlarmAsync | POST /api/central/alarm/confirm | ✅ |
|
||||
| IHasAlarms.EndAlarmAsync | POST /api/central/alarm/end | ✅ |
|
||||
| IHasAlarms.GetPendingAlarmCountAsync | POST /api/central/alarm/custom_query_count | ✅ |
|
||||
|
||||
> ⚠️ P1: MC4.0 告警查询使用 `skip/limit` 分页（非 `page/size`），且 `from/to` 为必填参数（非可选）。Mc4Adapter 实现时需注意。
|
||||
|
||||
**与 Owl API 实际行为对照**:
|
||||
|
||||
| 方案接口 | Owl 对应端点 | 验证结果 |
|
||||
|----------|------------|:---:|
|
||||
| IHasFlatDevices.GetAllDevicesAsync | GET /devices, GET /channels | ✅ |
|
||||
| IHasStreams.GetLiveUrlAsync | POST /channels/:id/play | ✅ |
|
||||
| IHasStreams.GetPlaybackUrlAsync | GET /recordings/channels/:cid/index.m3u8?start_ms=&end_ms= | ✅ |
|
||||
| IHasStreams.StopPlayAsync | POST /channels/:id/stop | ✅ |
|
||||
| IHasStreams.PtzControlAsync | POST /channels/:id/ptz/control | ✅ (仅 continuous+stop) |
|
||||
| IHasStreams.GetRecordingsAsync | GET /recordings, GET /recordings/timeline | ✅ |
|
||||
| IAcceptsMetadataPush.PushMetadataAsync | PUT /devices/:id | ✅ |
|
||||
|
||||
---
|
||||
|
||||
### §三 数据模型 【通过】
|
||||
|
||||
#### 3.1-3.3 表结构
|
||||
|
||||
| 评估项 | 结论 |
|
||||
|--------|------|
|
||||
| 6 张表 vs MC4.0+Owl 需求 | 完全覆盖。ExtraData JSON 替代扩展表，新增适配器不增表 |
|
||||
| DeviceGroup 字典 | 正确。5 个分组值覆盖现在及未来可预见的设备类型 |
|
||||
| PointId 替代 RegionId | 正确。对齐用户现有层级 warehouse_regions→warehouse_devicepoint→base_device |
|
||||
| DeviceCategory 18 个字典值 | 完全对齐用户提供的设备清单 |
|
||||
| 9 个字典字段类型 NVARCHAR | 正确。Vol.Pro 字典要求字符串类型 |
|
||||
| 字段分治规则（网关字段/管理员字段） | 正确。解决了上一版 v2.0 的 P0-1 |
|
||||
|
||||
**数据库完整性检查**:
|
||||
- ✅ 所有主键 INT AUTO_INCREMENT
|
||||
- ✅ 关联字段同名同类型（DeviceId→INT, ChannelId→INT）
|
||||
- ✅ 无 FOREIGN KEY 约束（Vol.Pro 通过同名字段自动关联）
|
||||
- ✅ 查询加速索引覆盖所有关联字段和业务查询字段
|
||||
|
||||
#### 3.6 层级示例
|
||||
|
||||
| 评估项 | 结论 |
|
||||
|--------|------|
|
||||
| NVR→通道 双重身份 | 正确。通道=base_device子记录+video_channel扩展记录 |
|
||||
| video_channel.DeviceId 指向通道自身 | 正确。v3.0 已明确，v2.0 存在歧义 |
|
||||
|
||||
---
|
||||
|
||||
### §四 Vol.Pro 同步接口 【通过】
|
||||
|
||||
| 评估项 | 结论 |
|
||||
|--------|------|
|
||||
| 首次入库 vs 增量更新分治逻辑 | 正确。用 `entity.DeviceId==0` 判断是否首次 |
|
||||
| parentSourceId→ParentDeviceId 映射 | 正确。批量查询已有设备字典，O(1) 查找 |
|
||||
| ExtraData 一行承载所有适配器字段 | 正确。新增适配器零改动 |
|
||||
| SqlSugar Upsert 语义 | ⚠️ 见 Vol.Pro 框架注意事项 |
|
||||
|
||||
> **Vol.Pro 框架注意事项**: Vol.Pro 使用 SqlSugar ORM，`Update()` 方法默认更新全部字段。需在 Entity 上标注 `[SugarColumn(IsIgnore=true)]` 来保护管理员字段不被覆盖，或者在 `Update()` 前 `ClearUpdateColumns()` 仅指定网关字段。建议使用 `_db.Updateable(entity).UpdateColumns(it => new { it.IsOnline, it.IsParent, ... }).ExecuteCommand()` 精确控制。
|
||||
|
||||
---
|
||||
|
||||
### §五 管理端页面 【通过，1 处建议】
|
||||
|
||||
| 评估项 | 结论 |
|
||||
|--------|------|
|
||||
| Vol.Pro 框架兼容性 | 正确。el-tree + el-table 为 Element Plus 标准组件，Vol.Pro 支持 |
|
||||
| 按钮矩阵按 DeviceGroup 路由 | 正确。actionMap 字典路由，新增设备类型只需加一个组件 |
|
||||
| 云台按钮仅方向键 | 正确。与 Owl PTZ 实际能力一致 |
|
||||
| DeviceManager 页面为自定义Vue页面 | 正确。在 `views/warehouse/DeviceManager/` 下独立存在，不被生成器覆盖 |
|
||||
|
||||
**Vol.Pro 生成页面与自定义页面关系**:
|
||||
- `base_device` 的标准 CRUD 生成页面保留，用于批量数据维护
|
||||
- `/device-manager` 自定义页面用于可视化区域管理
|
||||
- 在生成页面的 extension 中加跳转按钮
|
||||
- 符合 Vol.Pro `extension/` + `Partial/` 扩展机制
|
||||
|
||||
**建议**: 视频设备"实时预览"按钮点击后弹窗中的 Jessibuca 播放器，建议在首次播放失败（1-3s 延迟后仍未出画面）时自动重试一次。Owl+ZLM 的按需拉流机制在首次播放时有信令建立延迟。
|
||||
|
||||
---
|
||||
|
||||
### §六 同步策略 【通过，1 处补充】
|
||||
|
||||
| 评估项 | 结论 |
|
||||
|--------|------|
|
||||
| MC4.0 FullReplace 模式 | 正确。MC4.0 是唯一设备源 |
|
||||
| Owl Merge 模式 | 正确。Owl 和 Vol.Pro 可并行管理设备 |
|
||||
| 告警确认双向写回 | 正确。B9 成功后更新本地 State |
|
||||
| 录像同步策略 | 正确。方式一（按需）+ 方式二（定时）组合 |
|
||||
| 反方向写回矩阵 | 正确。Owl 支持改名+PTZ，MC4.0 不支持改名 |
|
||||
|
||||
**补充**: MC4.0 告警确认响应仅为 `{}`（空对象），无确认状态返回。Mc4Adapter.ConfirmAlarmAsync 应在 HTTP 200 即为成功，不做响应体解析。
|
||||
|
||||
---
|
||||
|
||||
### §七 部署拓扑 【通过】
|
||||
|
||||
| 评估项 | 结论 |
|
||||
|--------|------|
|
||||
| Owl 端口 15123 | 正确 |
|
||||
| MC4 端口 3000 | 正确（MC4.0 API 文档 §1.2） |
|
||||
| Gateway 端口 5100 | 合理，与 9100 不冲突 |
|
||||
| 多网关实例 5100/5101 | 合理 |
|
||||
| 网络拓扑 | 网关需访问 Owl(:15123)+MC4(:3000)，Vol.Pro 只需访问网关(:5100) |
|
||||
|
||||
---
|
||||
|
||||
### §八～十 【通过】
|
||||
|
||||
实施路线、新增整合流程、代码组织规范均正确且与 Vol.Pro 框架兼容。
|
||||
|
||||
---
|
||||
|
||||
## 三、与 Vol.Pro 框架深度兼容性分析
|
||||
|
||||
基于 Vol.Pro 官方文档（doc.volcore.xyz）的评估：
|
||||
|
||||
### 3.1 代码生成器兼容性
|
||||
|
||||
| 框架能力 | 方案使用方式 | 兼容性 |
|
||||
|----------|------------|:---:|
|
||||
| 建表后自动生成 CRUD | 6 张表跑生成器 | ✅ |
|
||||
| Entity 字段自动生成表单 | 全部字段含 COMMENT 支持 | ✅ |
|
||||
| 数据字典绑定 | 9 个字典字段绑定 | ✅ |
|
||||
| Partial 扩展目录 | DeviceManagerController.cs 在 Partial/ 下 | ✅ |
|
||||
| 代码生成器覆盖保护 | extension/ + Partial/ 不被覆盖 | ✅ |
|
||||
|
||||
### 3.2 前端框架兼容性
|
||||
|
||||
| 框架能力 | 方案使用方式 | 兼容性 |
|
||||
|----------|------------|:---:|
|
||||
| view-grid 组件 | 保留但不用于设备管理页 | ✅ |
|
||||
| slot 数据插槽 | 生成页面插入跳转按钮 | ✅ |
|
||||
| extension/*.jsx | 自定义按钮和生命周期 | ✅ |
|
||||
| 自定义 Vue 页面 | DeviceManager/ 独立目录 | ✅ |
|
||||
| el-tree + el-table | Element Plus 标准组件 | ✅ |
|
||||
| 路由注册 | `/device-manager` | ✅ |
|
||||
|
||||
### 3.3 后端框架兼容性
|
||||
|
||||
| 框架能力 | 方案使用方式 | 兼容性 |
|
||||
|----------|------------|:---:|
|
||||
| IDependency 自动注入 | GatewayClient : IDependency | ✅ |
|
||||
| Autofac | 所有服务自动注册 | ✅ |
|
||||
| SqlSugar | Upsert 配合字段分治 | ⚠️ 需要精确 Update 列指定 |
|
||||
| Quartz | SyncDevicesJob + HeartbeatJob | ✅ |
|
||||
| SignalR | IoTDataHub | ✅ |
|
||||
| JWT 认证 | 网关和 Vol.Pro 间无需 JWT（NodeToken） | ✅ |
|
||||
|
||||
> 唯一需要额外处理的：SqlSugar 的精确列更新。方案 §四 的示例代码已给出 `_db.Update(entity)`，实际使用时建议改为 `_db.Updateable(entity).UpdateColumns(...)` 精确指定更新列。
|
||||
|
||||
---
|
||||
|
||||
## 四、安全性评估
|
||||
|
||||
| 评估项 | 结论 |
|
||||
|--------|------|
|
||||
| 网关认证（NodeToken） | 正确。不受 JWT 过期影响 |
|
||||
| B 组 API 无认证 | 可行。内网部署 + IP 白名单 |
|
||||
| Owl JWT Token 缓存 | TokenManager 用 MemoryCache，3 天有效期 |
|
||||
| MC4.0 Token 缓存 | 同上，注意 MC4 使用 `token` header 非 `Bearer` |
|
||||
| 密码在 appsettings.json 明文 | ⚠️ 建议增加加密 |
|
||||
|
||||
**建议**: 网关 `appsettings.json` 中 Owl/MC4 密码建议使用 ASP.NET Core 的 Secret Manager 或环境变量注入，避免明文存储在版本库中。
|
||||
|
||||
---
|
||||
|
||||
## 五、性能评估
|
||||
|
||||
| 场景 | 评估 | 结果 |
|
||||
|------|------|------|
|
||||
| 网关启动注册 | 1 次 HTTP POST，< 100ms | ✅ |
|
||||
| 心跳 | 15s 一次 POST，开销极小 | ✅ |
|
||||
| MC4.0 设备同步 | 100 设备对象树解析 + Upsert，< 2s | ✅ |
|
||||
| Owl 设备同步 | 分页拉取 100 设备，< 5s | ✅ |
|
||||
| 实时数据查询 | 网关→MC4.0 HTTP 往返 + 解析，< 1s | ✅ |
|
||||
| 9 路视频墙 | 9 路 WS-FLV 同时播放，ZLM 官方标称单机 10W 并发 | ✅ |
|
||||
| base_device 单表规模 | 1000 设备 × ExtraData JSON ≈ 2MB | ✅ |
|
||||
| IoT_DeviceData 归档 | 1000 设备 × 每小时 1 条 = 24000 条/天 | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## 六、可扩展性验证
|
||||
|
||||
### "新增海康门禁"全链路推演
|
||||
|
||||
```
|
||||
Day 1:
|
||||
1. 新建 IntegrationGateway.Adapters.HikvisionAccess 项目
|
||||
2. 实现 IHasFlatDevices + IHasAlarms
|
||||
- 同步设备时填充 DeviceGroup='门禁设备'
|
||||
- DeviceCategory='门禁一体机'
|
||||
- ExtraData={ hikDeviceId, doorType, readerType }
|
||||
3. 注册到 Host
|
||||
|
||||
Day 2:
|
||||
4. 管理端字典加一条"门禁一体机" → 基础 CRUD 自动可用
|
||||
5. 前端新建 AccessDeviceActions.vue (~80行)
|
||||
6. DeviceTable.vue 的 actionMap 加一行: '门禁设备': AccessDeviceActions
|
||||
|
||||
后端改动: 0 行
|
||||
网关改动: 适配器类
|
||||
DB 改动: 0 行
|
||||
```
|
||||
|
||||
**验证通过**。
|
||||
|
||||
---
|
||||
|
||||
## 七、发现的新问题与建议
|
||||
|
||||
本次深度评估新发现 **3 个细节问题**，均不影响架构，建议在实施时注意：
|
||||
|
||||
### N1: MC4.0 分页参数差异
|
||||
|
||||
MC4.0 使用 `skip/limit`，非标准 `page/size`。Mc4Adapter 实现时需转换。
|
||||
|
||||
**建议**: Mc4Adapter 内部封装 `ToMc4Pagination(int page, int size)` 方法。
|
||||
|
||||
### N2: Owl JWT 加密流程细节
|
||||
|
||||
Owl 登录加密目前 Gateway 配置文件存明文密码。实际流程是 `GET /login/key` → 获取 RSA 公钥 → `POST /login { data: RSA加密后的JSON }`。方案文档未展开但现有 TokenManager 设计可容纳。
|
||||
|
||||
**建议**: OwlAdapter.InitializeAsync 中实现完整的 RSA 加密登录链路，不在配置文件中存密码则可以用环境变量。
|
||||
|
||||
### N3: 字典初始化时机
|
||||
|
||||
Phase 0 Day 2 字典初始化需要在代码生成之后进行，因为代码生成器不创建字典。顺序应为: 建表 → 代码生成 → 字典初始化 → 绑定字典到字段。
|
||||
|
||||
**建议**: 实施手册中明确此顺序。
|
||||
|
||||
---
|
||||
|
||||
## 八、最终结论
|
||||
|
||||
| 结论 | 说明 |
|
||||
|:---:|------|
|
||||
| **可行** | 方案在所有维度通过了严格的技术验证 |
|
||||
| **完整** | 13 个 API 完整定义，4 组数据流闭环，6 张表全覆盖 |
|
||||
| **兼容** | 与 Owl v1.3.0、ZLMediaKit master、MC4.0 API、Vol.Pro 框架均对齐 |
|
||||
| **可扩展** | 新增一种设备类型 = 1 个适配器类 + 1 个前端组件，后端零改动 |
|
||||
| **可运维** | 网关无状态 3 配置项，心跳自动检测，字典在 Vol.Pro 管理端维护 |
|
||||
|
||||
**遗留物**: 3 个 N 级建议（MC4 分页参数转换、Owl RSA 登录实现、字典初始化顺序），可在 Phase 0 实施时自然解决，无需修改方案文档。
|
||||
|
||||
---
|
||||
|
||||
> 本报告为 SecMPS 整合方案的最终技术验收文件。
|
||||
> 签名: 资深架构师评估
|
||||
> 日期: 2026-05-16
|
||||
253
doc/整合方案/SecMPS_整合项目实施手册_v3.0.md
Normal file
253
doc/整合方案/SecMPS_整合项目实施手册_v3.0.md
Normal file
@@ -0,0 +1,253 @@
|
||||
# SecMPS 整合项目实施手册
|
||||
|
||||
> **版本**: v3.0
|
||||
> **日期**: 2026-05-16
|
||||
> **基于**: SecMPS_最终整合方案_v3.0.md
|
||||
> **工期**: 18-20 个工作日
|
||||
> **开发模式**: 单人 + Agent，Squash Merge 主线策略
|
||||
|
||||
---
|
||||
|
||||
## 分支管理策略
|
||||
|
||||
```
|
||||
master ──────────────────────────────────────────────→ v3.0.0
|
||||
│ ┌─ squash ─┐ ┌─ squash ─┐ ┌─ squash ─┐
|
||||
├── phase/0 ├── phase/1 ├── phase/2 ├── ...
|
||||
└── infrastructure └── owl-video └── mc4-iot └──
|
||||
```
|
||||
|
||||
### 每个 Phase 标准流程
|
||||
|
||||
```bash
|
||||
git checkout master
|
||||
git checkout -b phase/{n}-{name}
|
||||
# 开发 + 提交
|
||||
git checkout master && git merge --squash phase/{n}-{name}
|
||||
git commit -m "Phase {n}: {标题}" && git push && git tag phase-{n}-done
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 前置检查清单（Day 0）
|
||||
|
||||
| # | 检查项 | 验证方式 | 阻塞 |
|
||||
|---|--------|----------|------|
|
||||
| 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 |
|
||||
| 6 | MySQL 建表权限 | 执行 CREATE TABLE | Phase 0 |
|
||||
| 7 | Node.js >= 20.19 | node -v | Phase 3 |
|
||||
|
||||
---
|
||||
|
||||
## Phase 0：基础设施（Day 1-2）
|
||||
|
||||
### Day 1 — 从头搭建网关 + 数据库
|
||||
|
||||
**任务 1.1 — 创建 Gateway 解决方案**
|
||||
|
||||
在 `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",
|
||||
"NodeCode": "gw-31ku",
|
||||
"NodeToken": "xxxxxxxxxx",
|
||||
"Urls": "http://*:5100"
|
||||
}
|
||||
```
|
||||
|
||||
`Program.cs` 启动逻辑:
|
||||
```csharp
|
||||
builder.Services.AddControllers();
|
||||
builder.Services.AddMemoryCache();
|
||||
builder.Services.AddHttpClient("VolPro", c => {
|
||||
c.BaseAddress = new Uri(builder.Configuration["VolProBaseUrl"]);
|
||||
});
|
||||
builder.Services.AddSingleton<AdapterRegistry>();
|
||||
builder.Services.AddSingleton<TokenManager>();
|
||||
// 启动后自动调 Vol.Pro 注册
|
||||
app.Lifetime.ApplicationStarted.Register(() => {
|
||||
Task.Run(() => RegisterWithVolPro(app));
|
||||
});
|
||||
```
|
||||
|
||||
新增 `GatewayClient.cs` — 封装网关→Vol.Pro 的 HTTP 调用（A1注册/A2心跳/A3设备同步/A4告警同步）。
|
||||
|
||||
验证: 网关启动后调 Vol.Pro 的 A1 端点成功，返回 nodeId。
|
||||
|
||||
**任务 1.5 — 执行 db_init.sql（6张表）**
|
||||
|
||||
验证: `SELECT COUNT(*) FROM base_device` → 0，唯一索引 `(AdapterCode, SourceId)` 存在。
|
||||
|
||||
### Day 2 — Vol.Pro 侧集成 + 代码生成 + 字典
|
||||
|
||||
**任务 2.1 — Vol.Pro GatewayClient** (后端调网关的 HTTP 封装)
|
||||
|
||||
新增 `api_sqlsugar/VolPro.Core/Infrastructure/GatewayClient.cs` (IDependency)。
|
||||
封装: 注册/心跳/设备同步/告警同步/实时数据/取流/云台/告警确认。
|
||||
|
||||
**任务 2.2 — Vol.Pro GatewayNodeController** (A组接口服务端)
|
||||
|
||||
新增 `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张表 + 代码生成 + 字典 + API"
|
||||
git push && git tag phase-0-done
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 1：Owl 适配器 + 视频设备页（Day 3-6）
|
||||
|
||||
Owl 端口: **15123**（非 80）。PTZ 仅方向键（continuous+stop），不支持预设位。
|
||||
|
||||
### Day 3 — OwlAdapter
|
||||
创建 Adapters.Owl，实现 IHasFlatDevices+IHasStreams+IAcceptsMetadataPush。Token: GET /login/key → RSA → POST /login。
|
||||
|
||||
### Day 4 — 管理端设备页面框架
|
||||
DeviceManager/index.vue + RegionTree.vue + DeviceTable.vue。
|
||||
|
||||
### Day 5 — 视频操作 + Jessibuca
|
||||
VideoDeviceActions.vue + 播放弹窗 + 方向键云台面板。
|
||||
|
||||
### Day 6 — 联调 + [可选]AI事件接入
|
||||
|
||||
---
|
||||
|
||||
## Phase 2：MC4.0 + IoT（Day 7-11）
|
||||
|
||||
同上 v2.1 手册，增加 MC4.0 skip/limit 分页转换。
|
||||
|
||||
---
|
||||
|
||||
## Phase 3：warehouse 联调（Day 12-17）
|
||||
## Phase 4：验证发布（Day 18-20）
|
||||
|
||||
同上 v2.1 手册，发布标签 v3.0.0。
|
||||
|
||||
---
|
||||
|
||||
## 附录 A：每日检查清单
|
||||
|
||||
```
|
||||
□ 新增 C# 服务实现 IDependency
|
||||
□ Controller 在 Partial/ 目录
|
||||
□ 前端在 extension/ 目录
|
||||
□ 未修改自动生成文件
|
||||
□ 网关同步走字段分治
|
||||
□ parentSourceId 已映射
|
||||
□ 实时数据未写 IoT_DeviceData
|
||||
□ dotnet build 零错误
|
||||
```
|
||||
|
||||
## 附录 B：端口分配
|
||||
|
||||
| 服务 | 端口 |
|
||||
|------|------|
|
||||
| IntegrationGateway | 5100 |
|
||||
| VolPro.WebApi | 9100 |
|
||||
| web.vite | 9000 |
|
||||
| warehouse | 9200 |
|
||||
| Owl 管理端 | **15123** |
|
||||
| MC4.0 | 3000 |
|
||||
|
||||
## 附录 C：里程碑
|
||||
|
||||
| 标签 | 指向 |
|
||||
|------|------|
|
||||
| `phase-0-done` | 网关修正 + 6张表 + 字典 |
|
||||
| `phase-1-done` | OwlAdapter + 视频页 |
|
||||
| `phase-2-done` | Mc4Adapter + IoT + SignalR |
|
||||
| `phase-3-done` | warehouse + 联调 |
|
||||
| `phase-4-done` | 验证 + 文档 |
|
||||
| `v3.0.0` | 正式发布 |
|
||||
|
||||
---
|
||||
|
||||
> 取代: SecMPS_整合项目实施手册_v2.1.md
|
||||
@@ -1,9 +1,8 @@
|
||||
# SecMPS 整合方案（最终版）：IntegrationGateway + 统一设备管理
|
||||
|
||||
> **版本**: v2.0
|
||||
> **日期**: 2026-05-15
|
||||
> **日期**: 2026-05-16
|
||||
> **状态**: 待实施
|
||||
> **替代**: Vol.Pro_MC4.0_整合方案_v1.0、Vol.Pro_Owl_ZLMediaKit_整合方案_v1.0、Vol.Pro_统一设备管理_区域树与地图绑定方案_v1.0
|
||||
|
||||
---
|
||||
|
||||
@@ -11,49 +10,60 @@
|
||||
|
||||
```
|
||||
前端层
|
||||
web.vite 管理端（设备管理页+标准CRUD） warehouse 大屏（Map/Live/IoT/Alarm）
|
||||
│ HTTP REST │ HTTP REST + SignalR
|
||||
▼ ▼
|
||||
web.vite 管理端（设备管理+网关管理） warehouse 大屏（Map/Live/IoT/Alarm）
|
||||
| HTTP REST | HTTP REST + SignalR
|
||||
v v
|
||||
Vol.Pro 后端 (api_sqlsugar)
|
||||
DeviceManagerController / GatewayClient / SignalR Hubs
|
||||
DeviceManagerController / GatewayNodeController / SignalR Hubs
|
||||
Quartz: SyncDevicesJob / RealtimePollJob / AlarmPollJob
|
||||
数据库: Base_Device / warehouse_regions / Device_Video_Ext / Device_IoT_Ext / IoT_DevicePoint / IoT_Alarm
|
||||
│ HTTP REST
|
||||
▼
|
||||
IntegrationGateway (独立服务 :5100)
|
||||
Adapters.Owl (IHasFlatDevices+IHasStreams+IAcceptsMetadataPush)
|
||||
Adapters.MC4 (IHasOwnDeviceTree+IHasPoints+IHasAlarms)
|
||||
Core: AdapterRegistry / SyncEngine / TokenManager / RateLimiter
|
||||
│ HTTP │ HTTP
|
||||
▼ ▼
|
||||
Owl + ZLMediaKit MC4.0 采集网关
|
||||
Docker Compose HTTP API :3000
|
||||
数据库: 6 张表 (base_device / video_channel / video_record / iot_devicedata / iot_alarm / gateway_nodes)
|
||||
| 注册/下发设备/心跳/同步数据
|
||||
v
|
||||
IntegrationGateway 实例A (:5100) IntegrationGateway 实例B (:5101)
|
||||
NodeCode: gw-31ku NodeCode: gw-11ku
|
||||
Adapters: MC4 / Owl Adapters: MC4 / HikvisionISC
|
||||
| HTTP | HTTP
|
||||
v v
|
||||
MC4.0 (:3000) Owl (:80) MC4.0 (:3000) 海康ISC (:80)
|
||||
```
|
||||
|
||||
### 核心设计原则
|
||||
|
||||
- **网关无状态**：配置仅 NodeCode/Token/VolProUrl，挂了重装即恢复
|
||||
- **AdapterCode 双段标识**："mc4:31号库房" 区分同类型多实例
|
||||
- **DeviceGroup 路由**：基类表用字典字段决定适配器和行为，不依赖扩展表
|
||||
- **ExtraData JSON**：所有适配器特有字段存入 ExtraData，新增适配器不增表
|
||||
- **心跳机制**：网关 15s 心跳，Vol.Pro 超 30s 级联设备离线
|
||||
|
||||
---
|
||||
|
||||
## 二、IntegrationGateway 设计
|
||||
## 二、网关架构（方案 C+）
|
||||
|
||||
### 2.1 项目结构
|
||||
### 2.1 网关注册与心跳流程
|
||||
|
||||
```
|
||||
IntegrationGateway/
|
||||
├── src/
|
||||
│ ├── Host/Controllers/ → Devices / Points / Streams / Alarms / Sync / Health
|
||||
│ ├── Core/Abstractions/ → 分型接口
|
||||
│ │ ├── IIntegrationAdapter
|
||||
│ │ ├── IHasOwnDeviceTree (MC4.0)
|
||||
│ │ ├── IHasFlatDevices (Owl)
|
||||
│ │ ├── IHasPoints (MC4.0)
|
||||
│ │ ├── IHasStreams (Owl)
|
||||
│ │ ├── IHasAlarms (通用)
|
||||
│ │ └── IAcceptsMetadataPush (Owl)
|
||||
│ ├── Core/Infrastructure/ → SyncEngine / AdapterRegistry / TokenManager / RateLimiter
|
||||
│ ├── Adapters.Owl/ → OwlAdapter
|
||||
│ └── Adapters.MC4/ → Mc4Adapter
|
||||
管理端: gateway_nodes 表新增 → 生成 NodeCode + Token
|
||||
网关配置: { NodeCode, Token, VolProUrl }
|
||||
网关启动 → POST /register { nodeCode,token,adapterTypes,baseUrl }
|
||||
Vol.Pro 校验 → 更新 AdapterTypes/BaseUrl/IsOnline=在线
|
||||
响应: { gatewayNodeId, devices: [base_device WHERE GatewayNodeId=当前] }
|
||||
网关按 AdapterCode 分流 → Adapter 连接第三方 → 发现子设备
|
||||
网关 → POST /sync → Vol.Pro 写入 base_device（含 ExtraData)
|
||||
网关每 15s → POST /heartbeat { nodeCode, token }
|
||||
Vol.Pro Job: IsOnline=在线 且 LastHeartbeat < now-30s → IsOnline=离线 → 级联设备离线
|
||||
```
|
||||
|
||||
### 2.2 适配器能力矩阵
|
||||
### 2.2 网关配置
|
||||
|
||||
```json
|
||||
{
|
||||
"VolProBaseUrl": "http://localhost:9100",
|
||||
"NodeCode": "gw-31ku",
|
||||
"NodeToken": "xxxxxxxxxx"
|
||||
}
|
||||
```
|
||||
|
||||
### 2.3 适配器能力矩阵
|
||||
|
||||
| 接口 | Owl | MC4.0 | 门禁(未来) |
|
||||
|------|:---:|:-----:|:----------:|
|
||||
@@ -64,7 +74,7 @@ IntegrationGateway/
|
||||
| IHasAlarms | ⚠️ | ✅ | ✅ |
|
||||
| IAcceptsMetadataPush | ✅ | ❌ | ⚠️ |
|
||||
|
||||
### 2.3 双向同步引擎
|
||||
### 2.4 双向同步引擎
|
||||
|
||||
| 方向 | 说明 | MC4.0 | Owl |
|
||||
|------|------|-------|-----|
|
||||
@@ -72,152 +82,241 @@ IntegrationGateway/
|
||||
| PushToSource | Vol.Pro→第三方 | 告警确认/控制 | 元数据/PTZ |
|
||||
| Bidirectional | 先写第三方再更新本地 | 告警确认 | — |
|
||||
|
||||
### 2.4 Gateway API
|
||||
### 2.5 对接 API 规范
|
||||
|
||||
网关与 Vol.Pro 之间有两组接口，调用方向不同。
|
||||
|
||||
#### A. 网关 → Vol.Pro（网关主动调用）
|
||||
|
||||
| # | 接口 | 说明 |
|
||||
|---|------|------|
|
||||
| A1 | `POST /api/gateway/register` | 网关启动注册，上报身份与能力，获取所管设备列表 |
|
||||
| A2 | `POST /api/gateway/heartbeat` | 心跳（每 15s），Vol.Pro 更新在线状态 |
|
||||
| A3 | `POST /api/gateway/sync/devices` | 上送设备数据（新增/变更/离线） |
|
||||
| A4 | `POST /api/gateway/sync/alarms` | 上送告警数据 |
|
||||
|
||||
**A1 注册** — 认证: NodeToken
|
||||
|
||||
```
|
||||
GET /api/gateway/health
|
||||
GET /api/gateway/devices?adapter=&page=&size=
|
||||
GET /api/gateway/devices/sync?adapter=
|
||||
GET /api/gateway/realtime/{adapter}/{deviceId}
|
||||
POST /api/gateway/realtime/{adapter}/control
|
||||
GET /api/gateway/streams/{adapter}/{id}/live
|
||||
POST /api/gateway/streams/{adapter}/{id}/ptz
|
||||
GET /api/gateway/alarms/{adapter}?from=&to=
|
||||
POST /api/gateway/alarms/{adapter}/{id}/confirm
|
||||
Request: { nodeCode, token, adapterTypes, baseUrl }
|
||||
Response: { nodeId, devices: [ base_device 列表(当前网关负责的顶层设备) ] }
|
||||
Error: 401 认证失败
|
||||
```
|
||||
|
||||
**A2 心跳** — 认证: NodeToken
|
||||
|
||||
```
|
||||
Request: { nodeCode, token }
|
||||
Response: { status: "ok" }
|
||||
```
|
||||
|
||||
**A3 设备同步** — 认证: NodeToken
|
||||
|
||||
```
|
||||
Request: { nodeCode, token, devices: [{ adapterCode, sourceId, name, category, group,
|
||||
isParent, parentSourceId, isOnline, ipAddress, port, extraData }] }
|
||||
Response: { added, updated, removed }
|
||||
```
|
||||
> 网关只发自己负责的字段（ExtraData 中的适配器属性 + 公共状态字段），不碰管理员字段（DeviceName/Category/Location/MapModelId…）。Vol.Pro 首次入库写全量，后续仅更新网关负责的列。
|
||||
|
||||
**A4 告警同步** — 认证: NodeToken
|
||||
|
||||
```
|
||||
Request: { nodeCode, token, alarms: [{ sourceAlarmId, deviceSourceId, adapterCode,
|
||||
level, desc, value, startTime }] }
|
||||
Response: { added }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、数据模型
|
||||
#### B. Vol.Pro / 管理端 → 网关（查询与控制）
|
||||
|
||||
| # | 接口 | 说明 |
|
||||
|---|------|------|
|
||||
| B1 | `GET /api/gateway/health` | 网关及所有适配器状态 |
|
||||
| B2 | `GET /api/gateway/devices?adapter=&page=&size=` | 设备列表（实时查第三方） |
|
||||
| B3 | `POST /api/gateway/devices/sync?adapter=` | 手动触发全量同步 |
|
||||
| B4 | `GET /api/gateway/realtime/{adapter}/{deviceId}` | 实时点位值 |
|
||||
| B5 | `POST /api/gateway/realtime/{adapter}/control` | 反向控制 { deviceSourceId, pointIndex, value } |
|
||||
| B6 | `GET /api/gateway/streams/{adapter}/{channelId}/live` | 取流地址 → { wsFlv, httpFlv, hls, webrtc } |
|
||||
| B7 | `POST /api/gateway/streams/{adapter}/{channelId}/ptz` | 云台控制 { direction, speed } |
|
||||
| B8 | `GET /api/gateway/alarms/{adapter}?from=&to=&page=&size=` | 告警查询 |
|
||||
| B9 | `POST /api/gateway/alarms/{adapter}/{alarmId}/confirm` | 告警确认（写回第三方） |
|
||||
|
||||
> B 组接口由管理端或 Vol.Pro 后端直接调用网关，认证方式为内网直连或网关侧 IP 白名单。
|
||||
|
||||
---
|
||||
|
||||
## 三、数据模型（6 张表）
|
||||
|
||||
### 3.1 区域表 warehouse_regions（现有）
|
||||
|
||||
层级: warehouse_regions(区域) → warehouse_devicepoint(点位) → base_device(设备)
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| Id | int PK |
|
||||
| RegionName | nvarchar(255) |
|
||||
| ParentId | int? (自引用树) |
|
||||
|
||||
### 3.2 统一设备主表 Base_Device（新建）
|
||||
### 3.2 网关节点表 gateway_nodes
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| DeviceId | uniqueidentifier PK | Vol.Pro内部ID |
|
||||
| DeviceName | nvarchar(100) | 本地名称 |
|
||||
| **AdapterCode** | nvarchar(50) | owl/mc4/hikvision_access |
|
||||
| **SourceId** | nvarchar(100) | 第三方原始ID |
|
||||
| DeviceCategory | int | 1=视频 2=IoT 3=门禁 4=道闸 5=报警 |
|
||||
| DeviceType | nvarchar(50) | GB28181/TempSensor... |
|
||||
| **RegionId** | int? | FK→warehouse_regions.Id |
|
||||
| **IsParent** | bit | 是否父设备 |
|
||||
| **ParentDeviceId** | uniqueidentifier? | 父设备自引用 |
|
||||
| IsOnline | int | 0/1 |
|
||||
| **MapModelId** | nvarchar(100) | VgoMap模型ID |
|
||||
| MapModelScale | float | |
|
||||
| MapModelRotation | nvarchar(100) | |
|
||||
| Lat/Lng | float | WGS84 |
|
||||
| ExtraData | nvarchar(max) | 适配器原始JSON |
|
||||
| LocalOverrides | nvarchar(max) | 本地覆盖JSON |
|
||||
| SyncVersion | bigint | 乐观锁 |
|
||||
| LastSyncTime | datetime | |
|
||||
| NodeId | INT AUTO_INCREMENT | 网关节点ID |
|
||||
| NodeCode | NVARCHAR(50) | 网关唯一编码（管理端配置） |
|
||||
| NodeName | NVARCHAR(100) | 网关名称 |
|
||||
| NodeToken | NVARCHAR(100) | 认证令牌（管理端生成） |
|
||||
| AdapterTypes | NVARCHAR(200) | 适配器类型（网关上报） |
|
||||
| BaseUrl | NVARCHAR(200) | 网关地址（网关上报） |
|
||||
| LastHeartbeat | DATETIME | 上次心跳时间 |
|
||||
| IsOnline | NVARCHAR(20) | 在线状态(字典: 在线/离线) |
|
||||
| Enable | NVARCHAR(20) | 启用状态(字典: 启用/禁用) |
|
||||
|
||||
### 3.3 统一设备主表 base_device
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| DeviceId | INT AUTO_INCREMENT | Vol.Pro内部ID |
|
||||
| DeviceName | NVARCHAR(100) | 设备名称 |
|
||||
| AdapterCode | NVARCHAR(50) | "mc4:31号库房"（类型:实例） |
|
||||
| SourceId | NVARCHAR(100) | 源系统设备ID |
|
||||
| **DeviceCategory** | NVARCHAR(50) | 设备种类(字典: 摄像机/温湿度变送器/...) |
|
||||
| **DeviceGroup** | NVARCHAR(20) | 设备分组(字典: 视频设备/IoT设备/门禁设备/道闸设备/报警设备) |
|
||||
| PointId | INT? | 所属点位ID |
|
||||
| GatewayNodeId | INT? | 所属网关节点ID |
|
||||
| IsParent | NVARCHAR(20) | 是否父设备(字典: 是/否) |
|
||||
| ParentDeviceId | INT? | 父设备自引用 |
|
||||
| IsOnline | NVARCHAR(20) | 在线状态(字典: 在线/离线) |
|
||||
| MapModelId | NVARCHAR(100) | VgoMap模型ID |
|
||||
| MapModelScale | FLOAT | |
|
||||
| MapModelRotation | NVARCHAR(100) | |
|
||||
| **ExtraData** | TEXT | ★ 适配器扩展JSON(Owl/MC4/门禁字段均存于此) |
|
||||
| LastSyncTime | DATETIME | |
|
||||
| Enable | NVARCHAR(20) | 启用状态(字典: 启用/禁用) |
|
||||
|
||||
唯一约束: (AdapterCode, SourceId)
|
||||
|
||||
### 3.3 扩展表
|
||||
### 3.4 DeviceGroup 分组规则
|
||||
|
||||
- **Device_Video_Ext**: 视频设备扩展（OwlDeviceId, Protocol, ChannelCount）
|
||||
- **Device_IoT_Ext**: IoT设备扩展（Mc4DeviceId, ObjectType, Tag）
|
||||
- **Video_Channel**: 视频通道（OwlChannelId, DeviceId, HasPtz）
|
||||
- **Video_Record**: 录像记录
|
||||
- **IoT_DevicePoint**: 点位表（PointIndex, PointName, Unit, IsControlPoint）
|
||||
- **IoT_DeviceData**: 历史归档（仅存快照，实时不入库）
|
||||
- **IoT_Alarm**: 告警记录（Mc4AlarmId, AlarmLevel, State）
|
||||
Vol.Pro 同步接口通过 DeviceGroup 路由，无需硬编码：
|
||||
|
||||
### 3.4 层级示例
|
||||
| DeviceGroup | 网关适配器 | 前端按钮组 | 同步模式 |
|
||||
|:---:|------|------|:---:|
|
||||
| 视频设备 | OwlAdapter → IHasStreams | 实时预览/云台/回放/快照 | Merge |
|
||||
| IoT设备 | Mc4Adapter → IHasPoints | 实时数据/控制/告警 | FullReplace |
|
||||
| 门禁设备 | AccessAdapter | 远程开门/记录/告警 | Merge |
|
||||
| 道闸设备 | BarrierAdapter | 抬杆/落杆/记录 | Merge |
|
||||
| 报警设备 | AlarmAdapter | 查看告警/布防撤防 | Merge |
|
||||
|
||||
### 3.5 ExtraData 格式示例
|
||||
|
||||
```json
|
||||
// 摄像机 (Owl)
|
||||
{ "owlDeviceId": "gb_xxx", "protocol": "GB28181", "manufacturer": "海康" }
|
||||
|
||||
// 温湿度变送器 (MC4子设备)
|
||||
{ "mc4DeviceId": 1001, "pointIndex": 0, "unit": "℃", "isControlPoint": false }
|
||||
|
||||
// 空调控制器 (MC4子设备)
|
||||
{ "mc4DeviceId": 1002, "pointIndex": 2, "unit": null, "isControlPoint": true }
|
||||
|
||||
// 未来门禁
|
||||
{ "hikDeviceId": "door_01", "doorType": "单门", "readerType": "IC卡" }
|
||||
```
|
||||
|
||||
### 3.6 层级示例
|
||||
|
||||
```
|
||||
warehouse_regions: 厂区 → 新库区 → 31号库房
|
||||
Base_Device (RegionId=3):
|
||||
东北角高位摄像机 (Category=1)
|
||||
人员计数摄像机 (Category=1)
|
||||
动环采集器 (Category=2, IsParent=1)
|
||||
├── 温湿度探头 (ParentDeviceId=采集器)
|
||||
├── 空调控制器 (ParentDeviceId=采集器)
|
||||
├── 除湿机 (ParentDeviceId=采集器)
|
||||
└── 紧急报警按钮 (ParentDeviceId=采集器)
|
||||
gateway_nodes: gw-31ku
|
||||
|
||||
warehouse_regions → warehouse_devicepoint → base_device
|
||||
区域 点位 设备
|
||||
|
||||
例: 厂区 → 新库区 → 31号库房(点位) → 设备
|
||||
|
||||
base_device (PointId=点位ID, GatewayNodeId=gw-31ku.NodeId):
|
||||
东北角高位摄像机 (DeviceCategory=摄像机, DeviceGroup=视频设备, ExtraData={owlDeviceId,...})
|
||||
人员计数摄像机 (DeviceCategory=摄像机, DeviceGroup=视频设备)
|
||||
动环采集器 (DeviceCategory=动环采集器, DeviceGroup=IoT设备, IsParent=是)
|
||||
├── 温湿度变送器 (DeviceCategory=温湿度变送器, ParentDeviceId=采集器, ExtraData={pointIndex:0,unit:"℃"})
|
||||
├── 空调控制器 (DeviceCategory=空调控制器, ParentDeviceId=采集器, ExtraData={pointIndex:2,isControlPoint:true})
|
||||
├── 除湿/恒湿机 (DeviceCategory=除湿/恒湿机, ParentDeviceId=采集器)
|
||||
└── 紧急报警按钮 (DeviceCategory=紧急报警按钮, DeviceGroup=报警设备, ParentDeviceId=采集器)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、管理端统一设备页面
|
||||
## 四、Vol.Pro 同步接口（新增适配器零改动）
|
||||
|
||||
### 4.1 布局
|
||||
```csharp
|
||||
// POST /api/gateway/sync
|
||||
public async Task SyncDevices(string nodeCode, List<StandardDevice> devices)
|
||||
{
|
||||
var node = await _db.gateway_nodes.FirstAsync(n => n.NodeCode == nodeCode);
|
||||
foreach (var d in devices)
|
||||
{
|
||||
var entity = await _db.base_device
|
||||
.FirstOrDefaultAsync(x => x.AdapterCode == d.AdapterCode && x.SourceId == d.SourceId)
|
||||
?? new base_device();
|
||||
|
||||
entity.DeviceName = d.Name;
|
||||
entity.DeviceGroup = d.Group; // 字典: 视频设备/IoT设备/...
|
||||
entity.DeviceCategory = d.Category; // 字典: 摄像机/温湿度变送器/...
|
||||
entity.IsOnline = d.IsOnline ? "在线" : "离线";
|
||||
entity.IsParent = d.IsParent ? "是" : "否";
|
||||
entity.ParentDeviceId = d.ParentSourceId; // 网关同步过来的父级关系
|
||||
entity.GatewayNodeId = node.NodeId;
|
||||
entity.ExtraData = d.ExtraDataJson; // ★ 一行，适配器字段全在这里
|
||||
// ... 公共字段赋值 ...
|
||||
|
||||
_db.base_device.Upsert(entity);
|
||||
}
|
||||
await _db.SaveChangesAsync();
|
||||
}
|
||||
```
|
||||
┌──────────────────┬───────────────────────────────────────┐
|
||||
│ 顶部工具栏 │ │
|
||||
├──────────────────┼───────────────────────────────────────┤
|
||||
│ 左侧区域树 │ 右侧设备列表 │
|
||||
│ │ │
|
||||
│ 📁 厂区 │ 区域:31号库房 最后同步:05-15 │
|
||||
│ 📁 新库区 │ ┌──────────────────────────────┐ │
|
||||
│ 📁 31号库房 ● │ │ ▸动环采集器 MC4.0 █在线 │ │
|
||||
│ 📁 11号库房 │ │ 东北角摄像机 Owl █在线 │ │
|
||||
│ │ └──────────────────────────────┘ │
|
||||
│ [+新建区域] │ │
|
||||
└──────────────────┴───────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 4.2 前端文件
|
||||
|
||||
```
|
||||
web.vite/src/views/warehouse/DeviceManager/
|
||||
├── index.vue # 主页面（左树右表）
|
||||
├── components/
|
||||
│ ├── RegionTree.vue # el-tree 区域树
|
||||
│ ├── DeviceTable.vue # el-table 可展开行
|
||||
│ ├── DeviceEditDialog.vue # 编辑弹框
|
||||
│ ├── MapBindingPanel.vue # 地图绑定面板
|
||||
│ ├── VideoDeviceActions.vue # 视频操作按钮组
|
||||
│ └── IoTDeviceActions.vue # IoT操作按钮组
|
||||
└── api/deviceManager.js
|
||||
|
||||
路由: /device-manager
|
||||
```
|
||||
|
||||
### 4.3 后端 API
|
||||
|
||||
| 接口 | 说明 |
|
||||
|------|------|
|
||||
| GET `/api/DeviceManager/GetRegionTree` | 区域树+设备数量 |
|
||||
| GET `/api/DeviceManager/GetDevicesByRegion?regionId=3` | 区域设备列表(含子设备) |
|
||||
| PUT `/api/DeviceManager/{deviceId}` | 更新设备(含地图绑定) |
|
||||
| POST `/api/DeviceManager/SyncFromGateway` | 手动同步 |
|
||||
|
||||
Controller 路径: `Controllers/Warehouse/Partial/DeviceManagerController.cs`
|
||||
|
||||
### 4.4 操作按钮矩阵
|
||||
|
||||
| Category | 按钮 |
|
||||
|----------|------|
|
||||
| 1-视频 | 实时预览/云台控制/查看回放/获取快照/同步通道 |
|
||||
| 2-IoT | 查看实时数据/设备控制/刷新点位/查看告警 |
|
||||
| 3-门禁 | 远程开门/查看记录/查看告警 |
|
||||
| 4-道闸 | 抬杆/落杆/查看记录 |
|
||||
|
||||
---
|
||||
|
||||
## 五、同步策略
|
||||
## 五、管理端统一设备页面
|
||||
|
||||
### 5.1 操作按钮矩阵（按 DeviceGroup 路由）
|
||||
|
||||
| DeviceGroup | 操作按钮 |
|
||||
|:---:|------|
|
||||
| 视频设备 | 实时预览 / 云台控制 / 查看回放 / 获取快照 / 同步通道 |
|
||||
| IoT设备 | 查看实时数据 / 设备控制 / 刷新点位 / 查看告警 |
|
||||
| 门禁设备 | 远程开门 / 查看记录 / 查看告警 |
|
||||
| 道闸设备 | 抬杆 / 落杆 / 查看记录 |
|
||||
| 报警设备 | 查看告警 / 布防撤防 |
|
||||
|
||||
### 5.2 前端按钮路由
|
||||
|
||||
```javascript
|
||||
// DeviceTable.vue
|
||||
const actionMap = {
|
||||
'视频设备': VideoDeviceActions,
|
||||
'IoT设备': IoTDeviceActions,
|
||||
'门禁设备': AccessDeviceActions,
|
||||
'道闸设备': BarrierDeviceActions,
|
||||
'报警设备': AlarmDeviceActions,
|
||||
}
|
||||
// 渲染: actionMap[device.DeviceGroup]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、同步策略
|
||||
|
||||
### MC4.0 → 区域树+设备
|
||||
- `type=1` 节点 → 名称匹配 warehouse_regions → 绑区或新建
|
||||
- `type=2` 节点 → Upsert Base_Device, RegionId=叶子区域
|
||||
- type=1 节点 → 名称匹配 warehouse_regions → 绑区或新建
|
||||
- type=2 节点 → Upsert base_device, DeviceGroup=IoT设备, ExtraData 存点位属性
|
||||
- 模式: FullReplace, 频率限制: 2次/秒
|
||||
|
||||
### Owl → 设备
|
||||
- `GET /devices` → Upsert Base_Device (Category=1, IsParent=1)
|
||||
- `GET /channels` → Upsert Base_Device (ParentDeviceId=NVR)
|
||||
- Owl 无区域概念 → RegionId=NULL, 管理员手动分配
|
||||
- GET /devices → Upsert base_device (DeviceGroup=视频设备, IsParent=是)
|
||||
- GET /channels → Upsert base_device (ParentDeviceId=NVR) + video_channel
|
||||
- Owl 无区域概念 → PointId=NULL, 管理员手动分配
|
||||
- 模式: Merge
|
||||
|
||||
### 反方向写回
|
||||
@@ -230,60 +329,62 @@ Controller 路径: `Controllers/Warehouse/Partial/DeviceManagerController.cs`
|
||||
|
||||
---
|
||||
|
||||
## 六、部署拓扑
|
||||
## 七、部署拓扑
|
||||
|
||||
```
|
||||
Docker: Owl+ZLM (:80,:5060) │ Docker: MC4.0 (:3000)
|
||||
│
|
||||
┌──────────────┴──────────────┐
|
||||
│ IntegrationGateway :5100 │
|
||||
└──────────────┬──────────────┘
|
||||
│
|
||||
┌──────────────┴──────────────┐
|
||||
│ VolPro.WebApi :9100 │
|
||||
│ MySQL / Redis │
|
||||
└──────────────┬──────────────┘
|
||||
│
|
||||
┌──────────────────┴──────────────────┐
|
||||
│ web.vite :9000 warehouse :9200 │
|
||||
└─────────────────────────────────────┘
|
||||
Docker: Owl+ZLM (:80) MC4.0-1 (:3000) MC4.0-2 (:3000)
|
||||
| | |
|
||||
+----------+-----------+-------------------+
|
||||
|
|
||||
+----------+-----------+
|
||||
| Gateway gw-31ku | Gateway gw-11ku
|
||||
| :5100 | :5101
|
||||
+----------+-----------+
|
||||
|
|
||||
+----------+-----------+
|
||||
| VolPro.WebApi |
|
||||
| :9100 |
|
||||
| MySQL / Redis |
|
||||
+----------+-----------+
|
||||
|
|
||||
+--------------+---------------+
|
||||
| web.vite :9000 warehouse :9200 |
|
||||
+--------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、实施路线
|
||||
## 八、实施路线
|
||||
|
||||
| 阶段 | 工期 | 内容 |
|
||||
|------|------|------|
|
||||
| Phase 0 | Day 1-2 | Gateway骨架 + Base_Device建表 + 代码生成 |
|
||||
| Phase 0 | Day 1-2 | Gateway骨架 + 6张表建表 + 代码生成 |
|
||||
| Phase 1 | Day 3-6 | OwlAdapter + 管理端视频设备页 |
|
||||
| Phase 2 | Day 7-11 | Mc4Adapter + IoT管理 + 区域树匹配 + SignalR |
|
||||
| Phase 3 | Day 12-17 | warehouse端改造 + 全链路联调 |
|
||||
| Phase 4 | Day 18-20 | 验证 + 缓冲 |
|
||||
|
||||
**总计: 18-20 个工作日**
|
||||
总计: 18-20 个工作日
|
||||
|
||||
---
|
||||
|
||||
## 八、新增整合流程
|
||||
## 九、新增整合流程
|
||||
|
||||
以接入「海康门禁」为例：
|
||||
1. 新建 `IntegrationGateway.Adapters.HikvisionAccess` 项目
|
||||
2. 实现 `IHasFlatDevices + IHasAlarms`
|
||||
3. 注册到 Host
|
||||
4. 前端新增 `AccessDeviceActions.vue` (~80行)
|
||||
5. DeviceTable.vue 加 `v-else-if (Category===3)`
|
||||
6. Vol.Pro 后端零改动
|
||||
|
||||
**总工作量: 1-2 天**
|
||||
1. 新建 IntegrationGateway.Adapters.HikvisionAccess 项目
|
||||
2. 实现 IHasFlatDevices + IHasAlarms → 设备同步时填充 DeviceGroup=门禁设备
|
||||
3. 管理端字典加一条"门禁设备"分组 → 按钮自动出现
|
||||
4. Vol.Pro 同步接口零改动（ExtraData 承载门禁字段）
|
||||
5. 前端新增 AccessDeviceActions.vue (~80行)
|
||||
总工作量: 1-2 天
|
||||
|
||||
---
|
||||
|
||||
## 九、代码组织规范
|
||||
## 十、代码组织规范
|
||||
|
||||
| 代码类型 | 路径 | 被覆盖? |
|
||||
|----------|------|:---:|
|
||||
| 第三方对接 | IntegrationGateway/ | ❌ |
|
||||
| 第三方对接 | gateway/ | ❌ |
|
||||
| 扩展Controller | Controllers/*/Partial/ | ❌ |
|
||||
| Entity扩展 | DomainModels/*/partial/ | ❌ |
|
||||
| 前端业务逻辑 | extension/warehouse/*.jsx | ❌ |
|
||||
@@ -292,5 +393,4 @@ Docker: Owl+ZLM (:80,:5060) │ Docker: MC4.0 (:3000)
|
||||
|
||||
---
|
||||
|
||||
> **文档结束**
|
||||
> **取代**: Vol.Pro_MC4.0_整合方案_v1.0、Vol.Pro_Owl_ZLMediaKit_整合方案_v1.0、Vol.Pro_统一设备管理_区域树与地图绑定方案_v1.0、Vol.Pro_整合项目_实施方案_v1.0
|
||||
> 取代: V1.0 系列所有整合方案文档
|
||||
|
||||
@@ -329,71 +329,38 @@ public async Task SyncDevices(string nodeCode, List<StandardDevice> devices)
|
||||
|
||||
---
|
||||
|
||||
## 五、管理端设备操作集成
|
||||
|
||||
> **设计决策**: 不再需要独立的设备管理页面。Vol.Pro 框架自带三级主从表显示能力（warehouse_regions → warehouse_devicepoint → base_device），可直接在框架生成的 base_device 列表页面中嵌入操作按钮，按 DeviceGroup 动态渲染。
|
||||
## 五、管理端统一设备页面
|
||||
|
||||
### 5.1 操作按钮矩阵
|
||||
|
||||
| DeviceGroup | 操作按钮 | 说明 |
|
||||
|:---:|------|------|
|
||||
| 视频设备 | 实时预览 / 云台控制(仅方向键) / 查看回放 / 获取快照 / 同步通道 | 全部通过网关 B 组接口代理到 Owl |
|
||||
| IoT设备 | 查看实时数据 / 设备控制 / 刷新点位 / 查看告警 | 通过网关 B4/B5 代理到 MC4.0 |
|
||||
| 门禁设备 | 远程开门 / 查看记录 / 查看告警 | Phase 3 接入海康ISC后启用 |
|
||||
| 道闸设备 | 抬杆 / 落杆 / 查看记录 | Phase 3 接入 |
|
||||
| 报警设备 | 查看告警 / 布防撤防 | Phase 3 接入 |
|
||||
| DeviceGroup | 操作按钮 |
|
||||
|:---:|------|
|
||||
| 视频设备 | 实时预览 / 云台控制(仅方向键) / 查看回放 / 获取快照 / 同步通道 |
|
||||
| IoT设备 | 查看实时数据 / 设备控制 / 刷新点位 / 查看告警 |
|
||||
| 门禁设备 | 远程开门 / 查看记录 / 查看告警 |
|
||||
| 道闸设备 | 抬杆 / 落杆 / 查看记录 |
|
||||
| 报警设备 | 查看告警 / 布防撤防 |
|
||||
|
||||
### 5.2 前端按钮嵌入方案
|
||||
|
||||
框架生成的 base_device 列表页面的"操作"列默认只有"编辑/删除"。在 **base_deviceController Partial** 中扩展前端分组逻辑，替换默认操作列为自定义渲染。
|
||||
### 5.2 前端按钮路由
|
||||
|
||||
```javascript
|
||||
// web.vite/src/extension/warehouse/base_device.jsx 或 views/warehouse/base_device/components/ActionColumn.vue
|
||||
const actionMap = {
|
||||
'视频设备': VideoDeviceActions, // 实时预览/云台/回放/快照/同步通道
|
||||
'IoT设备': IoTDeviceActions, // 实时数据/控制/刷新/告警
|
||||
'门禁设备': AccessDeviceActions, // 远程开门/记录/告警
|
||||
'道闸设备': BarrierDeviceActions,// 抬杆/落杆/记录
|
||||
'报警设备': AlarmDeviceActions, // 告警/布防撤防
|
||||
'视频设备': VideoDeviceActions,
|
||||
'IoT设备': IoTDeviceActions,
|
||||
'门禁设备': AccessDeviceActions,
|
||||
'道闸设备': BarrierDeviceActions,
|
||||
'报警设备': AlarmDeviceActions,
|
||||
}
|
||||
|
||||
// 操作列模板中根据 row.deviceGroup 动态渲染对应组件
|
||||
<template v-for="(row, idx) in data">
|
||||
<component :is="actionMap[row.deviceGroup] || DefaultActions" :row="row" />
|
||||
</template>
|
||||
```
|
||||
|
||||
**要点**:
|
||||
- 框架"操作"列通过自定义插槽替换，不修改框架生成的 Vue 文件本体
|
||||
- 组件放在 `views/warehouse/base_device/components/` 下，防代码生成覆盖
|
||||
- 五个分组组件各自独立（~80-150 行），新增分组仅加一个文件
|
||||
### 5.3 后端 API
|
||||
|
||||
### 5.3 前端操作组件清单
|
||||
|
||||
| 文件 | 大小 | 说明 |
|
||||
|------|:---:|------|
|
||||
| `VideoDeviceActions.vue` | ~120行 | 预览/云台/回放/快照按钮组，预览弹窗内嵌 Jessibuca 播放器（或 <video> 标签回退），云台仅 ↑↓←→+ZOOM+停止 |
|
||||
| `IoTDeviceActions.vue` | ~100行 | 实时数据表格弹窗（轮询 B4），控制面板（B5 写值），告警快捷入口 |
|
||||
| `AccessDeviceActions.vue` | ~60行 | 远程开门按钮 + 记录查询入口 |
|
||||
| `BarrierDeviceActions.vue` | ~60行 | 抬杆/落杆按钮 |
|
||||
| `AlarmDeviceActions.vue` | ~60行 | 告警列表 + 布防/撤防开关 |
|
||||
|
||||
### 5.4 后端操作 API
|
||||
|
||||
> 以下 API 由网关 B 组接口代理，Vol.Pro 前端不直连子系统，统一经网关中转。
|
||||
|
||||
| 接口 | 方法 | 说明 | 对应网关接口 |
|
||||
|------|:---:|------|------|
|
||||
| `/api/gateway/streams/{adapter}/{sourceId}/live` | GET | 获取实时流地址 | B6a |
|
||||
| `/api/gateway/streams/{adapter}/{sourceId}/playback?start=&end=` | GET | 获取回放地址 | B6b |
|
||||
| `/api/gateway/streams/{adapter}/{sourceId}/snapshot` | POST | 获取截图 | — |
|
||||
| `/api/gateway/streams/{adapter}/{sourceId}/ptz` | POST | 云台方向控制 | B7 |
|
||||
| `/api/gateway/realtime/{adapter}/{sourceId}` | GET | 获取实时点位值 | B4 |
|
||||
| `/api/gateway/realtime/{adapter}/control` | POST | 设备控制写值 | B5 |
|
||||
| `/api/gateway/alarms/{adapter}` | GET | 分页查询告警 | B8 |
|
||||
| `/api/gateway/alarms/{adapter}/{alarmId}/confirm` | POST | 确认告警 | B9 |
|
||||
|
||||
> Vol.Pro 前端直接请求网关（:5100），不经过 Vol.Pro 后端中转。跨域问题通过网关 CORS 或 nginx 反向代理解决。
|
||||
| 接口 | 说明 |
|
||||
|------|------|
|
||||
| GET /api/DeviceManager/GetRegionTree | 区域→点位→设备树 |
|
||||
| GET /api/DeviceManager/GetDevicesByPoint?pointId= | 点位下设备列表(含子设备) |
|
||||
| PUT /api/DeviceManager/{deviceId} | 更新设备(含地图绑定) |
|
||||
| POST /api/DeviceManager/SyncFromGateway | 手动同步 |
|
||||
|
||||
---
|
||||
|
||||
@@ -459,7 +426,7 @@ Docker: Owl+ZLM (:15123) MC4.0-1 (:3000) MC4.0-2 (:3000)
|
||||
| 阶段 | 工期 | 内容 |
|
||||
|------|------|------|
|
||||
| Phase 0 | Day 1-2 | Gateway骨架 + 6张表建表 + 代码生成 + 字典初始化 |
|
||||
| Phase 1 | Day 3-6 | OwlAdapter + base_device操作按钮组件(视频) + [可选]AI事件接入 |
|
||||
| Phase 1 | Day 3-6 | OwlAdapter + 管理端视频设备页 + [可选]AI事件接入 |
|
||||
| Phase 2 | Day 7-11 | Mc4Adapter + IoT管理 + 区域树匹配 + SignalR |
|
||||
| Phase 3 | Day 12-17 | warehouse端改造 + 全链路联调 |
|
||||
| Phase 4 | Day 18-20 | 验证 + 缓冲 |
|
||||
@@ -528,4 +495,3 @@ Phase 0 建表后需在 Vol.Pro 管理端创建以下数据字典：
|
||||
> - v1.0 (2026-04-29) — 初始 Owl+MC4 独立方案
|
||||
> - v2.0 (2026-05-16) — 整合 Gateway 架构 + 数据字典 + ExtraData JSON
|
||||
> - v3.0 (2026-05-16) — Owl/ZLMediaKit 双文档验证 + 14 项修正（P0/P1/P2 修复）
|
||||
> - v3.1 (2026-05-17) — 第五章修订：取消独立设备管理页面，改为框架主从表嵌入操作按钮
|
||||
|
||||
@@ -1,512 +0,0 @@
|
||||
# Vol.Pro 框架前后端改造方案
|
||||
|
||||
> **版本**: 1.0
|
||||
> **日期**: 2025-05-17
|
||||
> **基准**: SecMPS 整合方案 v3.1 + Vol.Pro 框架官方文档
|
||||
> **核心原则**: 所有改动必须在 Partial/extension 目录中，严禁修改框架生成代码
|
||||
|
||||
---
|
||||
|
||||
## 1. 改造总览
|
||||
|
||||
### 1.1 改造清单
|
||||
|
||||
| 层面 | 改造项 | 位置 | 是否破坏可升级性 |
|
||||
|------|--------|------|:---:|
|
||||
| 数据库 | 5 张新表 + 字典数据 | SQL 脚本 | ❌ |
|
||||
| 后端-Entity | 6 个实体 Partial 类 | `DomainModels/*/partial/` | ❌ |
|
||||
| 后端-Service | 6 个 Service Partial 类 | `Services/*/Partial/` | ❌ |
|
||||
| 后端-Controller | 3 个 Controller Partial 类 | `Controllers/*/Partial/` | ❌ |
|
||||
| 后端-Job | 3 个 Quartz 定时任务 | `Warehouse/Services/` | ❌ |
|
||||
| 后端-Config | 注册网关 HttpClient | `Startup.cs` | ⚠️ 需手动合并 |
|
||||
| 前端-主表 | 自定义操作列插槽 | `extension/warehouse/` | ❌ |
|
||||
| 前端-组件 | 5 个设备操作组件 | `views/warehouse/base_device/components/` | ❌ |
|
||||
| 网关 | GatewayClient HTTP 客户端 | `Warehouse/Services/` | ❌ |
|
||||
|
||||
### 1.2 框架扩展点总览
|
||||
|
||||
```
|
||||
Vol.Pro 框架约定:
|
||||
自动生成代码 (代码生成器覆盖) 自定义代码 (不被覆盖)
|
||||
───────────────────────────── ──────────────────────────
|
||||
Controllers/xxxController.cs Controllers/xxx/Partial/xxxController.cs
|
||||
Services/xxxService.cs Services/xxx/Partial/xxxService.cs
|
||||
IServices/IxxxService.cs IServices/xxx/Partial/IxxxService.cs
|
||||
Repositories/xxxRepository.cs (无需自定义)
|
||||
IRepositories/IxxxRepository.cs (无需自定义)
|
||||
DomainModels/xxx/xxx.cs DomainModels/xxx/partial/xxx.cs
|
||||
前端 views/xxx/xxx.vue extension/xxx.jsx + views/xxx/components/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 数据库改造
|
||||
|
||||
### 2.1 新增表
|
||||
|
||||
执行 `doc/db_init.sql`，创建 5 张表：
|
||||
|
||||
| 表名 | 说明 | 层级 |
|
||||
|------|------|------|
|
||||
| `gateway_nodes` | 网关节点 | 顶层 |
|
||||
| `base_device` | 统一设备主表 | 核心，AdapterCode+SourceId 联合唯一 |
|
||||
| `video_channel` | 视频通道扩展 | base_device 子表 |
|
||||
| `video_record` | 录像文件 | video_channel 子表 |
|
||||
| `iot_alarm` | 告警记录 | base_device 子表 |
|
||||
| `iot_devicedata` | 数据归档 | base_device 子表 |
|
||||
|
||||
### 2.2 字典初始化
|
||||
|
||||
Phase 0 需在 Vol.Pro 管理端 → 字典管理 中创建 8 组数据字典：
|
||||
|
||||
| 字典名称 | 字典编号 | 字典值 |
|
||||
|----------|:---:|------|
|
||||
| 设备种类 | — | 摄像机/硬盘录像机/温湿度变送器/空调控制器/... (18 项) |
|
||||
| 设备分组 | device_group | 视频设备/IoT设备/门禁设备/道闸设备/报警设备 |
|
||||
| 是否父设备 | — | 是/否 |
|
||||
| 在线状态 | — | 在线/离线 |
|
||||
| 启用状态 | — | 启用/禁用 |
|
||||
| 是否控制点 | — | 只读/可写 |
|
||||
| 告警等级 | — | 提示/普通/重要/紧急 |
|
||||
| 告警状态 | — | 未确认/已确认/已结束 |
|
||||
|
||||
### 2.3 区-点位-设备 三级关联
|
||||
|
||||
框架支持主从表三级显示。利用现有表关系：
|
||||
|
||||
```
|
||||
warehouse_regions (区域) ← 代码生成器已有
|
||||
└── warehouse_devicepoint (点位) ← 代码生成器已有
|
||||
└── base_device (设备) ← 新建，用 PointId 关联点位
|
||||
├── video_channel ← 新建子表
|
||||
├── iot_devicedata ← 新建子表
|
||||
└── iot_alarm ← 新建子表
|
||||
```
|
||||
|
||||
**关键**：代码生成器配置 base_device 的 `DetailTable` 属性，关联 video_channel/iot_devicedata/iot_alarm 作为子表，框架自动渲染主从表 Tab。
|
||||
|
||||
---
|
||||
|
||||
## 3. 后端改造
|
||||
|
||||
### 3.1 Entity 扩展（Partial 类）
|
||||
|
||||
**原则**：框架生成的 Entity 在 `DomainModels/device_manager/base_device.cs`，不可修改。仅在 `partial/` 中添加。
|
||||
|
||||
```
|
||||
VolPro.Entity/DomainModels/device_manager/partial/
|
||||
├── base_device.cs # 添加导航属性 + AdapterCode/SourceId 唯一约束注解
|
||||
├── gateway_nodes.cs # 网关特有业务属性
|
||||
├── video_channel.cs # 通道流信息缓存
|
||||
├── video_record.cs # (留空，框架生成即够用)
|
||||
├── iot_devicedata.cs # (留空)
|
||||
└── iot_alarm.cs # 告警确认/结束方法
|
||||
```
|
||||
|
||||
**base_device Partial 示例**：
|
||||
|
||||
```csharp
|
||||
namespace VolPro.Entity.DomainModels
|
||||
{
|
||||
public partial class base_device
|
||||
{
|
||||
// 导航属性（用于主从表）
|
||||
[Navigate(NavigateType.OneToOne, nameof(DeviceId), nameof(video_channel.DeviceId))]
|
||||
public video_channel? VideoChannel { get; set; }
|
||||
|
||||
[Navigate(NavigateType.OneToMany, nameof(DeviceId), nameof(iot_alarm.DeviceId))]
|
||||
public List<iot_alarm>? Alarms { get; set; }
|
||||
|
||||
[Navigate(NavigateType.OneToMany, nameof(DeviceId), nameof(iot_devicedata.DeviceId))]
|
||||
public List<iot_devicedata>? DeviceData { get; set; }
|
||||
|
||||
// 网关字段标识（供同步时判断哪些字段可覆盖）
|
||||
public static readonly HashSet<string> GatewayFields = new()
|
||||
{
|
||||
nameof(IsOnline), nameof(IsParent), nameof(ParentDeviceId),
|
||||
nameof(ExtraData), nameof(IpAddress), nameof(Port), nameof(LastSyncTime)
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 Service 扩展（Partial 类）
|
||||
|
||||
```
|
||||
Warehouse/Services/device_manager/Partial/
|
||||
├── base_deviceService.cs # GetRegionTree / GetDevicesByPoint / 字典查询辅助
|
||||
├── gateway_nodesService.cs # 网关注册/心跳/同步入口
|
||||
├── video_channelService.cs # (留空)
|
||||
├── video_recordService.cs # (留空)
|
||||
├── iot_devicedataService.cs # (留空)
|
||||
└── iot_alarmService.cs # (留空)
|
||||
```
|
||||
|
||||
**gateway_nodesService Partial**（核心同步入口）：
|
||||
|
||||
```csharp
|
||||
namespace Warehouse.Services
|
||||
{
|
||||
public partial class gateway_nodesService
|
||||
{
|
||||
private readonly IHttpContextAccessor _httpContextAccessor;
|
||||
private readonly Igateway_nodesRepository _repository;
|
||||
|
||||
[ActivatorUtilitiesConstructor]
|
||||
public gateway_nodesService(
|
||||
Igateway_nodesRepository dbRepository,
|
||||
IHttpContextAccessor httpContextAccessor
|
||||
) : base(dbRepository)
|
||||
{
|
||||
_httpContextAccessor = httpContextAccessor;
|
||||
_repository = dbRepository;
|
||||
}
|
||||
|
||||
// 网关注册 (Upsert) — 被 Controller A1 调用
|
||||
public async Task<gateway_nodes> RegisterNodeAsync(string nodeCode, string token, string adapterTypes, string baseUrl)
|
||||
{
|
||||
// 实现: Upsert 逻辑
|
||||
}
|
||||
|
||||
// 心跳更新 — 被 Controller A2 调用
|
||||
public async Task UpdateHeartbeatAsync(string nodeCode, string token)
|
||||
{
|
||||
// 实现: 更新 LastHeartbeat + IsOnline
|
||||
}
|
||||
|
||||
// 设备同步 — 被 Controller A3 调用
|
||||
public async Task<(int added, int updated)> SyncDevicesAsync(int gatewayNodeId, List<StandardDevice> devices)
|
||||
{
|
||||
// 实现: 字段分治 + parentSourceId 映射
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 Controller 扩展（Partial 类）
|
||||
|
||||
```
|
||||
VolPro.WebApi/Controllers/Warehouse/Partial/
|
||||
├── base_deviceController.cs # GetRegionTree / GetDevicesByPoint / 操作代理
|
||||
├── gateway_nodesController.cs # A1-A4 网关 API
|
||||
├── video_channelController.cs # (留空)
|
||||
├── video_recordController.cs # (留空)
|
||||
├── iot_devicedataController.cs # (留空)
|
||||
└── iot_alarmController.cs # (留空)
|
||||
```
|
||||
|
||||
#### 3.3.1 gateway_nodesController（A 组 API）
|
||||
|
||||
**核心改造**：在框架生成的 `gateway_nodesController` 基础上，Partial 中添加 4 个不受权限控制的网关回调接口。
|
||||
|
||||
```csharp
|
||||
namespace Warehouse.Controllers
|
||||
{
|
||||
public partial class gateway_nodesController
|
||||
{
|
||||
private readonly IHttpContextAccessor _httpContextAccessor;
|
||||
|
||||
[ActivatorUtilitiesConstructor]
|
||||
public gateway_nodesController(
|
||||
Igateway_nodesService service,
|
||||
IHttpContextAccessor httpContextAccessor
|
||||
) : base(service)
|
||||
{
|
||||
_httpContextAccessor = httpContextAccessor;
|
||||
}
|
||||
|
||||
/// <summary>A1: 网关注册 (Upsert)</summary>
|
||||
[HttpPost, Route("/api/gateway/register"), AllowAnonymous]
|
||||
public async Task<IActionResult> RegisterGateway([FromBody] GatewayRegisterRequest req)
|
||||
{
|
||||
// 实现
|
||||
}
|
||||
|
||||
/// <summary>A2: 心跳</summary>
|
||||
[HttpPost, Route("/api/gateway/heartbeat"), AllowAnonymous]
|
||||
public async Task<IActionResult> GatewayHeartbeat([FromBody] GatewayHeartbeatRequest req)
|
||||
{
|
||||
// 实现
|
||||
}
|
||||
|
||||
/// <summary>A3: 设备数据同步 (字段分治)</summary>
|
||||
[HttpPost, Route("/api/gateway/sync/devices"), AllowAnonymous]
|
||||
public async Task<IActionResult> SyncDevices([FromBody] SyncDevicesRequest req)
|
||||
{
|
||||
// 实现
|
||||
}
|
||||
|
||||
/// <summary>A4: 告警同步</summary>
|
||||
[HttpPost, Route("/api/gateway/sync/alarms"), AllowAnonymous]
|
||||
public async Task<IActionResult> SyncAlarms([FromBody] SyncAlarmsRequest req)
|
||||
{
|
||||
// 实现
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**权限模型**：A 组接口加 `[AllowAnonymous]`，内部通过 `NodeToken` 二次认证。B 组接口走框架 JWT 权限。
|
||||
|
||||
#### 3.3.2 base_deviceController（B 组代理 + 设备树）
|
||||
|
||||
```csharp
|
||||
namespace Warehouse.Controllers
|
||||
{
|
||||
public partial class base_deviceController
|
||||
{
|
||||
/// <summary>区域→点位→设备树（管理端左侧树形控件）</summary>
|
||||
[HttpGet, Route("/api/DeviceManager/GetRegionTree")]
|
||||
public async Task<IActionResult> GetRegionTree()
|
||||
{
|
||||
// SELECT warehouse_regions JOIN warehouse_devicepoint → 树形结构
|
||||
// 每个点位下统计 base_device 数量
|
||||
}
|
||||
|
||||
/// <summary>点位下设备列表（含子设备）</summary>
|
||||
[HttpGet, Route("/api/DeviceManager/GetDevicesByPoint")]
|
||||
public async Task<IActionResult> GetDevicesByPoint(int pointId, int page = 1, int size = 20)
|
||||
{
|
||||
// SELECT base_device WHERE PointId = pointId
|
||||
// Include 子设备（ParentDeviceId）
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.4 网关 HTTP 客户端（GatewayClient）
|
||||
|
||||
```
|
||||
Warehouse/Services/GatewayClient.cs
|
||||
```
|
||||
|
||||
```csharp
|
||||
public class GatewayClient
|
||||
{
|
||||
private readonly IHttpClientFactory _httpFactory;
|
||||
private readonly IConfiguration _config;
|
||||
|
||||
public GatewayClient(IHttpClientFactory httpFactory, IConfiguration config)
|
||||
{
|
||||
_httpFactory = httpFactory;
|
||||
_config = config;
|
||||
}
|
||||
|
||||
/// <summary>调网关 B3: 手动触发全量同步</summary>
|
||||
public async Task TriggerFullSyncAsync(string baseUrl, string adapterTypes)
|
||||
{
|
||||
var http = _httpFactory.CreateClient();
|
||||
// POST {baseUrl}/api/gateway/devices/sync?adapter={adapterTypes}
|
||||
}
|
||||
|
||||
/// <summary>调网关 B4: 获取实时点位值</summary>
|
||||
public async Task<List<PointValue>> GetRealtimeAsync(string baseUrl, string adapter, string deviceId)
|
||||
{
|
||||
// GET {baseUrl}/api/gateway/realtime/{adapter}/{deviceId}
|
||||
}
|
||||
|
||||
/// <summary>调网关 B5: 设备控制</summary>
|
||||
public async Task ControlDeviceAsync(string baseUrl, string adapter, string deviceId, int pointIndex, double value)
|
||||
{
|
||||
// POST {baseUrl}/api/gateway/realtime/{adapter}/control
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.5 Quartz 定时任务
|
||||
|
||||
| Job | 触发器 | 职责 |
|
||||
|-----|:---:|------|
|
||||
| `SyncDevicesJob` | 每 5 分钟 | 遍历所有在线网关 → 调 GatewayClient.TriggerFullSyncAsync() |
|
||||
| `RealtimePollJob` | 每 10 秒 | 轮询 MC4.0 IoT 设备实时值 → 更新 iot_devicedata |
|
||||
| `HeartbeatMonitorJob` | 每 15 秒 | 扫描 gateway_nodes 心跳超时 → 标记离线 + 级联设备离线 |
|
||||
|
||||
**注册方式**：在 Vol.Pro 管理端 → Quartz 任务管理 → 新建任务，指定 Job 类全名。
|
||||
|
||||
### 3.6 Startup.cs 注册
|
||||
|
||||
```csharp
|
||||
// 在 Startup.cs 或 Program.cs 中注册
|
||||
builder.Services.AddHttpClient("VolPro", c =>
|
||||
{
|
||||
c.Timeout = TimeSpan.FromSeconds(30);
|
||||
});
|
||||
builder.Services.AddSingleton<GatewayClient>();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 前端改造
|
||||
|
||||
### 4.1 架构决策
|
||||
|
||||
| 方案 | 描述 | 是否破坏可升级性 |
|
||||
|------|------|:---:|
|
||||
| ❌ 修改生成的 .vue | 直接改 views/warehouse/base_device/ 下框架生成文件 | ✅ 破坏 |
|
||||
| ✅ extension + components | 通过扩展注入 + 自定义组件实现操作列 | ❌ 不破坏 |
|
||||
|
||||
### 4.2 自定义操作列插槽
|
||||
|
||||
框架生成的 base_device 列表页面默认操作列只有"编辑/删除"。通过 **前端扩展文件** 自定义替换：
|
||||
|
||||
```
|
||||
web.vite/src/extension/warehouse/base_device.jsx
|
||||
```
|
||||
|
||||
```javascript
|
||||
// 自定义操作列渲染
|
||||
import VideoDeviceActions from '@/views/warehouse/base_device/components/VideoDeviceActions.vue'
|
||||
import IoTDeviceActions from '@/views/warehouse/base_device/components/IoTDeviceActions.vue'
|
||||
|
||||
// 注册自定义组件
|
||||
export default {
|
||||
components: { VideoDeviceActions, IoTDeviceActions },
|
||||
|
||||
// 替换框架默认操作列
|
||||
slots: {
|
||||
// 操作列插槽
|
||||
'col-action': (h, { row }) => {
|
||||
const comp = row.deviceGroup === '视频设备' ? 'VideoDeviceActions'
|
||||
: row.deviceGroup === 'IoT设备' ? 'IoTDeviceActions'
|
||||
: null
|
||||
if (comp) return h(comp, { props: { row } })
|
||||
// fallback 到框架默认按钮
|
||||
return null
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4.3 组件目录
|
||||
|
||||
```
|
||||
web.vite/src/views/warehouse/base_device/components/
|
||||
├── VideoDeviceActions.vue # 实时预览/云台/回放/快照/同步通道
|
||||
├── IoTDeviceActions.vue # 实时数据/控制/刷新/告警
|
||||
├── AccessDeviceActions.vue # 远程开门 (Phase 3)
|
||||
├── BarrierDeviceActions.vue # 抬杆/落杆 (Phase 3)
|
||||
├── AlarmDeviceActions.vue # 告警/布防撤防 (Phase 3)
|
||||
├── DeviceLivePreview.vue # Jessibuca 播放器弹窗
|
||||
├── PtzControlPanel.vue # ↑↓←→+ZOOM+停止
|
||||
├── RealtimeDataPanel.vue # 实时点位值表格弹窗
|
||||
├── DeviceControlPanel.vue # 控制写值面板
|
||||
├── DeviceEditDialog.vue # 设备编辑弹窗 (扩展字段)
|
||||
└── MapBindingPanel.vue # VgoMap 模型绑定
|
||||
```
|
||||
|
||||
### 4.4 组件设计要点
|
||||
|
||||
**VideoDeviceActions.vue**（核心组件）：
|
||||
|
||||
```
|
||||
Props: row (base_device)
|
||||
按钮组:
|
||||
[实时预览] → 打开 DeviceLivePreview.vue 弹窗
|
||||
→ GET /api/gateway/streams/{adapterCode}/{sourceId}/live → 流地址
|
||||
→ 内嵌 Jessibuca 播放器（fallback: <video> 标签 + flv.js）
|
||||
|
||||
[云台控制] → 打开 PtzControlPanel.vue 弹窗
|
||||
→ POST /api/gateway/streams/{adapterCode}/{sourceId}/ptz
|
||||
→ 仅方向键: ↑↓←→ + ZOOM +/- + 停止
|
||||
→ mousedown 开始移动, mouseup 发送停止
|
||||
|
||||
[查看回放] → 打开录像时间轴弹窗
|
||||
→ GET /api/gateway/streams/{adapterCode}/{sourceId}/playback?start=&end=
|
||||
|
||||
[获取快照] → 下载快照图片
|
||||
|
||||
[同步通道] → 触发网关 B3 重新同步此 NVR 的通道
|
||||
|
||||
限制:
|
||||
- channel 设备显示前 4 个按钮（无"同步通道"）
|
||||
- NVR(IsParent=是) 显示全部 5 个按钮
|
||||
```
|
||||
|
||||
**IoTDeviceActions.vue**：
|
||||
|
||||
```
|
||||
[查看实时数据] → GET /api/gateway/realtime/{adapterCode}/{sourceId}
|
||||
→ 仪表盘或数值显示（温度/湿度/电压...）
|
||||
→ 5s 自动轮询
|
||||
|
||||
[设备控制] → 仅 isControlPoint=true 的设备显示
|
||||
→ 空调温度设定/开关/模式切换
|
||||
|
||||
[刷新点位] → 强制刷新当前点位所有设备数据
|
||||
|
||||
[查看告警] → GET /api/gateway/alarms/{adapterCode}
|
||||
→ 跳转或内嵌告警列表
|
||||
```
|
||||
|
||||
### 4.5 API 封装
|
||||
|
||||
```
|
||||
web.vite/src/api/deviceManager.js # (已存在于框架中)
|
||||
web.vite/src/api/gateway.js # 新增：网关 B 组接口封装
|
||||
```
|
||||
|
||||
```javascript
|
||||
// gateway.js
|
||||
import request from '@/uitils/request'
|
||||
|
||||
// 基础: 直连网关
|
||||
const gwBase = 'http://localhost:5100/api/gateway'
|
||||
|
||||
export const getStreamUrl = (adapter, deviceId) =>
|
||||
request({ url: `${gwBase}/streams/${adapter}/${deviceId}/live`, method: 'get' })
|
||||
|
||||
export const ptzControl = (adapter, deviceId, direction, speed = 0.5) =>
|
||||
request({ url: `${gwBase}/streams/${adapter}/${deviceId}/ptz`, method: 'post', data: { direction, speed } })
|
||||
|
||||
export const getRealtime = (adapter, deviceId) =>
|
||||
request({ url: `${gwBase}/realtime/${adapter}/${deviceId}`, method: 'get' })
|
||||
|
||||
export const controlDevice = (adapter, deviceId, pointIndex, value) =>
|
||||
request({ url: `${gwBase}/realtime/${adapter}/control`, method: 'post', data: { deviceId, pointIndex, value } })
|
||||
|
||||
export const getAlarms = (adapter, params) =>
|
||||
request({ url: `${gwBase}/alarms/${adapter}`, method: 'get', params })
|
||||
|
||||
export const confirmAlarm = (adapter, alarmId) =>
|
||||
request({ url: `${gwBase}/alarms/${adapter}/${alarmId}/confirm`, method: 'post' })
|
||||
```
|
||||
|
||||
> 前端直连网关（:5100），跨域问题通过 Vol.Pro nginx 反向代理 `/api/gateway/*` → `http://localhost:5100` 解决，或网关配置 CORS。
|
||||
|
||||
---
|
||||
|
||||
## 5. 可升级性保障清单
|
||||
|
||||
| 检查项 | 状态 |
|
||||
|--------|:---:|
|
||||
| 不修改框架生成的 C# 基础类 | ✅ |
|
||||
| 所有自定义代码在 Partial 目录 | ✅ |
|
||||
| 不修改框架生成的 .vue 文件 | ✅ |
|
||||
| 前端业务逻辑在 extension 目录 | ✅ |
|
||||
| 新增组件在 views/xxx/components/ 下 | ✅ |
|
||||
| 不修改框架 NuGet 包版本 | ✅ |
|
||||
| 网关调用通过独立 GatewayClient 类 | ✅ |
|
||||
| A 组 API 用 `[AllowAnonymous]` + Token 二次认证 | ✅ |
|
||||
| Dictionary/Entity 属性通过代码生成器配置，不手写 | ✅ |
|
||||
| Startup.cs 注册仅用 `AddHttpClient`/`AddSingleton` | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## 6. 实施顺序
|
||||
|
||||
| 步骤 | 内容 | 依赖 |
|
||||
|:---:|------|------|
|
||||
| 1 | 代码生成器生成 device_manager 模块 6 张表 | Phase 0 |
|
||||
| 2 | 创建 Entity Partial 类 | 步骤 1 |
|
||||
| 3 | 创建 Service Partial 类 | 步骤 1 |
|
||||
| 4 | 创建 Controller Partial 类 (A1-A4 + GetRegionTree) | 步骤 3 |
|
||||
| 5 | 注册 GatewayClient + HttpClient | 步骤 4 |
|
||||
| 6 | 创建 Quartz Job (3 个) | 步骤 5 |
|
||||
| 7 | 创建前端组件 (5 个按钮组 + 5 个弹窗) | 步骤 4 |
|
||||
| 8 | 编写 extension/warehouse/base_device.jsx | 步骤 7 |
|
||||
| 9 | nginx 配置网关反向代理 | 步骤 8 |
|
||||
|
||||
---
|
||||
|
||||
> **版本历史**:
|
||||
> - v1.0 (2025-05-17) — 初版，基于整合方案 v3.1 + Vol.Pro 框架规范
|
||||
@@ -1,260 +0,0 @@
|
||||
# Vol.Pro 框架前后端改造 — 任务清单
|
||||
|
||||
> **基准文档**: VolPro框架改造方案 v1.0
|
||||
> **分支**: phase/0-infrastructure
|
||||
> **原则**: 所有改动在 Partial/extension 目录，严禁修改框架生成文件
|
||||
|
||||
---
|
||||
|
||||
## Phase V0: 数据库与代码生成（预计 0.5 天）
|
||||
|
||||
### V0.1 建表
|
||||
- [ ] 在 SQL Server 执行 `doc/db_init.sql`，创建 6 张表：
|
||||
- `gateway_nodes`（网关节点）
|
||||
- `base_device`（统一设备主表，AdapterCode+SourceId 联合主键）
|
||||
- `video_channel`（视频通道扩展）
|
||||
- `video_record`（录像文件）
|
||||
- `iot_alarm`（告警记录）
|
||||
- `iot_devicedata`（数据归档）
|
||||
|
||||
### V0.2 字典初始化
|
||||
- [ ] 在 Vol.Pro 管理端 → 字典管理，创建 8 组数据字典：
|
||||
- 设备分组：视频设备/IoT设备/门禁设备/道闸设备/报警设备
|
||||
- 设备种类：摄像机/硬盘录像机/温湿度变送器/空调控制器/...（18 项）
|
||||
- 在线状态：在线/离线
|
||||
- 启用状态：启用/禁用
|
||||
- 是否父设备：是/否
|
||||
- 是否控制点：只读/可写
|
||||
- 告警等级：提示/普通/重要/紧急
|
||||
- 告警状态：未确认/已确认/已结束
|
||||
|
||||
### V0.3 代码生成
|
||||
- [ ] 在 Vol.Pro 代码生成器中选择 `device_manager` 数据源，生成 6 张表的全套代码：
|
||||
- `VolPro.Entity/DomainModels/device_manager/` — 6 个 Entity
|
||||
- `Warehouse/IRepositories/device_manager/` — 6 个 Repository 接口
|
||||
- `Warehouse/Repositories/device_manager/` — 6 个 Repository 实现
|
||||
- `Warehouse/IServices/device_manager/` — 6 个 Service 接口 + 6 个 Partial 接口
|
||||
- `Warehouse/Services/device_manager/` — 6 个 Service 实现 + 6 个 Partial Service
|
||||
- `VolPro.WebApi/Controllers/Warehouse/` — 6 个 Controller
|
||||
|
||||
### V0.4 配置主从表
|
||||
- [ ] 代码生成器配置 base_device 的 DetailTable：
|
||||
- 关联 video_channel（DeviceId=DeviceId）
|
||||
- 关联 iot_devicedata（DeviceId=DeviceId）
|
||||
- 关联 iot_alarm（DeviceId=DeviceId）
|
||||
- [ ] 代码生成器配置 base_device 的 ParentId 自引用字段（ParentDeviceId）
|
||||
|
||||
### V0.5 构建验证
|
||||
- [ ] VS 编译 Vol.Pro 解决方案，确认 0 错误
|
||||
- [ ] 管理端访问 base_device 页面 → 框架默认主从表三 Tab 渲染正常
|
||||
|
||||
> **V0 提交点**: `PhaseV0_db_codegen — 6 张表建表 + 字典 + 代码生成完毕，框架默认页面可访问`
|
||||
|
||||
---
|
||||
|
||||
## Phase V1: Entity 与 Service 扩展（预计 0.5 天）
|
||||
|
||||
### V1.1 Entity Partial
|
||||
- [ ] 创建 `VolPro.Entity/DomainModels/device_manager/partial/base_device.cs`
|
||||
- 添加导航属性：VideoChannel、Alarms、DeviceData
|
||||
- 添加网关字段白名单常量 `GatewayFields`
|
||||
- [ ] 创建 `VolPro.Entity/DomainModels/device_manager/partial/gateway_nodes.cs`
|
||||
- 添加 `AdapterList` 属性（从 AdapterTypes 逗号分隔解析）
|
||||
- [ ] 其他 4 个 Entity Partial 留空（框架生成即够用）
|
||||
|
||||
### V1.2 Service Partial — gateway_nodesService
|
||||
- [ ] 编辑 `Warehouse/Services/device_manager/Partial/gateway_nodesService.cs`
|
||||
- 注入 `Igateway_nodesRepository` + `IHttpContextAccessor`（`[ActivatorUtilitiesConstructor]`）
|
||||
- 实现 `RegisterNodeAsync(nodeCode, token, adapterTypes, baseUrl)` — Upsert 逻辑
|
||||
- 实现 `UpdateHeartbeatAsync(nodeCode, token)` — 更新心跳
|
||||
- 实现 `SyncDevicesAsync(gatewayNodeId, List<StandardDevice>)` — 字段分治 + parentSourceId 映射
|
||||
|
||||
### V1.3 Service Partial — base_deviceService
|
||||
- [ ] 编辑 `Warehouse/Services/device_manager/Partial/base_deviceService.cs`
|
||||
- 注入 `Ibase_deviceRepository`
|
||||
- 实现 `GetDevicesByGatewayNodeAsync(gatewayNodeId)` — 网关注册时返回设备列表
|
||||
- 实现 `UpsertDeviceAsync(StandardDevice, gatewayNodeId, existingIds)` — 字段分治
|
||||
|
||||
### V1.4 Service Partial — iot_alarmService
|
||||
- [ ] 编辑 `Warehouse/Services/device_manager/Partial/iot_alarmService.cs`
|
||||
- 注入 `Iiot_alarmRepository`
|
||||
- 实现 `UpsertAlarmAsync(StandardAlarm)` — SourceAlarmId 去重
|
||||
|
||||
### V1.5 构建验证
|
||||
- [ ] VS 编译 → 0 错误
|
||||
|
||||
> **V1 提交点**: `PhaseV1_entity_service — Entity 导航属性 + Service 同步方法全部就绪`
|
||||
|
||||
---
|
||||
|
||||
## Phase V2: Controller 扩展（预计 1 天）
|
||||
|
||||
### V2.1 gateway_nodesController — A1 网关注册
|
||||
- [ ] 编辑 `Controllers/Warehouse/Partial/gateway_nodesController.cs`
|
||||
- 添加 `[HttpPost, Route("/api/gateway/register"), AllowAnonymous]`
|
||||
- 认证：NodeToken 验证
|
||||
- Upsert：存在则更新 AdapterTypes/BaseUrl/IsOnline，不存在且 Token 有效则 Insert
|
||||
- 返回：`{ nodeId, devices }` — 当前网关的顶层设备列表
|
||||
|
||||
### V2.2 gateway_nodesController — A2 心跳
|
||||
- [ ] 添加 `[HttpPost, Route("/api/gateway/heartbeat"), AllowAnonymous]`
|
||||
- 认证：NodeToken
|
||||
- 更新：IsOnline="在线" + LastHeartbeat=now
|
||||
- 返回：`{ status: "ok", serverTime }`
|
||||
|
||||
### V2.3 gateway_nodesController — A3 设备同步
|
||||
- [ ] 添加 `[HttpPost, Route("/api/gateway/sync/devices"), AllowAnonymous]`
|
||||
- 认证：NodeToken
|
||||
- 批量查已有 DeviceId 映射表
|
||||
- 遍历设备：字段分治写入（首次全量，后续仅网关字段）
|
||||
- parentSourceId → ParentDeviceId 解析
|
||||
- 返回：`{ added, updated, removed }`
|
||||
|
||||
### V2.4 gateway_nodesController — A4 告警同步
|
||||
- [ ] 添加 `[HttpPost, Route("/api/gateway/sync/alarms"), AllowAnonymous]`
|
||||
- 认证：NodeToken
|
||||
- 批量查 deviceSourceId → DeviceId 映射
|
||||
- SourceAlarmId 去重
|
||||
- 写入 iot_alarm，State="未确认"
|
||||
- 返回：`{ added }`
|
||||
|
||||
### V2.5 base_deviceController — 设备树
|
||||
- [ ] 编辑 `Controllers/Warehouse/Partial/base_deviceController.cs`
|
||||
- [ ] 添加 `[HttpGet, Route("/api/DeviceManager/GetRegionTree")]`
|
||||
- 查询：warehouse_regions JOIN warehouse_devicepoint
|
||||
- 构建树形结构（region → point，含 deviceCount）
|
||||
- 返回：`[{ id, label, type, children, deviceCount }]`
|
||||
- [ ] 添加 `[HttpGet, Route("/api/DeviceManager/GetDevicesByPoint")]`
|
||||
- 查询：base_device WHERE PointId=pointId（含子设备递归）
|
||||
- 分页返回：`{ items, total }`
|
||||
|
||||
### V2.6 权限配置
|
||||
- [ ] A1-A4 接口加 `[AllowAnonymous]`（内部 Token 二次认证）
|
||||
- [ ] GetRegionTree/GetDevicesByPoint 走框架 JWT 权限
|
||||
|
||||
### V2.7 构建验证
|
||||
- [ ] VS 编译 → 0 错误
|
||||
- [ ] Postman 测试 A1-A4（Mock Token）
|
||||
- [ ] 管理端访问 GetRegionTree → 返回 JSON
|
||||
|
||||
> **V2 提交点**: `PhaseV2_controller — 6 个 API 全部就绪，A1-A4 AllowAnonymous，设备树可查`
|
||||
|
||||
---
|
||||
|
||||
## Phase V3: 基础设施与定时任务（预计 0.5 天）
|
||||
|
||||
### V3.1 GatewayClient
|
||||
- [ ] 创建 `Warehouse/Services/GatewayClient.cs`
|
||||
- 实现 `TriggerFullSyncAsync(baseUrl, adapterTypes)` — 调网关 B3
|
||||
- 实现 `GetRealtimeAsync(baseUrl, adapter, deviceId)` — 调网关 B4
|
||||
- 实现 `ControlDeviceAsync(baseUrl, adapter, deviceId, pointIndex, value)` — 调网关 B5
|
||||
|
||||
### V3.2 Quartz Job — SyncDevicesJob
|
||||
- [ ] 创建 `Warehouse/Services/SyncDevicesJob.cs`
|
||||
- 实现 `IJob` 接口
|
||||
- 遍历 `gateway_nodes WHERE IsOnline=在线 AND Enable=启用`
|
||||
- 逐个调 `GatewayClient.TriggerFullSyncAsync`
|
||||
|
||||
### V3.3 Quartz Job — HeartbeatMonitorJob
|
||||
- [ ] 创建 `Warehouse/Services/HeartbeatMonitorJob.cs`
|
||||
- 扫描心跳超时 30s 的网关 → 标记离线
|
||||
- 级联：`base_device WHERE GatewayNodeId=离线节点Id → IsOnline=离线`
|
||||
|
||||
### V3.4 Quartz Job — RealtimePollJob（Phase 2）
|
||||
- [ ] 创建 `Warehouse/Services/RealtimePollJob.cs`（骨架，Phase 2 完善）
|
||||
|
||||
### V3.5 Startup.cs 注册
|
||||
- [ ] 注册 `IHttpClientFactory`（Named: "VolPro"）
|
||||
- [ ] 注册 `GatewayClient` 为 Singleton
|
||||
- [ ] 确认 Quartz Job 在管理端可配置（JobDataMap 传入 ServiceProvider）
|
||||
|
||||
### V3.6 Job 注册
|
||||
- [ ] 在 Vol.Pro 管理端 → Quartz 管理 → 新建 3 个 Job：
|
||||
- SyncDevicesJob：Cron "0 */5 * * * ?"
|
||||
- HeartbeatMonitorJob：Cron "0/15 * * * * ?"
|
||||
- RealtimePollJob：Cron "0/10 * * * * ?"
|
||||
|
||||
### V3.7 构建验证
|
||||
- [ ] VS 编译 → 0 错误
|
||||
- [ ] GatewayClient 可通过 Swagger 测试
|
||||
|
||||
> **V3 提交点**: `PhaseV3_infrastructure — GatewayClient + 3 Job + Startup 注册完毕`
|
||||
|
||||
---
|
||||
|
||||
## Phase V4: 前端改造（预计 1.5 天）
|
||||
|
||||
### V4.1 目录创建
|
||||
- [ ] 创建 `web.vite/src/views/warehouse/base_device/components/` 目录
|
||||
- [ ] 创建 `web.vite/src/extension/warehouse/` 目录
|
||||
- [ ] 创建 `web.vite/src/api/gateway.js` — 网关 B 组 API 封装
|
||||
|
||||
### V4.2 gateway.js API 封装
|
||||
- [ ] `getStreamUrl(adapter, deviceId)` → GET 流地址
|
||||
- [ ] `ptzControl(adapter, deviceId, direction)` → POST 云台控制
|
||||
- [ ] `getRealtime(adapter, deviceId)` → GET 实时点值
|
||||
- [ ] `controlDevice(adapter, deviceId, pointIndex, value)` → POST 控制
|
||||
- [ ] `getAlarms(adapter, params)` → GET 告警列表
|
||||
- [ ] `confirmAlarm(adapter, alarmId)` → POST 告警确认
|
||||
|
||||
### V4.3 视频操作组件
|
||||
- [ ] 创建 `VideoDeviceActions.vue` — 按钮组（预览/云台/回放/快照/同步通道）
|
||||
- [ ] 创建 `DeviceLivePreview.vue` — Jessibuca 播放器弹窗（<video> 回退）
|
||||
- 调 `getStreamUrl` → 获取 WS-FLV/HLS 地址
|
||||
- [ ] 创建 `PtzControlPanel.vue` — 方向键面板（↑↓←→+ZOOM+停止）
|
||||
- mousedown 开始移动，mouseup 停止
|
||||
|
||||
### V4.4 IoT 操作组件
|
||||
- [ ] 创建 `IoTDeviceActions.vue` — 按钮组（实时数据/控制/刷新/告警）
|
||||
- [ ] 创建 `RealtimeDataPanel.vue` — 实时数值弹窗（5s 自动轮询 B4）
|
||||
- [ ] 创建 `DeviceControlPanel.vue` — 控制写值面板（B5）
|
||||
|
||||
### V4.5 通用操作组件
|
||||
- [ ] 创建 `DeviceEditDialog.vue` — 设备编辑弹窗（管理员字段）
|
||||
- [ ] 创建 `MapBindingPanel.vue` — 地图模型绑定面板（模型ID/缩放/旋转）
|
||||
|
||||
### V4.6 未来组件（骨架）
|
||||
- [ ] 创建 `AccessDeviceActions.vue` — 门禁按钮组（远程开门）
|
||||
- [ ] 创建 `BarrierDeviceActions.vue` — 道闸按钮组（抬杆/落杆）
|
||||
- [ ] 创建 `AlarmDeviceActions.vue` — 报警按钮组（告警/布防撤防）
|
||||
|
||||
### V4.7 扩展注入
|
||||
- [ ] 创建 `web.vite/src/extension/warehouse/base_device.jsx`
|
||||
- 注册操作列插槽 `col-action`
|
||||
- 按 `row.deviceGroup` 动态渲染对应按钮组件
|
||||
- 视频设备 → VideoDeviceActions
|
||||
- IoT 设备 → IoTDeviceActions
|
||||
- 其他 → 框架默认编辑/删除按钮
|
||||
|
||||
### V4.8 构建验证
|
||||
- [ ] 前端 `npm run dev` 启动
|
||||
- [ ] 访问 base_device 页面 → 操作列根据 DeviceGroup 显示不同按钮
|
||||
- [ ] 点击"预览"→ 弹窗打开 → 获取流地址
|
||||
|
||||
> **V4 提交点**: `PhaseV4_frontend — 11 个组件 + extension 注入完成，操作列动态渲染`
|
||||
|
||||
---
|
||||
|
||||
## Phase V5: 联调验证（需网关+子系统就绪，预计 1 天）
|
||||
|
||||
### V5.1 端到端同步
|
||||
- [ ] 启动网关 → 调 A1 注册 → gateway_nodes 表新增记录
|
||||
- [ ] 网关调 A3 上送设备 → base_device 表有新设备
|
||||
- [ ] 管理端 base_device 页面 → 列表中显示新设备
|
||||
|
||||
### V5.2 视频操作
|
||||
- [ ] 视频设备行 → 点击"实时预览" → 弹窗播放 Owl 视频流
|
||||
- [ ] 视频设备行 → 云台方向键操作 → Owl PTZ 响应
|
||||
|
||||
### V5.3 IoT 操作
|
||||
- [ ] IoT 设备行 → 点击"实时数据" → 显示 MC4.0 温湿度值
|
||||
|
||||
### V5.4 告警确认
|
||||
- [ ] MC4.0 触发告警 → 网关 A4 上送 → iot_alarm 表新增
|
||||
- [ ] 管理端确认告警 → 通过 B9 写回 MC4.0
|
||||
|
||||
> **V5 提交点**: `PhaseV5_integration — 端到端同步 + 视频操作 + IoT 数据 + 告警确认全链路跑通`
|
||||
|
||||
---
|
||||
|
||||
> **总周期**: V0-V5 预计 5 个工作日（不含联调等待时间）
|
||||
@@ -1,703 +0,0 @@
|
||||
# IntegrationGateway 对接网关详细设计文档
|
||||
|
||||
> **版本**: 1.0
|
||||
> **日期**: 2025-05-17
|
||||
> **基准**: SecMPS 整合方案 v3.0
|
||||
> **作者**: 架构组
|
||||
|
||||
---
|
||||
|
||||
## 1. 概述
|
||||
|
||||
IntegrationGateway 是 SecMPS 整合方案 v3.0 的核心组件，定位为 Vol.Pro 管理端与各物联子系统之间的**协议适配中间层**。网关对外提供统一 REST API，对内通过适配器模式对接异构子系统，实现"适配一次，多处复用"。
|
||||
|
||||
### 1.1 设计目标
|
||||
|
||||
| 目标 | 度量 |
|
||||
|------|------|
|
||||
| 适配器热插拔 | 新增子系统不改网关核心，仅加 Adapter 项目 |
|
||||
| 故障隔离 | 任一适配器故障不影响其他适配器和网关注册 |
|
||||
| 无状态部署 | 网关不存数据库，配置仅 NodeCode/Token/VolProUrl |
|
||||
| 编译独立性 | `dotnet build` 0 错误，不依赖 Vol.Pro 运行时 |
|
||||
|
||||
### 1.2 技术栈
|
||||
|
||||
| 层面 | 选型 |
|
||||
|------|------|
|
||||
| 运行时 | .NET 8 |
|
||||
| Web 框架 | ASP.NET Core Minimal API |
|
||||
| HTTP 客户端 | IHttpClientFactory + SocketsHttpHandler |
|
||||
| 序列化 | System.Text.Json |
|
||||
| 容器化 | Docker (可选) |
|
||||
|
||||
---
|
||||
|
||||
## 2. 项目结构
|
||||
|
||||
```
|
||||
gateway/
|
||||
├── IntegrationGateway.sln
|
||||
└── src/
|
||||
├── IntegrationGateway.Core/ # 核心抽象（被所有项目引用）
|
||||
│ ├── Abstractions/ # 7 个能力接口
|
||||
│ │ ├── IHasOwnDeviceTree.cs
|
||||
│ │ ├── IHasFlatDevices.cs
|
||||
│ │ ├── IHasPoints.cs
|
||||
│ │ ├── IHasStreams.cs
|
||||
│ │ ├── IHasAlarms.cs
|
||||
│ │ ├── IHasRecordings.cs
|
||||
│ │ └── IAcceptsMetadataPush.cs
|
||||
│ ├── Models/ # 统一模型
|
||||
│ │ ├── StandardDevice.cs
|
||||
│ │ ├── StandardAlarm.cs
|
||||
│ │ ├── StandardRecording.cs
|
||||
│ │ ├── DeviceTreeNode.cs
|
||||
│ │ ├── PointValue.cs
|
||||
│ │ ├── StreamUrls.cs
|
||||
│ │ ├── PagedResult.cs
|
||||
│ │ ├── AdapterCapabilities.cs
|
||||
│ │ └── MetadataChangeSet.cs
|
||||
│ └── Infrastructure/ # 基础设施
|
||||
│ ├── AdapterRegistry.cs # 适配器注册中心
|
||||
│ ├── RateLimiter.cs # 令牌桶限流器
|
||||
│ └── GatewayClientFactory.cs # HTTP 客户端工厂
|
||||
│
|
||||
├── IntegrationGateway.Adapters.Owl/ # Owl 适配器
|
||||
│ ├── OwlAdapter.cs # 实现 IHasFlatDevices + IHasStreams
|
||||
│ └── OwlAuthHelper.cs # RSA 加密登录
|
||||
│
|
||||
├── IntegrationGateway.Adapters.MC4/ # MC4.0 适配器
|
||||
│ ├── Mc4Adapter.cs # 实现 IHasOwnDeviceTree + IHasPoints + IHasAlarms
|
||||
│ └── Mc4AuthHelper.cs # Token 认证
|
||||
│
|
||||
└── IntegrationGateway.Host/ # 宿主（启动项目）
|
||||
├── Program.cs # 路由注册 + 适配器初始化
|
||||
└── appsettings.json # 适配器连接配置
|
||||
```
|
||||
|
||||
### 2.1 依赖关系
|
||||
|
||||
```
|
||||
Host → Adapters.Owl → Core
|
||||
Host → Adapters.MC4 → Core
|
||||
Host → Core
|
||||
```
|
||||
|
||||
适配器项目不互相引用，Core 项目零外部依赖（仅 Microsoft.Extensions.*）。
|
||||
|
||||
---
|
||||
|
||||
## 3. 核心接口体系
|
||||
|
||||
### 3.1 接口总览
|
||||
|
||||
```csharp
|
||||
namespace IntegrationGateway.Core.Abstractions
|
||||
{
|
||||
/// <summary>所有适配器必须实现的基础接口</summary>
|
||||
public interface IGatewayAdapter
|
||||
{
|
||||
string AdapterCode { get; } // "Owl:main" / "MC4:31ku"
|
||||
string DisplayName { get; } // 人类可读名称
|
||||
AdapterCapabilities Capabilities { get; } // 能力声明
|
||||
Task InitializeAsync(); // 懒加载初始化
|
||||
Task<bool> HealthCheckAsync(); // 健康检查
|
||||
}
|
||||
|
||||
/// <summary>扁平设备列表（Owl/门禁/道闸）</summary>
|
||||
public interface IHasFlatDevices : IGatewayAdapter
|
||||
{
|
||||
Task<PagedResult<StandardDevice>> GetDevicesAsync(int page, int size, string? keyword);
|
||||
}
|
||||
|
||||
/// <summary>自有对象树（MC4.0）</summary>
|
||||
public interface IHasOwnDeviceTree : IGatewayAdapter
|
||||
{
|
||||
Task<List<DeviceTreeNode>> GetObjectTreeAsync();
|
||||
}
|
||||
|
||||
/// <summary>实时点位值（MC4.0 动环）</summary>
|
||||
public interface IHasPoints : IGatewayAdapter
|
||||
{
|
||||
Task<List<PointValue>> GetRealtimeValuesAsync(string sourceDeviceId);
|
||||
Task SetPointValueAsync(string sourceDeviceId, int pointIndex, double value);
|
||||
}
|
||||
|
||||
/// <summary>视频流（Owl）</summary>
|
||||
public interface IHasStreams : IGatewayAdapter
|
||||
{
|
||||
Task<StreamUrls> GetLiveUrlAsync(string channelId);
|
||||
Task<StreamUrls> GetPlaybackUrlAsync(string channelId, DateTime start, DateTime end);
|
||||
Task PtzControlAsync(string channelId, string direction, float speed);
|
||||
Task PtzStopAsync(string channelId);
|
||||
Task<StreamUrls> GetSnapshotAsync(string channelId);
|
||||
}
|
||||
|
||||
/// <summary>告警（MC4.0 + Owl AI可选）</summary>
|
||||
public interface IHasAlarms : IGatewayAdapter
|
||||
{
|
||||
Task<PagedResult<StandardAlarm>> GetAlarmsAsync(
|
||||
int page, int size, DateTime from, DateTime to,
|
||||
string? level = null, string? state = null);
|
||||
Task ConfirmAlarmAsync(string alarmId);
|
||||
Task EndAlarmAsync(string alarmId);
|
||||
}
|
||||
|
||||
/// <summary>录像回放（Owl）</summary>
|
||||
public interface IHasRecordings : IGatewayAdapter
|
||||
{
|
||||
Task<PagedResult<StandardRecording>> GetRecordingsAsync(
|
||||
string channelId, DateTime start, DateTime end, int page, int size);
|
||||
}
|
||||
|
||||
/// <summary>元数据回写（Owl 设备改名等）</summary>
|
||||
public interface IAcceptsMetadataPush : IGatewayAdapter
|
||||
{
|
||||
Task<MetadataPushResult> PushMetadataAsync(string sourceDeviceId, MetadataChangeSet changes);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 接口设计原则
|
||||
|
||||
- **显式优于隐式**：每个接口明确声明一种能力，适配器按需实现，网关通过 `is` 检查自动发现路由
|
||||
- **异步优先**：所有方法返回 `Task`/`Task<T>`，避免阻塞线程
|
||||
- **统一分页**：`PagedResult<T>` 统一 page/size 语义，适配器内部完成 skip/limit 转换
|
||||
- **弹性 Extra**：`Dictionary<string, object?>` 承载适配器特有属性，不污染核心模型
|
||||
|
||||
### 3.3 适配器能力矩阵
|
||||
|
||||
```
|
||||
Owl MC4.0 门禁(未来)
|
||||
IGatewayAdapter ✅ ✅ ✅
|
||||
IHasOwnDeviceTree - ✅ -
|
||||
IHasFlatDevices ✅ - ✅
|
||||
IHasPoints - ✅ -
|
||||
IHasStreams ✅ - -
|
||||
IHasAlarms ⚠️ ✅ ✅
|
||||
IHasRecordings ✅ - -
|
||||
IAcceptsMetadata ✅ - ⚠️
|
||||
```
|
||||
|
||||
### 3.4 接口扩展规则
|
||||
|
||||
新增子系统时：
|
||||
1. 如果现有接口能覆盖 → 直接实现对应接口，零网关改动
|
||||
2. 如果现有接口不覆盖 → Core 中新增接口（如 `IHasFaceRecognition`），不能改已有接口签名
|
||||
3. 新增能力接口后 → Controller 加一个 `if (adapter is INewFeature)` 分支即可
|
||||
|
||||
---
|
||||
|
||||
## 4. 统一模型设计
|
||||
|
||||
### 4.1 StandardDevice
|
||||
|
||||
```csharp
|
||||
public class StandardDevice
|
||||
{
|
||||
public int DeviceId { get; set; } // Vol.Pro 侧主键（同步后回填）
|
||||
public string AdapterCode { get; set; } = ""; // "Owl:main"
|
||||
public string SourceId { get; set; } = ""; // 子系统原始ID (GB28181编码 / MC4 sid)
|
||||
public string Name { get; set; } = ""; // 设备名称
|
||||
public string Category { get; set; } = ""; // 摄像机/温湿度变送器/...
|
||||
public string Group { get; set; } = ""; // 视频设备/IoT设备/...
|
||||
public bool IsParent { get; set; } // 是否有子设备
|
||||
public string? ParentSourceId { get; set; } // 父设备SourceId（层级关系）
|
||||
public bool IsOnline { get; set; } // 在线状态
|
||||
public string? IpAddress { get; set; } // IP地址
|
||||
public int? Port { get; set; } // 端口
|
||||
public Dictionary<string, object?>? Extra { get; set; } // 适配器扩展JSON
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 字段映射规则（字段分治）
|
||||
|
||||
| StandardDevice | base_device | 写入策略 |
|
||||
|:---|---|:---:|
|
||||
| Name | DeviceName | 仅首次 |
|
||||
| Category | DeviceCategory | 仅首次 |
|
||||
| Group | DeviceGroup | 仅首次 |
|
||||
| IsOnline | IsOnline | 每次覆盖 |
|
||||
| IsParent | IsParent | 每次覆盖 |
|
||||
| ParentSourceId | ParentDeviceId | 每次覆盖（解析映射） |
|
||||
| IpAddress | IpAddress | 每次覆盖 |
|
||||
| Port | Port | 每次覆盖 |
|
||||
| Extra | ExtraData | 每次覆盖 |
|
||||
| AdapterCode + SourceId | (AdapterCode, SourceId) | 联合唯一键 |
|
||||
|
||||
### 4.3 DeviceTreeNode（对象树）
|
||||
|
||||
```csharp
|
||||
public class DeviceTreeNode
|
||||
{
|
||||
public int Id { get; set; } // MC4.0 原始ID
|
||||
public string SourceId { get; set; } = ""; // 转换为 string 的源ID
|
||||
public string Name { get; set; } = ""; // 节点名称
|
||||
public int Type { get; set; } // 1=区域, 2=设备
|
||||
public int ObjectType { get; set; } // MC4.0 对象类型
|
||||
public string? Tag { get; set; } // 标签（温湿度/烟雾/门磁...）
|
||||
public Dictionary<string, object?>? Option { get; set; } // 扩展属性
|
||||
public List<DeviceTreeNode> Children { get; set; } = new();
|
||||
}
|
||||
```
|
||||
|
||||
### 4.4 PagedResult<T>
|
||||
|
||||
```csharp
|
||||
public class PagedResult<T>
|
||||
{
|
||||
public List<T> Items { get; set; } = new();
|
||||
public int Total { get; set; }
|
||||
public int Page => 0; // 由调用方设置
|
||||
public int Size => 0;
|
||||
}
|
||||
```
|
||||
|
||||
### 4.5 其他模型
|
||||
|
||||
```
|
||||
StreamUrls → { WsFlv, HttpFlv, Hls, WebRtc, Rtmp, Rtsp }
|
||||
StandardAlarm → { AlarmId, DeviceId, AdapterCode, Level, Title, Content, OccurTime, Status, ... }
|
||||
StandardRecording → { Id, ChannelId, StartedAt, EndedAt, Duration, FilePath, Size }
|
||||
PointValue → { SourceDeviceId, PointIndex, Value, UpdateTime, Interval }
|
||||
MetadataChangeSet → { Name?, Category?, Group?, Extra? }
|
||||
AdapterCapabilities → { HasObjectTree, HasPoints, HasStreams, HasAlarms, HasRecordings, AcceptsControl, AcceptsMetadataPush }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 基础设施设计
|
||||
|
||||
### 5.1 AdapterRegistry
|
||||
|
||||
```csharp
|
||||
public class AdapterRegistry
|
||||
{
|
||||
private readonly List<IGatewayAdapter> _adapters = new();
|
||||
|
||||
public void Register(IGatewayAdapter adapter) => _adapters.Add(adapter);
|
||||
|
||||
public async Task InitializeAllAsync()
|
||||
{
|
||||
// 并行初始化，单个失败不影响其他
|
||||
await Task.WhenAll(_adapters.Select(a => Task.Run(async () =>
|
||||
{
|
||||
try { await a.InitializeAsync(); }
|
||||
catch (Exception ex) { Log.Error($"Adapter {a.AdapterCode} init failed: {ex.Message}"); }
|
||||
})));
|
||||
}
|
||||
|
||||
public IReadOnlyList<IGatewayAdapter> All => _adapters.AsReadOnly();
|
||||
|
||||
public T? FindByCode<T>(string adapterCode) where T : class, IGatewayAdapter
|
||||
=> _adapters.FirstOrDefault(a => a.AdapterCode == adapterCode && a is T) as T;
|
||||
|
||||
public IGatewayAdapter? FindByCode(string adapterCode)
|
||||
=> _adapters.FirstOrDefault(a => a.AdapterCode == adapterCode);
|
||||
}
|
||||
```
|
||||
|
||||
**设计要点**：
|
||||
- 列表存储，O(1) 注册，O(n) 查找（n≤5，可接受）
|
||||
- 初始化失败不回滚，适配器标记为离线
|
||||
- 网关启动时通过 `POST /register` 上报 `AdapterTypes` 给 Vol.Pro
|
||||
|
||||
### 5.2 RateLimiter（令牌桶）
|
||||
|
||||
```csharp
|
||||
public class RateLimiter
|
||||
{
|
||||
private readonly SemaphoreSlim _semaphore;
|
||||
private readonly int _tokensPerSecond;
|
||||
|
||||
public RateLimiter(int tokensPerSecond)
|
||||
{
|
||||
_tokensPerSecond = tokensPerSecond;
|
||||
_semaphore = new SemaphoreSlim(tokensPerSecond, tokensPerSecond);
|
||||
}
|
||||
|
||||
public async Task WaitAsync(CancellationToken ct = default)
|
||||
{
|
||||
await _semaphore.WaitAsync(ct);
|
||||
_ = Task.Run(async () =>
|
||||
{
|
||||
await Task.Delay(1000 / _tokensPerSecond);
|
||||
_semaphore.Release();
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**配置策略**：
|
||||
| 适配器 | QPS 限制 | 原因 |
|
||||
|--------|:---:|------|
|
||||
| Owl | 5 | 按文档推荐 |
|
||||
| MC4.0 | 2 | MC4.0 API 限频 |
|
||||
|
||||
### 5.3 HttpClient 工厂
|
||||
|
||||
```csharp
|
||||
// Program.cs 注册
|
||||
builder.Services.AddHttpClient("VolPro", c =>
|
||||
{
|
||||
c.BaseAddress = new Uri("http://localhost:9100");
|
||||
c.DefaultRequestHeaders.Add("Accept", "application/json");
|
||||
c.Timeout = TimeSpan.FromSeconds(30);
|
||||
}).ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler
|
||||
{
|
||||
PooledConnectionLifetime = TimeSpan.FromMinutes(5),
|
||||
MaxConnectionsPerServer = 10
|
||||
});
|
||||
```
|
||||
|
||||
**策略**：
|
||||
- 命名 HttpClient（`"VolPro"` 用于调 Vol.Pro，适配器内部自行创建 AuthenticatedClient）
|
||||
- 连接池复用，5 分钟生命周期
|
||||
- 超时 30 秒，防止第三方 API 慢响应阻塞
|
||||
|
||||
---
|
||||
|
||||
## 6. 认证与安全
|
||||
|
||||
### 6.1 网关注册认证（A1-A4）
|
||||
|
||||
```
|
||||
网关持有: NodeCode + NodeToken（管理端分配）
|
||||
注册流程:
|
||||
1. 网关 → POST /api/gateway/register { nodeCode, token, ... }
|
||||
2. Vol.Pro 查询 gateway_nodes WHERE NodeCode = req.NodeCode
|
||||
- 存在 → 比对 NodeToken
|
||||
- 不存在 → NodeToken 验证通过后 Insert
|
||||
3. 认证失败 → 401
|
||||
4. 成功后返回 NodeId + 设备列表
|
||||
```
|
||||
|
||||
### 6.2 Owl 认证（RSA 加密）
|
||||
|
||||
```
|
||||
1. GET /login/key → 获取 RSA 公钥 (Base64)
|
||||
2. 用公钥加密 { username, password } → Base64
|
||||
3. POST /login { data: <Base64密文> } → 获取 JWT Token
|
||||
4. Token 有效期: 3 天
|
||||
5. 后续请求: Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**安全要点**：
|
||||
- Token 内存缓存，不落盘
|
||||
- Token 过期前 1 小时自动刷新（懒刷新策略）
|
||||
- 认证失败不清除缓存 → 重试 3 次后 `Invalidate()`
|
||||
|
||||
### 6.3 MC4.0 认证
|
||||
|
||||
```
|
||||
1. POST /api/central/auth/conf/get → 获取临时 Token
|
||||
2. Token 有效期: 8 小时（保守估计）
|
||||
3. 后续请求: header["token"] = <token>
|
||||
```
|
||||
|
||||
### 6.4 网关内部接口（B 组）
|
||||
|
||||
B 组接口供管理端或 Vol.Pro 内部调用，认证方式：
|
||||
- 内网部署：IP 白名单（Simple）
|
||||
- 外网部署：共享 Secret Key（HMAC 签名），Phase 4 实现
|
||||
|
||||
---
|
||||
|
||||
## 7. 路由设计
|
||||
|
||||
### 7.1 网关主动接口（调 Vol.Pro，不暴露给外部）
|
||||
|
||||
网关内部通过 `VolProClient` 调用，不在 Minimal API 中注册路由。
|
||||
|
||||
```
|
||||
POST {VolProBaseUrl}/api/gateway/register A1
|
||||
POST {VolProBaseUrl}/api/gateway/heartbeat A2
|
||||
POST {VolProBaseUrl}/api/gateway/sync/devices A3
|
||||
POST {VolProBaseUrl}/api/gateway/sync/alarms A4
|
||||
```
|
||||
|
||||
### 7.2 网关暴露接口（B 组，供管理端调用）
|
||||
|
||||
```csharp
|
||||
// Program.cs 路由注册伪代码
|
||||
app.MapGet("/api/gateway/health", async (AdapterRegistry reg) => {
|
||||
var results = await Task.WhenAll(reg.All.Select(async a => new {
|
||||
a.AdapterCode, a.DisplayName,
|
||||
Healthy = await a.HealthCheckAsync(),
|
||||
a.Capabilities
|
||||
}));
|
||||
return Results.Ok(results);
|
||||
});
|
||||
|
||||
app.MapGet("/api/gateway/devices", async (string adapter, int page, int size, string? keyword, AdapterRegistry reg) => {
|
||||
var a = reg.FindByCode<IHasFlatDevices>(adapter);
|
||||
if (a == null) return Results.NotFound();
|
||||
return Results.Ok(await a.GetDevicesAsync(page, size, keyword));
|
||||
});
|
||||
|
||||
app.MapGet("/api/gateway/tree", async (string adapter, AdapterRegistry reg) => {
|
||||
var a = reg.FindByCode<IHasOwnDeviceTree>(adapter);
|
||||
if (a == null) return Results.NotFound();
|
||||
return Results.Ok(await a.GetObjectTreeAsync());
|
||||
});
|
||||
|
||||
app.MapGet("/api/gateway/streams/{adapter}/{deviceId}/live", async (string adapter, string deviceId, AdapterRegistry reg) => {
|
||||
var a = reg.FindByCode<IHasStreams>(adapter);
|
||||
if (a == null) return Results.NotFound();
|
||||
return Results.Ok(await a.GetLiveUrlAsync(deviceId));
|
||||
});
|
||||
|
||||
app.MapPost("/api/gateway/streams/{adapter}/{deviceId}/ptz", async (string adapter, string deviceId, PtzRequest req, AdapterRegistry reg) => {
|
||||
var a = reg.FindByCode<IHasStreams>(adapter);
|
||||
if (a == null) return Results.NotFound();
|
||||
if (req.Action == "stop") await a.PtzStopAsync(deviceId);
|
||||
else await a.PtzControlAsync(deviceId, req.Direction, req.Speed);
|
||||
return Results.Ok();
|
||||
});
|
||||
|
||||
app.MapGet("/api/gateway/alarms/{adapter}", async (string adapter, int page, int size, DateTime from, DateTime to, AdapterRegistry reg) => {
|
||||
var a = reg.FindByCode<IHasAlarms>(adapter);
|
||||
if (a == null) return Results.NotFound();
|
||||
return Results.Ok(await a.GetAlarmsAsync(page, size, from, to));
|
||||
});
|
||||
|
||||
app.MapPost("/api/gateway/alarms/{adapter}/{alarmId}/confirm", async (string adapter, string alarmId, AdapterRegistry reg) => {
|
||||
var a = reg.FindByCode<IHasAlarms>(adapter);
|
||||
if (a == null) return Results.NotFound();
|
||||
await a.ConfirmAlarmAsync(alarmId);
|
||||
return Results.Ok();
|
||||
});
|
||||
|
||||
// ... 更多 B 组接口
|
||||
```
|
||||
|
||||
### 7.3 路由设计原则
|
||||
|
||||
- **适配器参数前置**：所有 B 组接口第一个路径参数都是 `{adapter}`，通过注册中心查找
|
||||
- **能力检查懒加载**：请求到达时才检查适配器是否实现对应接口
|
||||
- **404 语义**：适配器不存在或未实现对应能力 → 404（而非 500）
|
||||
- **统一错误格式**：`{ "error": "ADAPTER_NOT_FOUND", "message": "Adapter 'xxx' not found" }`
|
||||
|
||||
---
|
||||
|
||||
## 8. 同步流程设计
|
||||
|
||||
### 8.1 网关启动同步
|
||||
|
||||
```
|
||||
1. 网关启动 → 加载配置 (NodeCode, Token, VolProBaseUrl)
|
||||
2. 初始化适配器 (并行: Owl + MC4)
|
||||
3. POST /api/gateway/register → 获取 NodeId + 已有设备列表
|
||||
4. 按 AdapterCode 分流已有设备 → 适配器对比差异
|
||||
5. 各适配器发现子设备 → 构建 StandardDevice[] 列表
|
||||
6. POST /api/gateway/sync/devices → Vol.Pro Upsert 设备
|
||||
7. 开启 15s 心跳定时器
|
||||
```
|
||||
|
||||
### 8.2 手动全量同步（B3）
|
||||
|
||||
```
|
||||
管理端 → POST /api/gateway/devices/sync?adapter=MC4:31ku
|
||||
网关:
|
||||
1. 找到 Mc4Adapter
|
||||
2. (MC4) GetObjectTree() → 解析区域+设备 → StandardDevice[]
|
||||
3. (Owl) GetDevices() + GetChannels() → StandardDevice[]
|
||||
4. POST /api/gateway/sync/devices → Vol.Pro
|
||||
5. 返回 { added, updated, removed }
|
||||
```
|
||||
|
||||
### 8.3 MC4.0 同步（FullReplace 模式）
|
||||
|
||||
```
|
||||
MC4.0 对象树遍历:
|
||||
type=1 (区域) → 名称匹配 warehouse_regions → 新建或绑区
|
||||
type=2 (设备) → Upsert base_device
|
||||
- 首次写入: DeviceName/Category/Group/ExtraData 全量
|
||||
- 后续同步: 仅更新 IsOnline/ExtraData/ParentDeviceId
|
||||
type=2 子节点 → parentSourceId 解析 → ParentDeviceId
|
||||
```
|
||||
|
||||
### 8.4 Owl 同步（Merge 模式）
|
||||
|
||||
```
|
||||
Owl 设备列表遍历:
|
||||
GET /devices → NVR 设备 (IsParent=是, DeviceGroup=视频设备)
|
||||
GET /channels → 通道 (ParentDeviceId=NVR, IsParent=否)
|
||||
通道额外写 video_channel 扩展记录 (OwlStreamApp/OwlStreamName)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 错误处理
|
||||
|
||||
### 9.1 错误码规范
|
||||
|
||||
| HTTP 状态码 | error_code | 场景 |
|
||||
|:---:|------|------|
|
||||
| 200 | - | 正常 |
|
||||
| 400 | `INVALID_PARAMETER` | 参数缺失或格式错误 |
|
||||
| 401 | `UNAUTHORIZED` | Token 验证失败 |
|
||||
| 404 | `ADAPTER_NOT_FOUND` | 适配器不存在 |
|
||||
| 404 | `CAPABILITY_NOT_SUPPORTED` | 适配器未实现该能力 |
|
||||
| 502 | `UPSTREAM_ERROR` | 第三方 API 返回错误 |
|
||||
| 503 | `ADAPTER_OFFLINE` | 适配器健康检查失败 |
|
||||
| 504 | `UPSTREAM_TIMEOUT` | 第三方 API 超时 |
|
||||
| 500 | `INTERNAL_ERROR` | 网关内部错误 |
|
||||
|
||||
### 9.2 适配器日志
|
||||
|
||||
```csharp
|
||||
public void Log(string adapterCode, string operation, string detail, Exception? ex = null)
|
||||
{
|
||||
var level = ex != null ? "ERROR" : "INFO";
|
||||
var msg = $"[{DateTime.UtcNow:O}] [{level}] [{adapterCode}] {operation}: {detail}";
|
||||
if (ex != null) msg += $"\n{ex}";
|
||||
Console.WriteLine(msg);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. 配置管理
|
||||
|
||||
### 10.1 appsettings.json 结构
|
||||
|
||||
```json
|
||||
{
|
||||
"Logging": {
|
||||
"LogLevel": { "Default": "Information" }
|
||||
},
|
||||
"Owl": {
|
||||
"BaseUrl": "http://localhost:15123",
|
||||
"Username": "admin",
|
||||
"Password": "your_password"
|
||||
},
|
||||
"MC4": {
|
||||
"BaseUrl": "http://localhost:3000"
|
||||
},
|
||||
"Gateway": {
|
||||
"VolProBaseUrl": "http://localhost:9100",
|
||||
"NodeCode": "gw-31ku",
|
||||
"NodeToken": "xxxxxxxxxx",
|
||||
"HeartbeatIntervalSec": 15,
|
||||
"AdapterInitTimeoutSec": 30
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 10.2 环境变量覆盖（Docker 部署）
|
||||
|
||||
```bash
|
||||
GATEWAY__OWL__BASEURL=http://192.168.1.100:15123
|
||||
GATEWAY__OWL__PASSWORD=prod_password
|
||||
GATEWAY__GATEWAY__NODETOKEN=prod_token
|
||||
```
|
||||
|
||||
### 10.3 配置验证
|
||||
|
||||
启动时验证必填项：
|
||||
```
|
||||
Gateway.VolProBaseUrl ✓
|
||||
Gateway.NodeCode ✓ (长度 1-50)
|
||||
Gateway.NodeToken ✓ (长度 8-100)
|
||||
Owl.BaseUrl ✓ (格式 http(s)://...)
|
||||
Owl.Username ✓
|
||||
Owl.Password ✓
|
||||
MC4.BaseUrl ✓
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. 部署方案
|
||||
|
||||
### 11.1 单机部署
|
||||
|
||||
```bash
|
||||
cd gateway
|
||||
dotnet publish src/IntegrationGateway.Host -c Release -o publish
|
||||
cd publish
|
||||
./IntegrationGateway.Host --urls http://0.0.0.0:5100
|
||||
```
|
||||
|
||||
### 11.2 Docker 部署
|
||||
|
||||
```dockerfile
|
||||
FROM mcr.microsoft.com/dotnet/aspnet:8.0
|
||||
WORKDIR /app
|
||||
COPY publish/ .
|
||||
ENV ASPNETCORE_URLS=http://+:5100
|
||||
ENTRYPOINT ["dotnet", "IntegrationGateway.Host.dll"]
|
||||
```
|
||||
|
||||
### 11.3 双实例部署
|
||||
|
||||
```
|
||||
实例A: gw-31ku :5100 → MC4.0(31号库) + Owl(仓库视频)
|
||||
实例B: gw-11ku :5101 → MC4.0(11号库) + 海康ISC(门禁)
|
||||
```
|
||||
|
||||
### 11.4 运维命令
|
||||
|
||||
```bash
|
||||
# 健康检查
|
||||
curl http://localhost:5100/api/gateway/health
|
||||
|
||||
# 手动同步
|
||||
curl -X POST "http://localhost:5100/api/gateway/devices/sync?adapter=MC4:31ku"
|
||||
|
||||
# 查看日志
|
||||
docker logs -f integration-gateway
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. 性能指标
|
||||
|
||||
| 指标 | 目标值 | 说明 |
|
||||
|------|:---:|------|
|
||||
| 网关启动时间 | < 5s | 含适配器并行初始化 |
|
||||
| 设备同步吞吐 | 100 设备/s | 含 HTTP 往返 |
|
||||
| 实时取流响应 | < 500ms | 从请求到返回流地址 |
|
||||
| 内存占用 | < 100MB | 空载状态 |
|
||||
| 并发连接数 | 50 | 同时处理的管理端请求 |
|
||||
|
||||
---
|
||||
|
||||
## 13. 测试策略
|
||||
|
||||
### 13.1 单元测试（Phase 4）
|
||||
|
||||
```
|
||||
IntegrationGateway.Core.Tests/
|
||||
├── AdapterRegistryTests # 注册/查找/初始化
|
||||
├── RateLimiterTests # 令牌桶行为
|
||||
└── ModelSerializationTests # JSON 序列化往返
|
||||
```
|
||||
|
||||
### 13.2 集成测试（需子系统 Mock）
|
||||
|
||||
```
|
||||
适配器层 Mock → 验证 Controller 路由分发
|
||||
Vol.Pro API Mock → 验证网关注册/心跳/同步流程
|
||||
```
|
||||
|
||||
### 13.3 边界测试
|
||||
|
||||
| 场景 | 预期行为 |
|
||||
|------|----------|
|
||||
| Owl 离线 | HealthCheck → false, 设备 IsOnline 不变 |
|
||||
| MC4.0 超时 | 返回 504, 不影响 Owl 适配器 |
|
||||
| 并发取流 | RateLimiter 排队, 不丢请求 |
|
||||
| 配置错误 | 启动时校验失败, 拒绝启动 |
|
||||
|
||||
---
|
||||
|
||||
## 14. 版本历史
|
||||
|
||||
| 版本 | 日期 | 变更 |
|
||||
|------|------|------|
|
||||
| 1.0 | 2025-05-17 | 初版详细设计 |
|
||||
|
||||
---
|
||||
|
||||
> **下一步**: Phase 0 Day 1 按本设计实施网关项目骨架。
|
||||
@@ -1,203 +0,0 @@
|
||||
# IntegrationGateway 对接网关详细设计 — 任务清单
|
||||
|
||||
> **基准文档**: 对接网关设计文档 v1.0
|
||||
> **分支**: phase/0-infrastructure
|
||||
> **原则**: 每阶段产出可编译、可提交的独立成果
|
||||
|
||||
---
|
||||
|
||||
## Phase G0: 项目骨架与核心抽象（预计 1 天）
|
||||
|
||||
### G0.1 解决方案与项目结构
|
||||
- [ ] 创建 `gateway/IntegrationGateway.sln`（dotnet new sln）
|
||||
- [ ] 创建 `src/IntegrationGateway.Core/` 类库项目（net8.0）
|
||||
- [ ] 创建 `src/IntegrationGateway.Host/` Web 项目（net8.0, ASP.NET Core Minimal API）
|
||||
- [ ] Host 引用 Core 项目
|
||||
- [ ] 确认 `dotnet build` 0 错误
|
||||
|
||||
### G0.2 能力接口体系（7 个接口）
|
||||
- [ ] 创建 `Core/Abstractions/IGatewayAdapter.cs` — 基础接口（AdapterCode/DisplayName/Capabilities/InitializeAsync/HealthCheckAsync）
|
||||
- [ ] 创建 `Core/Abstractions/IHasOwnDeviceTree.cs` — 对象树接口
|
||||
- [ ] 创建 `Core/Abstractions/IHasFlatDevices.cs` — 扁平设备列表接口
|
||||
- [ ] 创建 `Core/Abstractions/IHasPoints.cs` — 实时点位值 + 控制接口
|
||||
- [ ] 创建 `Core/Abstractions/IHasStreams.cs` — 视频流 + PTZ + 截图接口
|
||||
- [ ] 创建 `Core/Abstractions/IHasAlarms.cs` — 告警查询 + 确认 + 结束接口
|
||||
- [ ] 创建 `Core/Abstractions/IHasRecordings.cs` — 录像回放接口
|
||||
- [ ] 创建 `Core/Abstractions/IAcceptsMetadataPush.cs` — 元数据回写接口
|
||||
- [ ] 确认 `dotnet build` 0 错误
|
||||
|
||||
### G0.3 统一模型（10 个类）
|
||||
- [ ] 创建 `Core/Models/StandardDevice.cs`
|
||||
- [ ] 创建 `Core/Models/StandardAlarm.cs`
|
||||
- [ ] 创建 `Core/Models/StandardRecording.cs`
|
||||
- [ ] 创建 `Core/Models/DeviceTreeNode.cs`
|
||||
- [ ] 创建 `Core/Models/PointValue.cs`
|
||||
- [ ] 创建 `Core/Models/StreamUrls.cs`
|
||||
- [ ] 创建 `Core/Models/PagedResult.cs`（泛型分页容器）
|
||||
- [ ] 创建 `Core/Models/AdapterCapabilities.cs`
|
||||
- [ ] 创建 `Core/Models/MetadataChangeSet.cs`
|
||||
- [ ] 创建 `Core/Models/MetadataPushResult.cs`
|
||||
- [ ] 确认 `dotnet build` 0 错误
|
||||
|
||||
### G0.4 基础设施（3 个类）
|
||||
- [ ] 创建 `Core/Infrastructure/AdapterRegistry.cs` — 注册/查找/并行初始化
|
||||
- [ ] 创建 `Core/Infrastructure/RateLimiter.cs` — 令牌桶限流器
|
||||
- [ ] 创建 `Core/Infrastructure/GatewayClientFactory.cs` — Vol.Pro HTTP 客户端工厂
|
||||
- [ ] 确认 `dotnet build` 0 错误
|
||||
|
||||
> **G0 提交点**: `PhaseG0_gateway_core — Core 项目编译通过，7 接口 + 10 模型 + 3 基础设施`
|
||||
|
||||
---
|
||||
|
||||
## Phase G1: Host 宿主与路由注册（预计 0.5 天）
|
||||
|
||||
### G1.1 配置文件
|
||||
- [ ] 创建 `appsettings.json` — Owl/MC4/Gateway 三段配置
|
||||
- [ ] 配置验证：启动时检查必填项（VolProBaseUrl/NodeCode/NodeToken/Owl/MC4）
|
||||
|
||||
### G1.2 启动与注册
|
||||
- [ ] 实现 `Program.cs` — IHttpClientFactory 注册（"VolPro" 命名客户端）
|
||||
- [ ] 实现适配器初始化（从配置读取生成 OwlAdapter/MC4Adapter 实例 → 注册到 AdapterRegistry）
|
||||
- [ ] 实现并行初始化（`Task.WhenAll`，单个失败不影响其他）
|
||||
|
||||
### G1.3 B 组路由（14 个端点）
|
||||
- [ ] `GET /api/gateway/health` — 返回所有适配器健康状态
|
||||
- [ ] `GET /api/gateway/devices?adapter=&page=&size=&keyword=` — 扁平设备列表
|
||||
- [ ] `GET /api/gateway/tree?adapter=` — 对象树
|
||||
- [ ] `GET /api/gateway/streams/{adapter}/{deviceId}/live` — 实时流地址
|
||||
- [ ] `GET /api/gateway/streams/{adapter}/{deviceId}/playback?start=&end=` — 回放地址
|
||||
- [ ] `POST /api/gateway/streams/{adapter}/{deviceId}/snapshot` — 截图
|
||||
- [ ] `POST /api/gateway/streams/{adapter}/{deviceId}/ptz` — 云台控制
|
||||
- [ ] `GET /api/gateway/realtime/{adapter}/{deviceId}` — 实时点位值
|
||||
- [ ] `POST /api/gateway/realtime/{adapter}/control` — 设备控制写值
|
||||
- [ ] `GET /api/gateway/alarms/{adapter}?from=&to=&page=&size=` — 告警查询
|
||||
- [ ] `POST /api/gateway/alarms/{adapter}/{alarmId}/confirm` — 告警确认
|
||||
- [ ] `POST /api/gateway/alarms/{adapter}/{alarmId}/end` — 告警结束
|
||||
- [ ] `GET /api/gateway/recordings/{adapter}/{deviceId}` — 录像列表
|
||||
- [ ] `POST /api/gateway/devices/sync?adapter=` — 手动触发同步
|
||||
- [ ] 确认 `dotnet build` 0 错误
|
||||
|
||||
### G1.4 错误处理中间件
|
||||
- [ ] 统一错误响应格式：`{ error, message }`
|
||||
- [ ] 适配器未找到 → 404 `ADAPTER_NOT_FOUND`
|
||||
- [ ] 能力不支持 → 404 `CAPABILITY_NOT_SUPPORTED`
|
||||
- [ ] 第三方超时 → 504 `UPSTREAM_TIMEOUT`
|
||||
|
||||
> **G1 提交点**: `PhaseG1_gateway_host — Host 编译通过，14 个路由骨架就绪，健康检查可响应`
|
||||
|
||||
---
|
||||
|
||||
## Phase G2: OwlAdapter（预计 1 天）
|
||||
|
||||
### G2.1 项目创建
|
||||
- [ ] 创建 `src/IntegrationGateway.Adapters.Owl/` 类库项目（net8.0）
|
||||
- [ ] 引用 Core 项目
|
||||
- [ ] Host 引用 Adapters.Owl
|
||||
- [ ] 加入解决方案
|
||||
|
||||
### G2.2 OwlAuthHelper
|
||||
- [ ] 实现 RSA 公钥获取 → 加密登录 → JWT Token 缓存
|
||||
- [ ] Token 过期前自动刷新（懒刷新）
|
||||
- [ ] 提供 `GetAuthenticatedClientAsync()` 方法
|
||||
|
||||
### G2.3 OwlAdapter 核心实现
|
||||
- [ ] 实现 `IGatewayAdapter` — AdapterCode="Owl:main"
|
||||
- [ ] 实现 `IHasFlatDevices` — `GetDevicesAsync` 分页 + `GetAllDevicesAsync` 全量
|
||||
- [ ] 实现通道管理 — `GetChannelsAsync` + `GetAllChannelsAsync`
|
||||
- [ ] 设备映射 — `OwlDevice → StandardDevice`, `OwlChannel → StandardDevice`
|
||||
|
||||
### G2.4 OwlAdapter 视频流实现
|
||||
- [ ] 实现 `IHasStreams.GetLiveUrlAsync` — POST /channels/:id/play → StreamUrls
|
||||
- [ ] 实现 `IHasStreams.GetPlaybackUrlAsync` — 构建 HLS VOD URL
|
||||
- [ ] 实现 `IHasStreams.PtzControlAsync` — continuous + stop（仅方向键）
|
||||
- [ ] 实现 `IHasStreams.GetSnapshotAsync` — POST /channels/:id/snapshot
|
||||
|
||||
### G2.5 OwlAdapter 录像与 Metadata
|
||||
- [ ] 实现 `IHasRecordings.GetRecordingsAsync` — GET /recordings
|
||||
- [ ] 实现 `IAcceptsMetadataPush.PushMetadataAsync` — PUT /devices/:id
|
||||
|
||||
### G2.6 HealthCheck
|
||||
- [ ] 实现 `HealthCheckAsync` — 调 /health 端点
|
||||
- [ ] Owl 认证失败 → HealthCheck = false
|
||||
|
||||
### G2.7 构建验证
|
||||
- [ ] 确认 `dotnet build` 0 错误
|
||||
- [ ] 确认 `POST /register` 返回 OwlAdapter 在适配器列表中
|
||||
|
||||
> **G2 提交点**: `PhaseG2_owl_adapter — OwlAdapter 编译通过，3 个接口实现完整（FlatDevices+Streams+Recordings+MetadataPush）`
|
||||
|
||||
---
|
||||
|
||||
## Phase G3: MC4Adapter（预计 1 天）
|
||||
|
||||
### G3.1 项目创建
|
||||
- [ ] 创建 `src/IntegrationGateway.Adapters.MC4/` 类库项目（net8.0）
|
||||
- [ ] 引用 Core 项目
|
||||
- [ ] Host 引用 Adapters.MC4
|
||||
- [ ] 加入解决方案
|
||||
|
||||
### G3.2 Mc4AuthHelper
|
||||
- [ ] 实现 POST /api/central/auth/conf/get → Token 缓存（8 小时）
|
||||
- [ ] 提供 `GetAuthenticatedClientAsync()` 方法（header["token"]）
|
||||
|
||||
### G3.3 MC4Adapter 对象树
|
||||
- [ ] 实现 `IGatewayAdapter` — AdapterCode="MC4:31ku"
|
||||
- [ ] 实现 `IHasOwnDeviceTree.GetObjectTreeAsync` — POST /api/central/object/tree → DeviceTreeNode[]
|
||||
- [ ] MC4 节点映射：`Mc4TreeNode → DeviceTreeNode`（Type=1区域/2设备）
|
||||
|
||||
### G3.4 MC4Adapter 实时数据
|
||||
- [ ] 实现 `IHasPoints.GetRealtimeValuesAsync` — POST /api/central/device/point/value/get → PointValue[]
|
||||
- [ ] 实现 `IHasPoints.GetMultiPointValuesAsync` — POST /api/central/point/multi/value/get
|
||||
- [ ] 实现 `IHasPoints.SetPointValueAsync` — POST /api/central/point/value/set
|
||||
|
||||
### G3.5 MC4Adapter 告警
|
||||
- [ ] 实现 `IHasAlarms.GetAlarmsAsync` — POST /api/central/alarm/query（skip/limit 转 page/size）
|
||||
- [ ] 实现 `IHasAlarms.ConfirmAlarmAsync` — POST /api/central/alarm/confirm
|
||||
- [ ] 实现 `IHasAlarms.EndAlarmAsync` — POST /api/central/alarm/end
|
||||
- [ ] 告警去重：`SourceAlarmId` 唯一
|
||||
|
||||
### G3.6 限流与验证
|
||||
- [ ] RateLimiter = new RateLimiter(2)（MC4.0 QPS 限制）
|
||||
- [ ] 确认 `dotnet build` 0 错误
|
||||
|
||||
> **G3 提交点**: `PhaseG3_mc4_adapter — MC4Adapter 编译通过，3 个接口实现完整（OwnDeviceTree+Points+Alarms）`
|
||||
|
||||
---
|
||||
|
||||
## Phase G4: 联调验证（需子系统就绪，预计 1 天）
|
||||
|
||||
### G4.1 Owl 联调
|
||||
- [ ] 启动 Owl+ZLM → 网关 RSA 登录成功
|
||||
- [ ] `GET /api/gateway/devices?adapter=Owl:main` → 返回设备列表
|
||||
- [ ] `GET /api/gateway/streams/Owl:main/{channelId}/live` → 返回 WS-FLV 地址
|
||||
- [ ] `POST /api/gateway/streams/Owl:main/{channelId}/ptz` → 云台响应
|
||||
|
||||
### G4.2 MC4.0 联调
|
||||
- [ ] `GET /api/gateway/tree?adapter=MC4:31ku` → 返回对象树 JSON
|
||||
- [ ] `GET /api/gateway/realtime/MC4:31ku/{deviceId}` → 返回点位值
|
||||
- [ ] `GET /api/gateway/alarms/MC4:31ku` → 返回告警列表
|
||||
|
||||
### G4.3 故障隔离验证
|
||||
- [ ] 停止 MC4.0 → `GET /health` 中 Owl=OK, MC4=FAIL
|
||||
- [ ] Owl 设备查询仍正常返回
|
||||
|
||||
> **G4 提交点**: `PhaseG4_integration — 联调通过，健康检查报告真实状态`
|
||||
|
||||
---
|
||||
|
||||
## Phase G5: 部署与文档（预计 0.5 天）
|
||||
|
||||
### G5.1 发布
|
||||
- [ ] `dotnet publish` Release 模式
|
||||
- [ ] Dockerfile 编写与构建
|
||||
|
||||
### G5.2 运维文档
|
||||
- [ ] 启动脚本（单机/Docker）
|
||||
- [ ] 配置说明（环境变量覆盖）
|
||||
- [ ] 健康检查命令
|
||||
|
||||
> **G5 提交点**: `PhaseG5_deploy — 可发布的网关二进制 + 运维文档`
|
||||
|
||||
---
|
||||
|
||||
> **总周期**: G0-G5 预计 4 个工作日（不含联调等待时间）
|
||||
@@ -5,9 +5,9 @@ VisualStudioVersion = 17.0.31903.59
|
||||
MinimumVisualStudioVersion = 10.0.40219.1
|
||||
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{827E0CD3-B72D-47B6-A68D-7590B98EB39B}"
|
||||
EndProject
|
||||
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "IntegrationGateway.Host", "src\IntegrationGateway.Host\IntegrationGateway.Host.csproj", "{8F605B6B-5217-4119-A75E-05FFB4E42347}"
|
||||
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "IntegrationGateway.Host", "src\IntegrationGateway.Host\IntegrationGateway.Host.csproj", "{387BD4FC-725B-4948-B413-F50BC6BD605D}"
|
||||
EndProject
|
||||
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "IntegrationGateway.Core", "src\IntegrationGateway.Core\IntegrationGateway.Core.csproj", "{D1F85A10-E56A-44E8-96B8-7BC3C91E513B}"
|
||||
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "IntegrationGateway.Core", "src\IntegrationGateway.Core\IntegrationGateway.Core.csproj", "{2055B7A5-418F-456C-8642-A99A68282561}"
|
||||
EndProject
|
||||
Global
|
||||
GlobalSection(SolutionConfigurationPlatforms) = preSolution
|
||||
@@ -19,36 +19,36 @@ Global
|
||||
Release|x86 = Release|x86
|
||||
EndGlobalSection
|
||||
GlobalSection(ProjectConfigurationPlatforms) = postSolution
|
||||
{8F605B6B-5217-4119-A75E-05FFB4E42347}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
|
||||
{8F605B6B-5217-4119-A75E-05FFB4E42347}.Debug|Any CPU.Build.0 = Debug|Any CPU
|
||||
{8F605B6B-5217-4119-A75E-05FFB4E42347}.Debug|x64.ActiveCfg = Debug|Any CPU
|
||||
{8F605B6B-5217-4119-A75E-05FFB4E42347}.Debug|x64.Build.0 = Debug|Any CPU
|
||||
{8F605B6B-5217-4119-A75E-05FFB4E42347}.Debug|x86.ActiveCfg = Debug|Any CPU
|
||||
{8F605B6B-5217-4119-A75E-05FFB4E42347}.Debug|x86.Build.0 = Debug|Any CPU
|
||||
{8F605B6B-5217-4119-A75E-05FFB4E42347}.Release|Any CPU.ActiveCfg = Release|Any CPU
|
||||
{8F605B6B-5217-4119-A75E-05FFB4E42347}.Release|Any CPU.Build.0 = Release|Any CPU
|
||||
{8F605B6B-5217-4119-A75E-05FFB4E42347}.Release|x64.ActiveCfg = Release|Any CPU
|
||||
{8F605B6B-5217-4119-A75E-05FFB4E42347}.Release|x64.Build.0 = Release|Any CPU
|
||||
{8F605B6B-5217-4119-A75E-05FFB4E42347}.Release|x86.ActiveCfg = Release|Any CPU
|
||||
{8F605B6B-5217-4119-A75E-05FFB4E42347}.Release|x86.Build.0 = Release|Any CPU
|
||||
{D1F85A10-E56A-44E8-96B8-7BC3C91E513B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
|
||||
{D1F85A10-E56A-44E8-96B8-7BC3C91E513B}.Debug|Any CPU.Build.0 = Debug|Any CPU
|
||||
{D1F85A10-E56A-44E8-96B8-7BC3C91E513B}.Debug|x64.ActiveCfg = Debug|Any CPU
|
||||
{D1F85A10-E56A-44E8-96B8-7BC3C91E513B}.Debug|x64.Build.0 = Debug|Any CPU
|
||||
{D1F85A10-E56A-44E8-96B8-7BC3C91E513B}.Debug|x86.ActiveCfg = Debug|Any CPU
|
||||
{D1F85A10-E56A-44E8-96B8-7BC3C91E513B}.Debug|x86.Build.0 = Debug|Any CPU
|
||||
{D1F85A10-E56A-44E8-96B8-7BC3C91E513B}.Release|Any CPU.ActiveCfg = Release|Any CPU
|
||||
{D1F85A10-E56A-44E8-96B8-7BC3C91E513B}.Release|Any CPU.Build.0 = Release|Any CPU
|
||||
{D1F85A10-E56A-44E8-96B8-7BC3C91E513B}.Release|x64.ActiveCfg = Release|Any CPU
|
||||
{D1F85A10-E56A-44E8-96B8-7BC3C91E513B}.Release|x64.Build.0 = Release|Any CPU
|
||||
{D1F85A10-E56A-44E8-96B8-7BC3C91E513B}.Release|x86.ActiveCfg = Release|Any CPU
|
||||
{D1F85A10-E56A-44E8-96B8-7BC3C91E513B}.Release|x86.Build.0 = Release|Any CPU
|
||||
{387BD4FC-725B-4948-B413-F50BC6BD605D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
|
||||
{387BD4FC-725B-4948-B413-F50BC6BD605D}.Debug|Any CPU.Build.0 = Debug|Any CPU
|
||||
{387BD4FC-725B-4948-B413-F50BC6BD605D}.Debug|x64.ActiveCfg = Debug|Any CPU
|
||||
{387BD4FC-725B-4948-B413-F50BC6BD605D}.Debug|x64.Build.0 = Debug|Any CPU
|
||||
{387BD4FC-725B-4948-B413-F50BC6BD605D}.Debug|x86.ActiveCfg = Debug|Any CPU
|
||||
{387BD4FC-725B-4948-B413-F50BC6BD605D}.Debug|x86.Build.0 = Debug|Any CPU
|
||||
{387BD4FC-725B-4948-B413-F50BC6BD605D}.Release|Any CPU.ActiveCfg = Release|Any CPU
|
||||
{387BD4FC-725B-4948-B413-F50BC6BD605D}.Release|Any CPU.Build.0 = Release|Any CPU
|
||||
{387BD4FC-725B-4948-B413-F50BC6BD605D}.Release|x64.ActiveCfg = Release|Any CPU
|
||||
{387BD4FC-725B-4948-B413-F50BC6BD605D}.Release|x64.Build.0 = Release|Any CPU
|
||||
{387BD4FC-725B-4948-B413-F50BC6BD605D}.Release|x86.ActiveCfg = Release|Any CPU
|
||||
{387BD4FC-725B-4948-B413-F50BC6BD605D}.Release|x86.Build.0 = Release|Any CPU
|
||||
{2055B7A5-418F-456C-8642-A99A68282561}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
|
||||
{2055B7A5-418F-456C-8642-A99A68282561}.Debug|Any CPU.Build.0 = Debug|Any CPU
|
||||
{2055B7A5-418F-456C-8642-A99A68282561}.Debug|x64.ActiveCfg = Debug|Any CPU
|
||||
{2055B7A5-418F-456C-8642-A99A68282561}.Debug|x64.Build.0 = Debug|Any CPU
|
||||
{2055B7A5-418F-456C-8642-A99A68282561}.Debug|x86.ActiveCfg = Debug|Any CPU
|
||||
{2055B7A5-418F-456C-8642-A99A68282561}.Debug|x86.Build.0 = Debug|Any CPU
|
||||
{2055B7A5-418F-456C-8642-A99A68282561}.Release|Any CPU.ActiveCfg = Release|Any CPU
|
||||
{2055B7A5-418F-456C-8642-A99A68282561}.Release|Any CPU.Build.0 = Release|Any CPU
|
||||
{2055B7A5-418F-456C-8642-A99A68282561}.Release|x64.ActiveCfg = Release|Any CPU
|
||||
{2055B7A5-418F-456C-8642-A99A68282561}.Release|x64.Build.0 = Release|Any CPU
|
||||
{2055B7A5-418F-456C-8642-A99A68282561}.Release|x86.ActiveCfg = Release|Any CPU
|
||||
{2055B7A5-418F-456C-8642-A99A68282561}.Release|x86.Build.0 = Release|Any CPU
|
||||
EndGlobalSection
|
||||
GlobalSection(SolutionProperties) = preSolution
|
||||
HideSolutionNode = FALSE
|
||||
EndGlobalSection
|
||||
GlobalSection(NestedProjects) = preSolution
|
||||
{8F605B6B-5217-4119-A75E-05FFB4E42347} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
|
||||
{D1F85A10-E56A-44E8-96B8-7BC3C91E513B} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
|
||||
{387BD4FC-725B-4948-B413-F50BC6BD605D} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
|
||||
{2055B7A5-418F-456C-8642-A99A68282561} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
|
||||
EndGlobalSection
|
||||
EndGlobal
|
||||
|
||||
@@ -22,9 +22,6 @@ public class RateLimiter
|
||||
await Task.Delay(_minIntervalMs - elapsed);
|
||||
_lastRequest = DateTime.UtcNow;
|
||||
}
|
||||
finally
|
||||
{
|
||||
_semaphore.Release();
|
||||
}
|
||||
finally { _semaphore.Release(); }
|
||||
}
|
||||
}
|
||||
|
||||
@@ -18,14 +18,8 @@ public class TokenManager
|
||||
public async Task SetAsync(string key, string token, TimeSpan expiresIn)
|
||||
{
|
||||
await _semaphore.WaitAsync();
|
||||
try
|
||||
{
|
||||
_cache.Set($"token_{key}", token, expiresIn * 0.9);
|
||||
}
|
||||
finally
|
||||
{
|
||||
_semaphore.Release();
|
||||
}
|
||||
try { _cache.Set($"token_{key}", token, expiresIn * 0.9); }
|
||||
finally { _semaphore.Release(); }
|
||||
}
|
||||
|
||||
public void Remove(string key) => _cache.Remove($"token_{key}");
|
||||
|
||||
@@ -10,7 +10,6 @@ public class StandardAlarm
|
||||
public string? Content { get; set; }
|
||||
public DateTime OccurTime { get; set; }
|
||||
public string Status { get; set; } = "Active";
|
||||
public string? PointCode { get; set; }
|
||||
public double? ThresholdValue { get; set; }
|
||||
public double? ActualValue { get; set; }
|
||||
}
|
||||
|
||||
@@ -6,18 +6,12 @@ public class StandardDevice
|
||||
public string AdapterCode { get; set; } = "";
|
||||
public string Name { get; set; } = "";
|
||||
public string Category { get; set; } = "";
|
||||
public string? Type { get; set; }
|
||||
public string Group { get; set; } = "";
|
||||
public string? IpAddress { get; set; }
|
||||
public int? Port { get; set; }
|
||||
public bool IsOnline { get; set; }
|
||||
public string? Location { get; set; }
|
||||
public double? Lat { get; set; }
|
||||
public double? Lng { get; set; }
|
||||
public string? MapModelId { get; set; }
|
||||
public int ChannelCount { get; set; }
|
||||
public bool IsParent { get; set; }
|
||||
public string? ParentSourceId { get; set; }
|
||||
public string? SourcePath { get; set; }
|
||||
public Dictionary<string, object?> Extra { get; set; } = new();
|
||||
public DateTime LastSyncTime { get; set; }
|
||||
}
|
||||
|
||||
@@ -10,5 +10,4 @@ public class StandardPoint
|
||||
public string? PointDesc { get; set; }
|
||||
public string? Unit { get; set; }
|
||||
public bool IsControlPoint { get; set; }
|
||||
public Dictionary<string, object?>? RawOption { get; set; }
|
||||
}
|
||||
|
||||
@@ -9,11 +9,11 @@ namespace IntegrationGateway.Host.Controllers;
|
||||
public class AlarmsController : ControllerBase
|
||||
{
|
||||
private readonly AdapterRegistry _registry;
|
||||
|
||||
public AlarmsController(AdapterRegistry registry) => _registry = registry;
|
||||
|
||||
[HttpGet("{adapter}")]
|
||||
public async Task<IActionResult> GetAlarms(string adapter, [FromQuery] DateTime from, [FromQuery] DateTime to,
|
||||
public async Task<IActionResult> GetAlarms(string adapter,
|
||||
[FromQuery] DateTime from, [FromQuery] DateTime to,
|
||||
[FromQuery] int page = 1, [FromQuery] int size = 50)
|
||||
{
|
||||
var a = _registry.Get(adapter);
|
||||
|
||||
@@ -1,6 +1,5 @@
|
||||
using IntegrationGateway.Core.Abstractions;
|
||||
using IntegrationGateway.Core.Infrastructure;
|
||||
using IntegrationGateway.Core.Models;
|
||||
using Microsoft.AspNetCore.Mvc;
|
||||
|
||||
namespace IntegrationGateway.Host.Controllers;
|
||||
@@ -10,14 +9,13 @@ namespace IntegrationGateway.Host.Controllers;
|
||||
public class DevicesController : ControllerBase
|
||||
{
|
||||
private readonly AdapterRegistry _registry;
|
||||
|
||||
public DevicesController(AdapterRegistry registry) => _registry = registry;
|
||||
|
||||
[HttpGet]
|
||||
public async Task<IActionResult> GetDevices([FromQuery] string adapter, [FromQuery] int page = 1, [FromQuery] int size = 50)
|
||||
{
|
||||
var a = _registry.Get(adapter);
|
||||
if (a is not IHasFlatDevices f) return NotFound("Adapter not found or unsupported");
|
||||
if (a is not IHasFlatDevices f) return NotFound();
|
||||
return Ok(await f.GetDevicesAsync(page, size));
|
||||
}
|
||||
|
||||
|
||||
@@ -8,15 +8,14 @@ namespace IntegrationGateway.Host.Controllers;
|
||||
public class HealthController : ControllerBase
|
||||
{
|
||||
private readonly AdapterRegistry _registry;
|
||||
|
||||
public HealthController(AdapterRegistry registry) => _registry = registry;
|
||||
|
||||
[HttpGet]
|
||||
public async Task<IActionResult> Get()
|
||||
{
|
||||
var status = new Dictionary<string, bool>();
|
||||
foreach (var adapter in _registry.GetAll())
|
||||
status[adapter.AdapterCode] = await adapter.HealthCheckAsync();
|
||||
return Ok(status);
|
||||
foreach (var a in _registry.GetAll())
|
||||
status[a.AdapterCode] = await a.HealthCheckAsync();
|
||||
return Ok(new { gateway = "ok", adapters = status });
|
||||
}
|
||||
}
|
||||
|
||||
@@ -9,7 +9,6 @@ namespace IntegrationGateway.Host.Controllers;
|
||||
public class PointsController : ControllerBase
|
||||
{
|
||||
private readonly AdapterRegistry _registry;
|
||||
|
||||
public PointsController(AdapterRegistry registry) => _registry = registry;
|
||||
|
||||
[HttpGet("{adapter}/{deviceId}")]
|
||||
@@ -25,14 +24,14 @@ public class PointsController : ControllerBase
|
||||
{
|
||||
var a = _registry.Get(adapter);
|
||||
if (a is not IHasPoints p) return NotFound();
|
||||
await p.SetPointValueAsync(req.DeviceId, req.PointIndex, req.Value);
|
||||
await p.SetPointValueAsync(req.DeviceSourceId, req.PointIndex, req.Value);
|
||||
return Ok(new { status = "sent" });
|
||||
}
|
||||
}
|
||||
|
||||
public class ControlRequest
|
||||
{
|
||||
public string DeviceId { get; set; } = "";
|
||||
public string DeviceSourceId { get; set; } = "";
|
||||
public int PointIndex { get; set; }
|
||||
public double Value { get; set; }
|
||||
}
|
||||
|
||||
@@ -0,0 +1,40 @@
|
||||
using IntegrationGateway.Core.Infrastructure;
|
||||
using Microsoft.AspNetCore.Mvc;
|
||||
|
||||
namespace IntegrationGateway.Host.Controllers;
|
||||
|
||||
[ApiController]
|
||||
[Route("api/gateway")]
|
||||
public class RegisterController : ControllerBase
|
||||
{
|
||||
private readonly AdapterRegistry _registry;
|
||||
|
||||
public RegisterController(AdapterRegistry registry) => _registry = registry;
|
||||
|
||||
[HttpPost("register")]
|
||||
public async Task<IActionResult> Register([FromBody] RegisterRequest req)
|
||||
{
|
||||
// 网关向 Vol.Pro 注册，由外部 GatewayClient 调用
|
||||
return Ok(new { status = "ok" });
|
||||
}
|
||||
|
||||
[HttpPost("heartbeat")]
|
||||
public async Task<IActionResult> Heartbeat([FromBody] HeartbeatRequest req)
|
||||
{
|
||||
return Ok(new { status = "ok" });
|
||||
}
|
||||
}
|
||||
|
||||
public class RegisterRequest
|
||||
{
|
||||
public string NodeCode { get; set; } = "";
|
||||
public string Token { get; set; } = "";
|
||||
public string AdapterTypes { get; set; } = "";
|
||||
public string BaseUrl { get; set; } = "";
|
||||
}
|
||||
|
||||
public class HeartbeatRequest
|
||||
{
|
||||
public string NodeCode { get; set; } = "";
|
||||
public string Token { get; set; } = "";
|
||||
}
|
||||
@@ -9,7 +9,6 @@ namespace IntegrationGateway.Host.Controllers;
|
||||
public class StreamsController : ControllerBase
|
||||
{
|
||||
private readonly AdapterRegistry _registry;
|
||||
|
||||
public StreamsController(AdapterRegistry registry) => _registry = registry;
|
||||
|
||||
[HttpGet("{adapter}/{channelId}/live")]
|
||||
@@ -20,13 +19,25 @@ public class StreamsController : ControllerBase
|
||||
return Ok(await s.GetLiveUrlAsync(channelId));
|
||||
}
|
||||
|
||||
[HttpGet("{adapter}/{channelId}/playback")]
|
||||
public async Task<IActionResult> GetPlayback(string adapter, string channelId,
|
||||
[FromQuery] DateTime start, [FromQuery] DateTime end)
|
||||
{
|
||||
var a = _registry.Get(adapter);
|
||||
if (a is not IHasStreams s) return NotFound();
|
||||
return Ok(await s.GetPlaybackUrlAsync(channelId, start, end));
|
||||
}
|
||||
|
||||
[HttpPost("{adapter}/{channelId}/ptz")]
|
||||
public async Task<IActionResult> Ptz(string adapter, string channelId, [FromBody] PtzRequest req)
|
||||
{
|
||||
var a = _registry.Get(adapter);
|
||||
if (a is not IHasStreams s) return NotFound();
|
||||
await s.PtzControlAsync(channelId, req.Direction, req.Speed);
|
||||
return Ok();
|
||||
if (req.Direction == "stop")
|
||||
await s.PtzStopAsync(channelId);
|
||||
else
|
||||
await s.PtzControlAsync(channelId, req.Direction, req.Speed);
|
||||
return Ok(new { status = "ok" });
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -10,42 +10,32 @@ namespace IntegrationGateway.Host.Controllers;
|
||||
public class SyncController : ControllerBase
|
||||
{
|
||||
private readonly AdapterRegistry _registry;
|
||||
|
||||
public SyncController(AdapterRegistry registry) => _registry = registry;
|
||||
|
||||
[HttpGet("devices/sync")]
|
||||
[HttpPost("devices/sync")]
|
||||
public async Task<IActionResult> SyncDevices([FromQuery] string adapter)
|
||||
{
|
||||
var a = _registry.Get(adapter) ?? throw new InvalidOperationException($"Adapter '{adapter}' not found");
|
||||
|
||||
var a = _registry.Get(adapter)
|
||||
?? throw new InvalidOperationException($"Adapter '{adapter}' not found");
|
||||
|
||||
var report = new SyncReport { AdapterCode = adapter, StartTime = DateTime.UtcNow };
|
||||
|
||||
if (a is IHasFlatDevices f)
|
||||
report = await SyncFlatDevices(f, report);
|
||||
{
|
||||
var devices = await f.GetAllDevicesAsync();
|
||||
report.Added = devices.Count;
|
||||
}
|
||||
else if (a is IHasOwnDeviceTree t)
|
||||
report = await SyncTreeDevices(t, report);
|
||||
else
|
||||
return BadRequest("Adapter does not support device sync");
|
||||
{
|
||||
var tree = await t.GetObjectTreeAsync();
|
||||
report.Added = CountDeviceNodes(tree);
|
||||
}
|
||||
else return BadRequest("Adapter does not support device sync");
|
||||
|
||||
report.EndTime = DateTime.UtcNow;
|
||||
return Ok(report);
|
||||
}
|
||||
|
||||
private async Task<SyncReport> SyncFlatDevices(IHasFlatDevices adapter, SyncReport report)
|
||||
{
|
||||
var devices = await adapter.GetAllDevicesAsync();
|
||||
report.Added = devices.Count;
|
||||
return report;
|
||||
}
|
||||
|
||||
private async Task<SyncReport> SyncTreeDevices(IHasOwnDeviceTree adapter, SyncReport report)
|
||||
{
|
||||
var tree = await adapter.GetObjectTreeAsync();
|
||||
int count = CountDeviceNodes(tree);
|
||||
report.Added = count;
|
||||
return report;
|
||||
}
|
||||
|
||||
private int CountDeviceNodes(List<DeviceTreeNode> nodes)
|
||||
{
|
||||
int count = 0;
|
||||
|
||||
118
gateway/src/IntegrationGateway.Host/GatewayClient.cs
Normal file
118
gateway/src/IntegrationGateway.Host/GatewayClient.cs
Normal file
@@ -0,0 +1,118 @@
|
||||
using System.Text;
|
||||
using System.Text.Json;
|
||||
|
||||
namespace IntegrationGateway.Host;
|
||||
|
||||
public class GatewayClient
|
||||
{
|
||||
private readonly HttpClient _http;
|
||||
private readonly IConfiguration _config;
|
||||
|
||||
public GatewayClient(IHttpClientFactory factory, IConfiguration config)
|
||||
{
|
||||
_http = factory.CreateClient("VolPro");
|
||||
_config = config;
|
||||
}
|
||||
|
||||
/// <summary>A1: 网关注册</summary>
|
||||
public async Task<RegisterResponse?> RegisterAsync()
|
||||
{
|
||||
var resp = await _http.PostAsJsonAsync("/api/gateway/register", new
|
||||
{
|
||||
nodeCode = _config["NodeCode"],
|
||||
token = _config["NodeToken"],
|
||||
adapterTypes = GetAdapterTypes(),
|
||||
baseUrl = _config["Urls"]?.Replace("http://*:", $"http://localhost:")
|
||||
});
|
||||
resp.EnsureSuccessStatusCode();
|
||||
return await resp.Content.ReadFromJsonAsync<RegisterResponse>();
|
||||
}
|
||||
|
||||
/// <summary>A2: 心跳</summary>
|
||||
public async Task HeartbeatAsync()
|
||||
{
|
||||
await _http.PostAsJsonAsync("/api/gateway/heartbeat", new
|
||||
{
|
||||
nodeCode = _config["NodeCode"],
|
||||
token = _config["NodeToken"]
|
||||
});
|
||||
}
|
||||
|
||||
/// <summary>A3: 设备同步</summary>
|
||||
public async Task<SyncResult> SyncDevicesAsync(List<DeviceSyncItem> devices)
|
||||
{
|
||||
var resp = await _http.PostAsJsonAsync("/api/gateway/sync/devices", new
|
||||
{
|
||||
nodeCode = _config["NodeCode"],
|
||||
token = _config["NodeToken"],
|
||||
devices
|
||||
});
|
||||
resp.EnsureSuccessStatusCode();
|
||||
return await resp.Content.ReadFromJsonAsync<SyncResult>() ?? new();
|
||||
}
|
||||
|
||||
/// <summary>A4: 告警同步</summary>
|
||||
public async Task<SyncResult> SyncAlarmsAsync(List<AlarmSyncItem> alarms)
|
||||
{
|
||||
var resp = await _http.PostAsJsonAsync("/api/gateway/sync/alarms", new
|
||||
{
|
||||
nodeCode = _config["NodeCode"],
|
||||
token = _config["NodeToken"],
|
||||
alarms
|
||||
});
|
||||
resp.EnsureSuccessStatusCode();
|
||||
return await resp.Content.ReadFromJsonAsync<SyncResult>() ?? new();
|
||||
}
|
||||
|
||||
private string GetAdapterTypes() => "MC4,Owl";
|
||||
}
|
||||
|
||||
public class RegisterResponse
|
||||
{
|
||||
public int NodeId { get; set; }
|
||||
public List<DeviceItem> Devices { get; set; } = new();
|
||||
}
|
||||
|
||||
public class DeviceItem
|
||||
{
|
||||
public int DeviceId { get; set; }
|
||||
public string DeviceName { get; set; } = "";
|
||||
public string AdapterCode { get; set; } = "";
|
||||
public string SourceId { get; set; } = "";
|
||||
public string DeviceCategory { get; set; } = "";
|
||||
public string DeviceGroup { get; set; } = "";
|
||||
public string IsParent { get; set; } = "";
|
||||
public string IsOnline { get; set; } = "";
|
||||
public JsonElement? ExtraData { get; set; }
|
||||
}
|
||||
|
||||
public class DeviceSyncItem
|
||||
{
|
||||
public string AdapterCode { get; set; } = "";
|
||||
public string SourceId { get; set; } = "";
|
||||
public string Name { get; set; } = "";
|
||||
public string Category { get; set; } = "";
|
||||
public string Group { get; set; } = "";
|
||||
public bool IsParent { get; set; }
|
||||
public string? ParentSourceId { get; set; }
|
||||
public bool IsOnline { get; set; }
|
||||
public string? IpAddress { get; set; }
|
||||
public int? Port { get; set; }
|
||||
public Dictionary<string, object?>? ExtraData { get; set; }
|
||||
}
|
||||
|
||||
public class AlarmSyncItem
|
||||
{
|
||||
public string SourceAlarmId { get; set; } = "";
|
||||
public string DeviceSourceId { get; set; } = "";
|
||||
public string AdapterCode { get; set; } = "";
|
||||
public string Level { get; set; } = "";
|
||||
public string Desc { get; set; } = "";
|
||||
public double? Value { get; set; }
|
||||
public string StartTime { get; set; } = "";
|
||||
}
|
||||
|
||||
public class SyncResult
|
||||
{
|
||||
public int Added { get; set; }
|
||||
}
|
||||
@@ -1,4 +1,4 @@
|
||||
@IntegrationGateway.Host_HostAddress = http://localhost:5294
|
||||
@IntegrationGateway.Host_HostAddress = http://localhost:5169
|
||||
|
||||
GET {{IntegrationGateway.Host_HostAddress}}/weatherforecast/
|
||||
Accept: application/json
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
using IntegrationGateway.Core.Infrastructure;
|
||||
using IntegrationGateway.Host;
|
||||
|
||||
var builder = WebApplication.CreateBuilder(args);
|
||||
|
||||
@@ -6,9 +7,32 @@ builder.Services.AddControllers();
|
||||
builder.Services.AddMemoryCache();
|
||||
builder.Services.AddSingleton<AdapterRegistry>();
|
||||
builder.Services.AddSingleton<TokenManager>();
|
||||
builder.Services.AddHttpClient("VolPro", c =>
|
||||
{
|
||||
c.BaseAddress = new Uri(builder.Configuration["VolProBaseUrl"] ?? "http://localhost:9100");
|
||||
});
|
||||
builder.Services.AddSingleton<GatewayClient>();
|
||||
|
||||
var app = builder.Build();
|
||||
|
||||
app.MapControllers();
|
||||
|
||||
// 启动时自动向 Vol.Pro 注册
|
||||
app.Lifetime.ApplicationStarted.Register(() =>
|
||||
{
|
||||
Task.Run(async () =>
|
||||
{
|
||||
var gw = app.Services.GetRequiredService<GatewayClient>();
|
||||
var registry = app.Services.GetRequiredService<AdapterRegistry>();
|
||||
try
|
||||
{
|
||||
var result = await gw.RegisterAsync();
|
||||
Console.WriteLine($"[Gateway] Registered as NodeId={result?.NodeId}, Devices={result?.Devices.Count ?? 0}");
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
Console.WriteLine($"[Gateway] Registration failed: {ex.Message}");
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
app.Run();
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
"windowsAuthentication": false,
|
||||
"anonymousAuthentication": true,
|
||||
"iisExpress": {
|
||||
"applicationUrl": "http://localhost:35846",
|
||||
"applicationUrl": "http://localhost:4117",
|
||||
"sslPort": 0
|
||||
}
|
||||
},
|
||||
@@ -14,7 +14,7 @@
|
||||
"dotnetRunMessages": true,
|
||||
"launchBrowser": true,
|
||||
"launchUrl": "swagger",
|
||||
"applicationUrl": "http://localhost:5294",
|
||||
"applicationUrl": "http://localhost:5169",
|
||||
"environmentVariables": {
|
||||
"ASPNETCORE_ENVIRONMENT": "Development"
|
||||
}
|
||||
|
||||
@@ -5,5 +5,9 @@
|
||||
"Microsoft.AspNetCore": "Warning"
|
||||
}
|
||||
},
|
||||
"AllowedHosts": "*"
|
||||
}
|
||||
"AllowedHosts": "*",
|
||||
"Urls": "http://*:5100",
|
||||
"VolProBaseUrl": "http://localhost:9100",
|
||||
"NodeCode": "gw-31ku",
|
||||
"NodeToken": "xxxxxxxxxx"
|
||||
}
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 352 KiB After Width: | Height: | Size: 903 KiB |
Reference in New Issue
Block a user