1164 lines
45 KiB
Markdown
1164 lines
45 KiB
Markdown
# Vol.Pro + MC4.0 采集网关整合方案
|
||
|
||
> **版本**: v1.0
|
||
> **日期**: 2026-04-29
|
||
> **编制**: 浮浮酱
|
||
> **状态**: 待确认（未实施）
|
||
|
||
---
|
||
|
||
## 一、项目概述
|
||
|
||
### 1.1 需求背景
|
||
|
||
MC4.0 是一款采集网关设备，负责接入温湿度传感器、空调控制器、485接口设备、开关量设备等，通过 HTTP API 对外提供设备管理、数据采集、反向控制和告警查询能力。
|
||
|
||
**目标**: 将 MC4.0 采集网关接入 Vol.Pro 后端，实现：
|
||
- 在 Vol.Pro 管理端中对采集设备进行增删改查管理
|
||
- warehouse 用户端实时展示设备数据（温湿度等）
|
||
- warehouse 用户端手动控制设备（如空调开关、温度设定）
|
||
- 接收并展示 MC4.0 的告警信息
|
||
|
||
### 1.2 MC4.0 API 能力分析
|
||
|
||
| 功能模块 | 接口 | 说明 |
|
||
|----------|------|------|
|
||
| **认证** | `/api/central/auth/login` | Token 认证（有效期需确认） |
|
||
| **对象树** | `/api/central/object/tree` | 获取区域+设备的树形结构 |
|
||
| **点表** | `/api/central/device/point/get` | 获取设备下的点（传感器/控制点） |
|
||
| **读数据** | `/api/central/device/point/value/get` | 按设备获取所有点的实时值 |
|
||
| **读数据** | `/api/central/point/multi/value/get` | 批量获取指定设备点的值 |
|
||
| **写控制** | `/api/central/point/value/set` | 设置设备点的值（反向控制） |
|
||
| **告警查询** | `/api/central/alarm/query` | 按条件查询告警（时间/设备/状态） |
|
||
| **告警处理** | `/api/central/alarm/confirm` | 确认告警 |
|
||
| **告警处理** | `/api/central/alarm/end` | 结束告警 |
|
||
| **历史告警** | `/api/central/his_alarm/query` | 查询历史告警记录 |
|
||
|
||
### 1.3 关键前提：所有修改独立于框架代码
|
||
|
||
> 与视频监控方案一致，所有自定义代码均写在 Vol.Pro 的扩展文件中，不修改任何框架自动生成的代码。
|
||
>
|
||
> - Controller 扩展写在 `Controllers/模块/Partial/`
|
||
> - Service 扩展写在 `Services/模块/Partial/`
|
||
> - Entity 扩展写在 `DomainModels/模块/partial/`
|
||
> - 前端扩展写在 `extension/` 目录
|
||
> - 新增独立服务实现 `IDependency`，Autofac 自动注入
|
||
|
||
---
|
||
|
||
## 二、系统架构设计
|
||
|
||
### 2.1 整体架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────┐
|
||
│ 客户端层 │
|
||
│ ┌─────────────────────┐ ┌─────────────────────┐ │
|
||
│ │ web.vite 管理端 │ │ warehouse 用户端 │ │
|
||
│ │ (设备管理+告警查看) │ │ (实时数据+设备控制) │ │
|
||
│ └──────────┬──────────┘ └──────────┬──────────┘ │
|
||
└─────────────┼──────────────────────────┼────────────────────────────────┘
|
||
│ │
|
||
▼ ▼
|
||
┌─────────────────────────────────────────────────────────────────────────┐
|
||
│ Vol.Pro 后端 (api_sqlsugar) │
|
||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||
│ │ 自动生成CRUD模块 │ │
|
||
│ │ ├─ Base_Device (统一设备主表，含视频监控+采集网关) │ │
|
||
│ │ ├─ Device_IoT_Ext (采集设备扩展信息) │ │
|
||
│ │ ├─ IoT_DevicePoint (设备点表/传感器点) │ │
|
||
│ │ ├─ IoT_DeviceData (实时/历史数据记录) │ │
|
||
│ │ └─ IoT_Alarm (告警记录管理) │ │
|
||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||
│ │ 扩展API模块 (IoTStreamController) │ │
|
||
│ │ ├─ POST /api/IoTStream/syncTree → 同步MC4.0对象树 │ │
|
||
│ │ ├─ POST /api/IoTStream/syncPoints → 同步设备点表 │ │
|
||
│ │ ├─ POST /api/IoTStream/realtime → 获取实时数据 │ │
|
||
│ │ ├─ POST /api/IoTStream/control → 设备反向控制 │ │
|
||
│ │ ├─ POST /api/IoTStream/alarms → 查询告警列表 │ │
|
||
│ │ ├─ POST /api/IoTStream/confirmAlarm→ 确认告警 │ │
|
||
│ │ └─ POST /api/IoTStream/pollAlarms → 手动轮询最新告警 │ │
|
||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||
│ │ MC4.0对接服务 (Mc4ApiService) │ │
|
||
│ │ ├─ Token管理 (登录/缓存/刷新) │ │
|
||
│ │ ├─ 对象树同步 (调用 /object/tree) │ │
|
||
│ │ ├─ 点表同步 (调用 /device/point/get) │ │
|
||
│ │ ├─ 实时数据获取 (调用 /device/point/value/get) │ │
|
||
│ │ ├─ 设备控制 (调用 /point/value/set) │ │
|
||
│ │ ├─ 告警查询 (调用 /alarm/query) │ │
|
||
│ │ └─ 告警确认/结束 (调用 /alarm/confirm, /alarm/end) │ │
|
||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||
│ │ 告警轮询任务 (Quartz Job) │ │
|
||
│ │ ├─ 每30秒轮询MC4.0最新告警 │ │
|
||
│ │ ├─ 将新告警写入 IoT_Alarm 表 │ │
|
||
│ │ └─ 通过 SignalR 推送给在线前端 │ │
|
||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||
└──────────────────────────────┬──────────────────────────────────────────┘
|
||
│ HTTP API (端口3000)
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────────┐
|
||
│ MC4.0 采集网关 │
|
||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||
│ │ 设备接入层 (温湿度/空调/485/开关量) │ │
|
||
│ │ 数据缓存层 │ │
|
||
│ │ HTTP API层 (对象树/点表/读值/写值/告警) │ │
|
||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.2 关键设计原则
|
||
|
||
1. **MC4.0 作为唯一设备源**: Vol.Pro 不直接管理设备接入，所有设备数据来自 MC4.0 的对象树
|
||
2. **数据双写**: MC4.0 中的设备、点表、告警通过同步机制写入 Vol.Pro 数据库
|
||
3. **定时轮询**: MC4.0 不支持主动推送，Vol.Pro 后端通过 Quartz 定时任务轮询实时数据和告警
|
||
4. **SignalR 推送**: Vol.Pro 后端通过 SignalR 将实时数据和告警主动推送给 warehouse 前端
|
||
|
||
---
|
||
|
||
## 三、数据库表设计
|
||
|
||
### 3.1 表结构说明
|
||
|
||
> **设备统一管理设计**：本方案与视频监控方案共用统一设备主表 `Base_Device`，实现视频监控设备和采集网关设备的统一管理，并支持在三维地图上统一标记展示。
|
||
|
||
#### 3.1.0 统一设备主表 (Base_Device) 【与视频监控方案共用】
|
||
|
||
| 字段名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| DeviceId | uniqueidentifier | ✅ | 主键，Vol.Pro系统内部ID |
|
||
| DeviceName | nvarchar(100) | ✅ | 设备名称 |
|
||
| DeviceCategory | int | ✅ | 设备大类：1=视频监控, 2=采集网关 |
|
||
| DeviceType | int | | 设备细分类型（根据Category解释不同值） |
|
||
| SourceId | nvarchar(64) | ✅ | 源系统设备ID（OwlDeviceId或Mc4DeviceId） |
|
||
| IpAddress | nvarchar(50) | | IP地址 |
|
||
| Port | int | | 端口 |
|
||
| IsOnline | int | | 是否在线：0=离线, 1=在线 |
|
||
| Location | nvarchar(200) | | 安装位置描述 |
|
||
| Lat | float | | 纬度（WGS84坐标系） |
|
||
| Lng | float | | 经度（WGS84坐标系） |
|
||
| **MapModelId** | **nvarchar(100)** | | **三维地图模型ID（VgoMap中对应模型的唯一标识）** |
|
||
| MapModelScale | float | | 三维模型缩放比例，默认1.0 |
|
||
| MapModelRotation | nvarchar(100) | | 三维模型旋转角度（JSON格式：{"x":0,"y":0,"z":0}） |
|
||
| Enable | int | | 启用状态：0=禁用, 1=启用 |
|
||
| Remark | nvarchar(500) | | 备注 |
|
||
| CreateID / Creator / CreateDate | | | Vol.Pro标准审计字段 |
|
||
| ModifyID / Modifier / ModifyDate | | | Vol.Pro标准审计字段 |
|
||
|
||
> **MapModelId 字段说明**：
|
||
> - 用于在warehouse前端三维地图（VgoMap）中标记设备位置
|
||
> - 值由三维地图系统提供，标识对应三维模型的唯一ID
|
||
> - 管理端可在设备编辑页面中配置/修改此字段
|
||
> - 三维地图加载时，根据MapModelId将设备图标/模型绑定到地图对应位置
|
||
|
||
#### 3.1.1 采集设备扩展表 (Device_IoT_Ext)
|
||
|
||
> 存储采集网关设备特有的扩展信息，通过DeviceId关联Base_Device主表。
|
||
|
||
| 字段名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| ExtId | uniqueidentifier | ✅ | 主键 |
|
||
| DeviceId | uniqueidentifier | ✅ | 关联Base_Device.DeviceId |
|
||
| Mc4DeviceId | int | ✅ | MC4.0 设备ID |
|
||
| ObjectType | int | | MC4.0 objectType 原始值 |
|
||
| Tag | nvarchar(100) | | 设备标签 |
|
||
| ParentId | int | | MC4.0 父级ID（区域层级） |
|
||
| Mc4Option | nvarchar(500) | | MC4.0 option 原始JSON |
|
||
|
||
#### 3.1.2 设备点表 (IoT_DevicePoint)
|
||
|
||
| 字段名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| PointId | uniqueidentifier | ✅ | 主键 |
|
||
| DeviceId | uniqueidentifier | ✅ | 关联 Base_Device.DeviceId |
|
||
| Mc4DeviceId | int | ✅ | MC4.0 设备ID |
|
||
| PointIndex | int | ✅ | 点索引（MC4.0中的index） |
|
||
| PointType | int | | 点类型（MC4.0中的type） |
|
||
| PointTag | nvarchar(100) | | 点标签 |
|
||
| PointName | nvarchar(100) | ✅ | 点名称 |
|
||
| PointDesc | nvarchar(200) | | 点描述 |
|
||
| Unit | nvarchar(50) | | 单位（如 ℃, %, V） |
|
||
| IsControlPoint | int | | 是否是控制点：0=只读, 1=可写 |
|
||
| Mc4Option | nvarchar(500) | | MC4.0 option 原始JSON |
|
||
| Enable | int | | 启用状态 |
|
||
| CreateDate | datetime | | 创建时间 |
|
||
|
||
#### 3.1.3 设备数据记录表 (IoT_DeviceData) 【仅用于历史归档】
|
||
|
||
> **⚠️ 重要设计变更**：实时数据**不入库**，直接通过SignalR推送给前端展示。本表仅用于存储**历史归档数据**（如每小时/每天保存一次快照）。
|
||
>
|
||
> **原因**：若每次轮询都入库，100设备×10点×每30秒轮询 = 288万条/天，SQL Server单表性能会急剧下降。
|
||
|
||
| 字段名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| DataId | uniqueidentifier | ✅ | 主键 |
|
||
| DeviceId | uniqueidentifier | ✅ | 关联设备 |
|
||
| PointId | uniqueidentifier | ✅ | 关联点 |
|
||
| PointValue | float | | 点值 |
|
||
| UpdateTime | datetime | ✅ | MC4.0 数据更新时间 |
|
||
| Interval | int | | 距离上一次采集间隔（毫秒） |
|
||
| CreateDate | datetime | | 记录入库时间 |
|
||
| ArchiveType | int | | 归档类型：1=小时归档, 2=日归档 |
|
||
|
||
#### 3.1.4 告警记录表 (IoT_Alarm)
|
||
|
||
| 字段名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| AlarmId | uniqueidentifier | ✅ | 主键 |
|
||
| Mc4AlarmId | nvarchar(64) | ✅ | MC4.0 告警ID |
|
||
| DeviceId | uniqueidentifier | | 关联设备 |
|
||
| AlarmType | int | | 告警类型 |
|
||
| AlarmLevel | int | | 告警等级：1=提示, 2=普通, 3=重要, 4=紧急 |
|
||
| AlarmDesc | nvarchar(500) | | 告警描述 |
|
||
| AlarmValue | float | | 触发值 |
|
||
| StartTime | datetime | ✅ | 告警开始时间 |
|
||
| EndTime | datetime | | 告警结束时间 |
|
||
| ConfirmTime | datetime | | 确认时间 |
|
||
| ConfirmUser | nvarchar(50) | | 确认人 |
|
||
| State | int | | 状态：1=未确认, 2=已确认, 3=已结束 |
|
||
| IsDischarge | int | | 是否是放电告警 |
|
||
| Mc4Option | nvarchar(500) | | MC4.0 原始JSON |
|
||
| CreateDate | datetime | | 入库时间 |
|
||
|
||
### 3.2 建表SQL (SQL Server)
|
||
|
||
```sql
|
||
-- ============================================
|
||
-- 统一设备主表（与视频监控方案共用）
|
||
-- ============================================
|
||
CREATE TABLE Base_Device (
|
||
DeviceId UNIQUEIDENTIFIER PRIMARY KEY DEFAULT NEWID(),
|
||
DeviceName NVARCHAR(100) NOT NULL,
|
||
DeviceCategory INT NOT NULL, -- 1=视频监控, 2=采集网关
|
||
DeviceType INT, -- 细分类型（根据Category解释）
|
||
SourceId NVARCHAR(64) NOT NULL, -- 源系统设备ID（OwlDeviceId或Mc4DeviceId）
|
||
IpAddress NVARCHAR(50),
|
||
Port INT,
|
||
IsOnline INT DEFAULT 0,
|
||
Location NVARCHAR(200), -- 安装位置描述
|
||
Lat FLOAT, -- 纬度
|
||
Lng FLOAT, -- 经度
|
||
MapModelId NVARCHAR(100), -- 三维地图模型ID（VgoMap）
|
||
MapModelScale FLOAT DEFAULT 1.0, -- 三维模型缩放比例
|
||
MapModelRotation NVARCHAR(100), -- 三维模型旋转角度（JSON）
|
||
Enable INT DEFAULT 1,
|
||
Remark NVARCHAR(500),
|
||
CreateID INT,
|
||
Creator NVARCHAR(30),
|
||
CreateDate DATETIME DEFAULT GETDATE(),
|
||
ModifyID INT,
|
||
Modifier NVARCHAR(30),
|
||
ModifyDate DATETIME
|
||
);
|
||
CREATE INDEX IX_Base_Device_Category ON Base_Device(DeviceCategory);
|
||
CREATE INDEX IX_Base_Device_SourceId ON Base_Device(SourceId);
|
||
CREATE INDEX IX_Base_Device_IsOnline ON Base_Device(IsOnline);
|
||
CREATE INDEX IX_Base_Device_MapModelId ON Base_Device(MapModelId);
|
||
|
||
-- ============================================
|
||
-- 采集网关设备扩展表
|
||
-- ============================================
|
||
CREATE TABLE Device_IoT_Ext (
|
||
ExtId UNIQUEIDENTIFIER PRIMARY KEY DEFAULT NEWID(),
|
||
DeviceId UNIQUEIDENTIFIER NOT NULL,
|
||
Mc4DeviceId INT NOT NULL,
|
||
ObjectType INT,
|
||
Tag NVARCHAR(100),
|
||
ParentId INT,
|
||
Mc4Option NVARCHAR(500),
|
||
FOREIGN KEY (DeviceId) REFERENCES Base_Device(DeviceId)
|
||
);
|
||
CREATE INDEX IX_Device_IoT_Ext_DeviceId ON Device_IoT_Ext(DeviceId);
|
||
CREATE INDEX IX_Device_IoT_Ext_Mc4DeviceId ON Device_IoT_Ext(Mc4DeviceId);
|
||
|
||
-- 设备点表
|
||
CREATE TABLE IoT_DevicePoint (
|
||
PointId UNIQUEIDENTIFIER PRIMARY KEY DEFAULT NEWID(),
|
||
DeviceId UNIQUEIDENTIFIER 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 INT DEFAULT 0,
|
||
Mc4Option NVARCHAR(500),
|
||
Enable INT DEFAULT 1,
|
||
CreateDate DATETIME DEFAULT GETDATE()
|
||
);
|
||
CREATE INDEX IX_IoT_DevicePoint_DeviceId ON IoT_DevicePoint(DeviceId);
|
||
CREATE INDEX IX_IoT_DevicePoint_Mc4DeviceId ON IoT_DevicePoint(Mc4DeviceId);
|
||
|
||
-- 设备数据记录表
|
||
CREATE TABLE IoT_DeviceData (
|
||
DataId UNIQUEIDENTIFIER PRIMARY KEY DEFAULT NEWID(),
|
||
DeviceId UNIQUEIDENTIFIER NOT NULL,
|
||
PointId UNIQUEIDENTIFIER NOT NULL,
|
||
PointValue FLOAT,
|
||
UpdateTime DATETIME NOT NULL,
|
||
Interval INT,
|
||
CreateDate DATETIME DEFAULT GETDATE()
|
||
);
|
||
CREATE INDEX IX_IoT_DeviceData_DeviceId ON IoT_DeviceData(DeviceId);
|
||
CREATE INDEX IX_IoT_DeviceData_PointId ON IoT_DeviceData(PointId);
|
||
CREATE INDEX IX_IoT_DeviceData_UpdateTime ON IoT_DeviceData(UpdateTime);
|
||
|
||
-- 告警记录表
|
||
CREATE TABLE IoT_Alarm (
|
||
AlarmId UNIQUEIDENTIFIER PRIMARY KEY DEFAULT NEWID(),
|
||
Mc4AlarmId NVARCHAR(64) NOT NULL,
|
||
DeviceId UNIQUEIDENTIFIER,
|
||
AlarmType INT,
|
||
AlarmLevel INT,
|
||
AlarmDesc NVARCHAR(500),
|
||
AlarmValue FLOAT,
|
||
StartTime DATETIME NOT NULL,
|
||
EndTime DATETIME,
|
||
ConfirmTime DATETIME,
|
||
ConfirmUser NVARCHAR(50),
|
||
State INT DEFAULT 1,
|
||
IsDischarge INT DEFAULT 0,
|
||
Mc4Option NVARCHAR(500),
|
||
CreateDate DATETIME DEFAULT GETDATE()
|
||
);
|
||
CREATE INDEX IX_IoT_Alarm_Mc4AlarmId ON IoT_Alarm(Mc4AlarmId);
|
||
CREATE INDEX IX_IoT_Alarm_DeviceId ON IoT_Alarm(DeviceId);
|
||
CREATE INDEX IX_IoT_Alarm_State ON IoT_Alarm(State);
|
||
CREATE INDEX IX_IoT_Alarm_StartTime ON IoT_Alarm(StartTime);
|
||
```
|
||
|
||
---
|
||
|
||
## 四、Vol.Pro 后端扩展方案
|
||
|
||
### 4.1 代码生成步骤
|
||
|
||
使用 Vol.Pro 代码生成器自动生成模块的 CRUD 代码：
|
||
1. **Base_Device**（统一设备主表，含视频监控+采集网关设备）
|
||
2. **Device_IoT_Ext**（采集设备扩展信息）
|
||
3. **IoT_DevicePoint**（设备点表）
|
||
4. **IoT_DeviceData**（数据记录）
|
||
5. **IoT_Alarm**（告警记录）
|
||
|
||
### 4.2 MC4.0 对接服务 (Mc4ApiService)
|
||
|
||
**新建独立服务文件**（不修改任何框架代码）：
|
||
|
||
```csharp
|
||
// 文件位置：api_sqlsugar/Warehouse/Services/Mc4/Mc4ApiService.cs
|
||
|
||
/// <summary>
|
||
/// MC4.0 采集网关对接服务
|
||
/// </summary>
|
||
public interface IMc4ApiService : IDependency
|
||
{
|
||
/// <summary>获取/刷新 MC4.0 Token</summary>
|
||
Task<string> GetTokenAsync();
|
||
|
||
/// <summary>同步 MC4.0 对象树（区域+设备）</summary>
|
||
Task<List<Mc4ObjectNode>> SyncObjectTreeAsync();
|
||
|
||
/// <summary>同步指定设备的点表</summary>
|
||
Task<List<Mc4DevicePoint>> SyncDevicePointsAsync(int mc4DeviceId);
|
||
|
||
/// <summary>获取设备实时数据（所有点）</summary>
|
||
Task<List<Mc4PointValue>> GetDeviceRealtimeDataAsync(int mc4DeviceId);
|
||
|
||
/// <summary>批量获取指定点的实时数据</summary>
|
||
Task<List<Mc4PointValue>> GetMultiPointValuesAsync(List<Mc4PointQuery> points);
|
||
|
||
/// <summary>控制设备点值（反向控制）</summary>
|
||
Task<bool> SetPointValueAsync(int mc4DeviceId, int pointIndex, double value);
|
||
|
||
/// <summary>查询告警列表</summary>
|
||
Task<Mc4AlarmPageResult> QueryAlarmsAsync(Mc4AlarmQueryInput input);
|
||
|
||
/// <summary>确认告警</summary>
|
||
Task<bool> ConfirmAlarmAsync(string alarmId);
|
||
|
||
/// <summary>结束告警</summary>
|
||
Task<bool> EndAlarmAsync(string alarmId);
|
||
}
|
||
```
|
||
|
||
**实现要点**：
|
||
1. **新建文件**，实现 `IDependency`，Autofac 自动注入
|
||
2. 使用 `IHttpClientFactory` 创建指向 MC4.0（端口3000）的 HTTP 客户端
|
||
3. Token 获取后缓存到内存，失效前自动刷新
|
||
4. 所有返回值统一转换为 Vol.Pro 的 `WebResponseContent` 格式
|
||
|
||
### 4.3 扩展 API 控制器 (IoTStreamController)
|
||
|
||
**新建独立 Controller**（不修改任何框架代码）：
|
||
|
||
```csharp
|
||
// 文件位置：api_sqlsugar/Warehouse/Controllers/IoTStreamController.cs
|
||
|
||
[Route("api/IoTStream")]
|
||
[JWTAuthorize]
|
||
public class IoTStreamController : VolController
|
||
{
|
||
private readonly IMc4ApiService _mc4Api;
|
||
private readonly IBase_DeviceService _deviceService;
|
||
|
||
public IoTStreamController(
|
||
IMc4ApiService mc4Api,
|
||
IBase_DeviceService deviceService)
|
||
{
|
||
_mc4Api = mc4Api;
|
||
_deviceService = deviceService;
|
||
}
|
||
|
||
/// <summary>
|
||
/// 同步 MC4.0 对象树（区域+设备）
|
||
/// </summary>
|
||
[HttpPost, Route("SyncTree")]
|
||
public async Task<ActionResult> SyncTree()
|
||
{
|
||
var nodes = await _mc4Api.SyncObjectTreeAsync();
|
||
// 将对象树写入 Base_Device 主表（DeviceCategory=2采集网关，DeviceType=1区域/2设备）
|
||
// ... 同步逻辑
|
||
return Json(new WebResponseContent().OK(null, $"同步完成，共{nodes.Count}个节点"));
|
||
}
|
||
|
||
/// <summary>
|
||
/// 同步指定设备的点表
|
||
/// </summary>
|
||
[HttpPost, Route("SyncPoints")]
|
||
public async Task<ActionResult> SyncPoints([FromBody] SyncPointsInput input)
|
||
{
|
||
var device = await _deviceService.GetDeviceByIdAsync(input.DeviceId);
|
||
if (device == null) return Json(new WebResponseContent().Error("设备不存在"));
|
||
|
||
var points = await _mc4Api.SyncDevicePointsAsync(device.Mc4DeviceId);
|
||
return Json(new WebResponseContent().OK(null, points));
|
||
}
|
||
|
||
/// <summary>
|
||
/// 获取设备实时数据
|
||
/// </summary>
|
||
[HttpPost, Route("GetRealtime")]
|
||
public async Task<ActionResult> GetRealtime([FromBody] GetRealtimeInput input)
|
||
{
|
||
var device = await _deviceService.GetDeviceByIdAsync(input.DeviceId);
|
||
if (device == null) return Json(new WebResponseContent().Error("设备不存在"));
|
||
|
||
var data = await _mc4Api.GetDeviceRealtimeDataAsync(device.Mc4DeviceId);
|
||
return Json(new WebResponseContent().OK(null, data));
|
||
}
|
||
|
||
/// <summary>
|
||
/// 设备反向控制
|
||
/// </summary>
|
||
[HttpPost, Route("Control")]
|
||
[ApiActionPermission("Base_Device", ActionPermissionOptions.Update)]
|
||
public async Task<ActionResult> Control([FromBody] ControlInput input)
|
||
{
|
||
var device = await _deviceService.GetDeviceByIdAsync(input.DeviceId);
|
||
if (device == null) return Json(new WebResponseContent().Error("设备不存在"));
|
||
|
||
var success = await _mc4Api.SetPointValueAsync(
|
||
device.Mc4DeviceId, input.PointIndex, input.Value);
|
||
|
||
return Json(success
|
||
? new WebResponseContent().OK(null, "控制指令已下发")
|
||
: new WebResponseContent().Error("控制失败"));
|
||
}
|
||
|
||
/// <summary>
|
||
/// 查询告警列表
|
||
/// </summary>
|
||
[HttpPost, Route("GetAlarms")]
|
||
public async Task<ActionResult> GetAlarms([FromBody] AlarmQueryInput input)
|
||
{
|
||
var result = await _mc4Api.QueryAlarmsAsync(new Mc4AlarmQueryInput
|
||
{
|
||
Sids = input.DeviceIds,
|
||
From = input.StartTime,
|
||
To = input.EndTime,
|
||
ConfirmState = input.ConfirmState,
|
||
EndState = input.EndState,
|
||
Skip = (input.Page - 1) * input.Rows,
|
||
Limit = input.Rows
|
||
});
|
||
|
||
return Json(new WebResponseContent().OK(null, new {
|
||
total = result.Total,
|
||
rows = result.List
|
||
}));
|
||
}
|
||
|
||
/// <summary>
|
||
/// 确认告警
|
||
/// </summary>
|
||
[HttpPost, Route("ConfirmAlarm")]
|
||
public async Task<ActionResult> ConfirmAlarm([FromBody] AlarmActionInput input)
|
||
{
|
||
var success = await _mc4Api.ConfirmAlarmAsync(input.AlarmId);
|
||
return Json(success
|
||
? new WebResponseContent().OK()
|
||
: new WebResponseContent().Error("确认失败"));
|
||
}
|
||
|
||
/// <summary>
|
||
/// 手动触发告警轮询（用于前端主动刷新）
|
||
/// </summary>
|
||
[HttpPost, Route("PollAlarms")]
|
||
public async Task<ActionResult> PollAlarms()
|
||
{
|
||
// 触发一次告警轮询任务
|
||
// ... 调用后台Job或直接查询MC4.0
|
||
return Json(new WebResponseContent().OK(null, "轮询已触发"));
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.4 告警轮询任务 (Quartz Job)
|
||
|
||
MC4.0 不支持主动推送告警，Vol.Pro 后端通过 **Quartz 定时任务** 定时轮询：
|
||
|
||
```csharp
|
||
// 文件位置：api_sqlsugar/Warehouse/Jobs/AlarmPollJob.cs
|
||
// （新建文件，实现 IDependency）
|
||
|
||
/// <summary>
|
||
/// MC4.0 告警轮询定时任务（每10秒执行一次）
|
||
/// </summary>
|
||
public class AlarmPollJob : IDependency
|
||
{
|
||
private readonly IMc4ApiService _mc4Api;
|
||
private readonly IIoT_AlarmService _alarmService;
|
||
private readonly IHubContext<IoTDataHub> _hubContext;
|
||
|
||
public AlarmPollJob(
|
||
IMc4ApiService mc4Api,
|
||
IIoT_AlarmService alarmService,
|
||
IHubContext<IoTDataHub> hubContext)
|
||
{
|
||
_mc4Api = mc4Api;
|
||
_alarmService = alarmService;
|
||
_hubContext = hubContext;
|
||
}
|
||
|
||
public async Task ExecuteAsync()
|
||
{
|
||
// 1. 查询最近30秒内的告警（缩短窗口匹配轮询间隔）
|
||
var result = await _mc4Api.QueryAlarmsAsync(new Mc4AlarmQueryInput
|
||
{
|
||
From = DateTime.Now.AddSeconds(-30).ToString("yyyy-MM-dd HH:mm:ss"),
|
||
To = DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss"),
|
||
Limit = 100
|
||
});
|
||
|
||
// 2. 过滤已入库的新告警（按Mc4AlarmId去重）
|
||
var newAlarms = await FilterNewAlarmsAsync(result.List);
|
||
|
||
// 3. 写入 IoT_Alarm 表
|
||
foreach (var alarm in newAlarms)
|
||
{
|
||
await _alarmService.AddAsync(alarm);
|
||
}
|
||
|
||
// 4. 通过 SignalR 按设备分组推送给前端（避免全量广播）
|
||
foreach (var alarm in newAlarms)
|
||
{
|
||
if (alarm.DeviceId.HasValue)
|
||
{
|
||
await _hubContext.Clients.Group($"device_{alarm.DeviceId}")
|
||
.SendAsync("NewAlarm", alarm);
|
||
}
|
||
}
|
||
|
||
// 5. 同时推送给告警管理员组
|
||
if (newAlarms.Any())
|
||
{
|
||
await _hubContext.Clients.Group("alarm_admin")
|
||
.SendAsync("NewAlarms", newAlarms);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.5 实时数据轮询任务（Quartz Job）
|
||
|
||
> **设计变更**：实时数据**不入库**，直接通过SignalR推送给前端展示。
|
||
|
||
```csharp
|
||
// 文件位置：api_sqlsugar/Warehouse/Jobs/RealtimeDataPollJob.cs
|
||
// （新建文件，实现 IDependency）
|
||
|
||
/// <summary>
|
||
/// 实时数据轮询任务（每5秒执行一次）
|
||
/// 注意：数据不入库，仅通过SignalR推送给前端
|
||
/// </summary>
|
||
public class RealtimeDataPollJob : IDependency
|
||
{
|
||
private readonly IMc4ApiService _mc4Api;
|
||
private readonly IBase_DeviceService _deviceService;
|
||
private readonly IHubContext<IoTDataHub> _hubContext;
|
||
|
||
public RealtimeDataPollJob(
|
||
IMc4ApiService mc4Api,
|
||
IBase_DeviceService deviceService,
|
||
IHubContext<IoTDataHub> hubContext)
|
||
{
|
||
_mc4Api = mc4Api;
|
||
_deviceService = deviceService;
|
||
_hubContext = hubContext;
|
||
}
|
||
|
||
public async Task ExecuteAsync()
|
||
{
|
||
// 1. 获取所有启用的采集网关设备
|
||
var devices = await _deviceService.GetDevicesAsync(
|
||
d => d.DeviceCategory == 2 && d.Enable == 1);
|
||
|
||
// 2. 批量获取实时数据（使用批量接口减少调用次数）
|
||
foreach (var device in devices)
|
||
{
|
||
var data = await _mc4Api.GetDeviceRealtimeDataAsync(device.Mc4DeviceId);
|
||
|
||
// 3. 直接SignalR推送给订阅了该设备的客户端（不入库！）
|
||
await _hubContext.Clients.Group($"device_{device.DeviceId}")
|
||
.SendAsync("ReceiveRealtimeData", new {
|
||
deviceId = device.DeviceId,
|
||
deviceName = device.DeviceName,
|
||
points = data,
|
||
updateTime = DateTime.Now
|
||
});
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
> **数据归档策略**（可选）：
|
||
> 如需保存历史数据，可另建一个**每小时执行一次**的归档Job，将数据写入`IoT_DeviceData`表（ArchiveType=1小时归档）。
|
||
|
||
### 4.6 MC4.0 请求频率控制
|
||
|
||
为防止高频轮询触发MC4.0限流，在`Mc4ApiService`中实现请求频率控制：
|
||
|
||
```csharp
|
||
public class Mc4ApiService : IMc4ApiService
|
||
{
|
||
private static readonly SemaphoreSlim _rateLimiter = new SemaphoreSlim(2, 2); // 每秒最多2个并发请求
|
||
|
||
private async Task<T> ExecuteWithRateLimitAsync<T>(Func<Task<T>> action)
|
||
{
|
||
await _rateLimiter.WaitAsync();
|
||
try
|
||
{
|
||
return await action();
|
||
}
|
||
finally
|
||
{
|
||
// 500ms后释放，确保每秒不超过2次请求
|
||
await Task.Delay(500);
|
||
_rateLimiter.Release();
|
||
}
|
||
}
|
||
|
||
public async Task<List<Mc4PointValue>> GetDeviceRealtimeDataAsync(int mc4DeviceId)
|
||
{
|
||
return await ExecuteWithRateLimitAsync(async () =>
|
||
{
|
||
// 实际HTTP调用
|
||
});
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.7 SignalR 实时数据推送
|
||
|
||
warehouse 前端需要实时接收数据更新和告警推送，Vol.Pro 后端通过 SignalR 实现：
|
||
|
||
```csharp
|
||
// 文件位置：api_sqlsugar/Warehouse/Hubs/IoTDataHub.cs
|
||
// （新建文件）
|
||
|
||
public interface IIoTDataHub
|
||
{
|
||
Task ReceiveRealtimeData(List<IoTDeviceDataDto> data);
|
||
Task ReceiveNewAlarm(IoTAlarmDto alarm); // 单条告警推送（按设备分组）
|
||
Task ReceiveNewAlarms(List<IoTAlarmDto> alarms); // 批量告警推送（管理员组）
|
||
Task DeviceControlResult(string deviceId, bool success, string message);
|
||
}
|
||
|
||
[Authorize]
|
||
public class IoTDataHub : Hub<IIoTDataHub>
|
||
{
|
||
/// <summary>订阅指定设备的实时数据和告警</summary>
|
||
public async Task SubscribeDevice(string deviceId)
|
||
{
|
||
await Groups.AddToGroupAsync(Context.ConnectionId, $"device_{deviceId}");
|
||
}
|
||
|
||
public async Task UnsubscribeDevice(string deviceId)
|
||
{
|
||
await Groups.RemoveFromGroupAsync(Context.ConnectionId, $"device_{deviceId}");
|
||
}
|
||
|
||
/// <summary>订阅告警管理员组（接收所有告警）</summary>
|
||
public async Task SubscribeAlarmAdmin()
|
||
{
|
||
await Groups.AddToGroupAsync(Context.ConnectionId, "alarm_admin");
|
||
}
|
||
|
||
public async Task UnsubscribeAlarmAdmin()
|
||
{
|
||
await Groups.RemoveFromGroupAsync(Context.ConnectionId, "alarm_admin");
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 五、前端对接方案
|
||
|
||
### 5.1 warehouse 用户端改造
|
||
|
||
warehouse 需要实现以下功能模块：
|
||
|
||
1. **实时数据看板**（新增页面或扩展现有页面）：
|
||
- 展示设备列表和当前实时数据（温湿度、电压等）
|
||
- 使用 SignalR 实时接收数据更新
|
||
- 支持按区域筛选设备
|
||
|
||
2. **设备控制面板**（新增）：
|
||
- 显示可控制的设备点（如空调开关、温度设定）
|
||
- 提供开关、滑块、输入框等控制组件
|
||
- 调用 `/api/IoTStream/Control` 下发控制指令
|
||
|
||
3. **告警信息面板**（新增或扩展现有告警模块）：
|
||
- 实时展示最新告警（通过 SignalR 推送）
|
||
- 支持告警确认、结束操作
|
||
- 告警历史查询
|
||
|
||
**warehouse 前端 API 调用示例**：
|
||
```typescript
|
||
import http from '@/api/http'
|
||
|
||
// 获取设备列表（统一设备主表，过滤DeviceCategory=2的采集网关设备）
|
||
const getDevices = () => {
|
||
return http.post('/api/Base_Device/GetPageData', {
|
||
page: 1, rows: 100, sort: 'CreateDate', order: 'desc',
|
||
wheres: JSON.stringify([{ name: 'DeviceCategory', value: '2', displayType: 'int' }])
|
||
})
|
||
}
|
||
|
||
// 获取设备实时数据
|
||
const getRealtimeData = (deviceId: string) => {
|
||
return http.post('/api/IoTStream/GetRealtime', { deviceId })
|
||
}
|
||
|
||
// 控制设备
|
||
const controlDevice = (deviceId: string, pointIndex: number, value: number) => {
|
||
return http.post('/api/IoTStream/Control', { deviceId, pointIndex, value })
|
||
}
|
||
|
||
// 查询告警
|
||
const getAlarms = (params: any) => {
|
||
return http.post('/api/IoTStream/GetAlarms', params)
|
||
}
|
||
|
||
// 确认告警
|
||
const confirmAlarm = (alarmId: string) => {
|
||
return http.post('/api/IoTStream/ConfirmAlarm', { alarmId })
|
||
}
|
||
|
||
// SignalR 连接
|
||
import * as signalR from '@microsoft/signalr'
|
||
|
||
const connection = new signalR.HubConnectionBuilder()
|
||
.withUrl('/hubs/iotData')
|
||
.withAutomaticReconnect()
|
||
.build()
|
||
|
||
// 连接成功后订阅当前页面展示的设备
|
||
connection.start().then(() => {
|
||
// 订阅设备实时数据（按设备分组）
|
||
const deviceIds = ['guid1', 'guid2'] // 当前页面展示的设备ID
|
||
deviceIds.forEach(id => {
|
||
connection.invoke('SubscribeDevice', id)
|
||
})
|
||
|
||
// 告警管理页面订阅管理员组
|
||
connection.invoke('SubscribeAlarmAdmin')
|
||
})
|
||
|
||
connection.on('ReceiveRealtimeData', (data) => {
|
||
// 更新对应设备的实时数据到页面
|
||
console.log(`设备${data.deviceName}数据更新:`, data.points)
|
||
})
|
||
|
||
connection.on('ReceiveNewAlarm', (alarm) => {
|
||
// 单条告警通知（来自订阅的设备）
|
||
ElNotification({
|
||
title: '新告警',
|
||
message: `${alarm.deviceName}: ${alarm.alarmDesc}`,
|
||
type: 'warning'
|
||
})
|
||
})
|
||
|
||
connection.on('ReceiveNewAlarms', (alarms) => {
|
||
// 批量告警（管理员组）
|
||
// 更新告警列表
|
||
})
|
||
```
|
||
|
||
### 5.2 管理端 (web.vite) 扩展
|
||
|
||
通过 Vol.Pro 代码生成器生成的 CRUD 页面，扩展以下功能：
|
||
|
||
1. **设备列表页扩展**（`extension/warehouse/Base_Device.jsx`）：
|
||
- 添加"同步对象树"按钮（仅对DeviceCategory=2的设备显示）
|
||
- 添加"同步点表"操作列
|
||
- 添加"三维地图定位"操作（可跳转地图并高亮对应模型）
|
||
- 添加"查看实时数据"按钮
|
||
|
||
2. **告警列表页扩展**：
|
||
- 添加"确认"和"结束"操作按钮
|
||
- 告警等级颜色标识（紧急=红色，重要=橙色）
|
||
|
||
---
|
||
|
||
## 六、关键 API 接口文档
|
||
|
||
### 6.1 Vol.Pro 后端对外接口
|
||
|
||
#### 6.1.1 同步对象树
|
||
|
||
```
|
||
POST /api/IoTStream/SyncTree
|
||
Authorization: Bearer <Vol.Pro JWT Token>
|
||
|
||
Response:
|
||
{
|
||
"status": true,
|
||
"message": "同步完成，共15个节点",
|
||
"data": { "total": 15, "devices": 8, "areas": 7 }
|
||
}
|
||
```
|
||
|
||
#### 6.1.2 获取设备实时数据
|
||
|
||
```
|
||
POST /api/IoTStream/GetRealtime
|
||
Authorization: Bearer <Vol.Pro JWT Token>
|
||
|
||
Request:
|
||
{
|
||
"deviceId": "guid"
|
||
}
|
||
|
||
Response:
|
||
{
|
||
"status": true,
|
||
"message": "ok",
|
||
"data": [
|
||
{ "index": 1, "name": "温度", "value": 24.5, "unit": "℃", "time": "2026-04-29 10:30:00" },
|
||
{ "index": 2, "name": "湿度", "value": 65.0, "unit": "%", "time": "2026-04-29 10:30:00" }
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 6.1.3 设备反向控制
|
||
|
||
```
|
||
POST /api/IoTStream/Control
|
||
Authorization: Bearer <Vol.Pro JWT Token>
|
||
|
||
Request:
|
||
{
|
||
"deviceId": "guid",
|
||
"pointIndex": 10,
|
||
"value": 1
|
||
}
|
||
|
||
Response:
|
||
{
|
||
"status": true,
|
||
"message": "控制指令已下发"
|
||
}
|
||
```
|
||
|
||
#### 6.1.4 查询告警
|
||
|
||
```
|
||
POST /api/IoTStream/GetAlarms
|
||
Authorization: Bearer <Vol.Pro JWT Token>
|
||
|
||
Request:
|
||
{
|
||
"deviceIds": [],
|
||
"startTime": "2026-04-28 00:00:00",
|
||
"endTime": "2026-04-29 23:59:59",
|
||
"confirmState": 1,
|
||
"endState": 0,
|
||
"page": 1,
|
||
"rows": 20
|
||
}
|
||
|
||
Response:
|
||
{
|
||
"status": true,
|
||
"message": "ok",
|
||
"data": {
|
||
"total": 5,
|
||
"rows": [
|
||
{
|
||
"alarmId": "guid",
|
||
"deviceName": "机房空调A",
|
||
"alarmDesc": "温度过高告警",
|
||
"alarmValue": 32.5,
|
||
"level": 3,
|
||
"startTime": "2026-04-29 10:15:00",
|
||
"state": 1
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.2 MC4.0 内部接口（Vol.Pro 后端调用）
|
||
|
||
| 接口 | 说明 | 用途 |
|
||
|------|------|------|
|
||
| `POST /api/central/auth/login` | 登录获取 Token | 认证 |
|
||
| `POST /api/central/object/tree` | 对象树 | 同步设备 |
|
||
| `POST /api/central/device/point/get` | 设备点表 | 同步点表 |
|
||
| `POST /api/central/device/point/value/get` | 设备实时数据 | 读数据 |
|
||
| `POST /api/central/point/multi/value/get` | 批量点值 | 批量读 |
|
||
| `POST /api/central/point/value/set` | 设置点值 | 反向控制 |
|
||
| `POST /api/central/alarm/query` | 告警查询 | 告警同步 |
|
||
| `POST /api/central/alarm/confirm` | 确认告警 | 告警处理 |
|
||
| `POST /api/central/alarm/end` | 结束告警 | 告警处理 |
|
||
|
||
---
|
||
|
||
## 七、实施计划
|
||
|
||
### 阶段一：数据库与代码生成（2天）
|
||
|
||
1. 执行建表 SQL 创建 4 张表
|
||
2. 使用 Vol.Pro 代码生成器生成 CRUD 代码
|
||
3. 验证生成后的增删改查功能正常
|
||
|
||
### 阶段二：MC4.0 对接服务（3天）
|
||
|
||
**新建独立文件**：
|
||
1. 创建 `Warehouse/Services/Mc4/IMc4ApiService.cs`（接口）
|
||
2. 创建 `Warehouse/Services/Mc4/Mc4ApiService.cs`（实现）
|
||
3. 实现 Token 管理（登录/缓存/刷新）
|
||
4. 实现对象树同步、点表同步、实时数据获取
|
||
5. 实现设备控制、告警查询
|
||
6. 创建 `Warehouse/Controllers/IoTStreamController.cs`（全新 Controller）
|
||
|
||
### 阶段三：实时数据与告警推送（2天）
|
||
|
||
1. 创建 `Warehouse/Hubs/IoTDataHub.cs`（SignalR Hub，支持按设备分组）
|
||
2. 创建 `Warehouse/Jobs/RealtimeDataPollJob.cs`（实时数据轮询，每5秒，**不入库仅推送**）
|
||
3. 创建 `Warehouse/Jobs/AlarmPollJob.cs`（告警轮询，每10秒）
|
||
4. 配置定时任务和频率控制（每秒最多2次MC4.0请求）
|
||
5. 实现SignalR分组推送逻辑
|
||
|
||
### 阶段四：管理端前端扩展（1天）
|
||
|
||
1. 扩展设备列表页（同步按钮、实时数据查看）
|
||
2. 扩展告警列表页（确认/结束操作）
|
||
|
||
### 阶段五：warehouse 用户端开发（3天）
|
||
|
||
1. 开发实时数据看板页面（设备列表 + 实时数值展示）
|
||
2. 开发设备控制面板（开关、滑块、输入框）
|
||
3. 开发告警信息面板（实时告警 + 历史查询）
|
||
4. 集成 SignalR 客户端，实现实时数据接收
|
||
|
||
### 阶段六：联调测试（2天）
|
||
|
||
1. MC4.0 设备接入测试（温湿度、空调等）
|
||
2. 实时数据读取测试（验证SignalR推送，不入库）
|
||
3. 反向控制测试（空调开关、温度设定）
|
||
4. 告警轮询与推送测试（验证10秒轮询+分组推送）
|
||
5. 请求频率控制测试（验证每秒不超过2次请求）
|
||
6. 多设备并发测试
|
||
|
||
**总计预计工期**: 16个工作日（含3天缓冲）
|
||
|
||
---
|
||
|
||
## 八、风险与注意事项
|
||
|
||
### 8.1 MC4.0 API 限制
|
||
|
||
1. **轮询频率限制**: MC4.0 可能对接口调用频率有限制，已通过`SemaphoreSlim`实现每秒最多2次请求的频率控制
|
||
2. **Token 有效期**: 文档未明确 Token 有效期，需实测确认，建议每次请求前检查 Token 是否过期
|
||
3. **无主动推送**: MC4.0 仅支持查询式接口，实时数据和告警都需要轮询获取
|
||
|
||
### 8.2 数据同步策略
|
||
|
||
1. **对象树同步**: 建议在管理端提供手动同步按钮，MC4.0 设备变更时手动触发
|
||
2. **点表同步**: 在对象树同步后，对每个设备自动同步点表
|
||
3. **⚠️ 实时数据不入库**: 实时数据直接通过SignalR推送给前端，**不写入`IoT_DeviceData`表**
|
||
4. **历史归档**（可选）: 如需保存历史数据，可配置每小时/每天归档Job，将数据写入`IoT_DeviceData`表（ArchiveType标记归档类型）
|
||
|
||
### 8.3 性能建议
|
||
|
||
1. **批量查询**: 使用 `/api/central/point/multi/value/get` 批量获取点值，减少接口调用次数
|
||
2. **数据缓存**: 对不频繁变化的数据（如设备列表、点表）做 Redis 缓存
|
||
3. **SignalR 分组**: 前端只订阅当前页面展示的设备，避免不必要的推送
|
||
4. **告警去重**: 轮询到的告警通过 `Mc4AlarmId` 去重，避免重复入库
|
||
5. **请求频率控制**: `Mc4ApiService`中已实现每秒最多2次并发请求的限制
|
||
|
||
### 8.4 安全建议
|
||
|
||
1. MC4.0 的登录密码建议配置在 `appsettings.json` 的机密配置段
|
||
2. 设备控制接口需要权限校验（`[ApiActionPermission]`）
|
||
3. MC4.0 的 Token 缓存需加密存储
|
||
|
||
---
|
||
|
||
## 附录A：统一设备管理与三维地图标记
|
||
|
||
### A.1 统一设备管理设计
|
||
|
||
本方案与视频监控方案共用 **`Base_Device` 统一设备主表**，实现所有设备的集中管理：
|
||
|
||
| 设备大类 (DeviceCategory) | 细分类型 (DeviceType) | 扩展表 | 对接系统 |
|
||
|--------------------------|----------------------|--------|----------|
|
||
| 1 = 视频监控 | 1=IPC, 2=NVR, 3=Platform | `Device_Video_Ext` | Owl + ZLMediaKit |
|
||
| 2 = 采集网关 | 1=区域, 2=设备(见MC4.0类型表) | `Device_IoT_Ext` | MC4.0 采集网关 |
|
||
|
||
**统一查询示例**：
|
||
```sql
|
||
-- 查询所有设备（含视频监控+采集网关）
|
||
SELECT * FROM Base_Device WHERE Enable = 1
|
||
|
||
-- 查询所有视频监控设备
|
||
SELECT * FROM Base_Device WHERE DeviceCategory = 1
|
||
|
||
-- 查询所有采集网关设备
|
||
SELECT * FROM Base_Device WHERE DeviceCategory = 2
|
||
|
||
-- 联查设备+视频扩展信息
|
||
SELECT d.*, v.ChannelCount, v.Protocol
|
||
FROM Base_Device d
|
||
LEFT JOIN Device_Video_Ext v ON d.DeviceId = v.DeviceId
|
||
WHERE d.DeviceCategory = 1
|
||
|
||
-- 联查设备+采集扩展信息
|
||
SELECT d.*, i.Mc4DeviceId, i.ObjectType
|
||
FROM Base_Device d
|
||
LEFT JOIN Device_IoT_Ext i ON d.DeviceId = i.DeviceId
|
||
WHERE d.DeviceCategory = 2
|
||
```
|
||
|
||
### A.2 三维地图标记 (VgoMap)
|
||
|
||
warehouse 前端使用 **VgoMap** 三维地图引擎，设备需要在地图上进行三维标记。
|
||
|
||
#### A.2.1 MapModelId 字段说明
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| **MapModelId** | nvarchar(100) | 三维地图中对应模型的唯一标识符 |
|
||
| **MapModelScale** | float | 模型缩放比例，默认1.0 |
|
||
| **MapModelRotation** | nvarchar(100) | 模型旋转角度，JSON格式 `{"x":0,"y":90,"z":0}` |
|
||
|
||
**配置流程**：
|
||
1. 在VgoMap三维地图编辑器中，为每个设备位置放置一个模型（如摄像头图标、传感器图标）
|
||
2. 记录每个模型的ID（VgoMap提供的唯一标识）
|
||
3. 在Vol.Pro管理端的设备编辑页面中，填写对应设备的`MapModelId`
|
||
4. 可选配置缩放比例和旋转角度
|
||
|
||
#### A.2.2 前端三维地图集成示例
|
||
|
||
```typescript
|
||
// warehouse 前端加载设备标记
|
||
const loadDeviceMarkers = async () => {
|
||
// 1. 从Vol.Pro后端获取所有设备（含MapModelId）
|
||
const res = await http.post('/api/Base_Device/GetPageData', {
|
||
page: 1, rows: 1000, wheres: JSON.stringify([{ name: 'Enable', value: '1' }])
|
||
});
|
||
|
||
const devices = res.rows;
|
||
|
||
// 2. 在VgoMap中根据MapModelId绑定设备数据
|
||
devices.forEach(device => {
|
||
if (device.MapModelId) {
|
||
// 绑定设备数据到地图模型
|
||
window.$map.setModelData(device.MapModelId, {
|
||
deviceId: device.DeviceId,
|
||
deviceName: device.DeviceName,
|
||
category: device.DeviceCategory,
|
||
isOnline: device.IsOnline
|
||
});
|
||
|
||
// 设置模型样式（在线/离线不同颜色）
|
||
const color = device.IsOnline === 1 ? '#67c23a' : '#f56c6c';
|
||
window.$map.setModelColor(device.MapModelId, color);
|
||
}
|
||
});
|
||
};
|
||
|
||
// 点击地图模型时显示设备详情
|
||
window.$map.on('modelClick', (e) => {
|
||
const deviceData = e.modelData;
|
||
if (deviceData) {
|
||
showDeviceDetail(deviceData.deviceId);
|
||
}
|
||
});
|
||
|
||
// 实时更新设备状态（通过SignalR）
|
||
connection.on('DeviceStatusChanged', (deviceId, isOnline) => {
|
||
const device = devices.find(d => d.DeviceId === deviceId);
|
||
if (device && device.MapModelId) {
|
||
const color = isOnline ? '#67c23a' : '#f56c6c';
|
||
window.$map.setModelColor(device.MapModelId, color);
|
||
}
|
||
});
|
||
```
|
||
|
||
#### A.2.3 管理端地图配置界面
|
||
|
||
在Vol.Pro管理端的设备编辑页面中，扩展地图配置表单：
|
||
|
||
```javascript
|
||
// extension/warehouse/Base_Device.jsx 中的扩展
|
||
methods: {
|
||
modelOpenAfter(row) {
|
||
// 在编辑表单中添加三维地图配置字段
|
||
this.editFormOptions.push([
|
||
{ title: '三维地图模型ID', field: 'MapModelId', type: 'text' },
|
||
{ title: '模型缩放比例', field: 'MapModelScale', type: 'number' },
|
||
{ title: '模型旋转角度', field: 'MapModelRotation', type: 'text' }
|
||
]);
|
||
}
|
||
}
|
||
```
|
||
|
||
### A.3 设备数据流汇总
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 统一设备数据流 │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ Base_Device (统一主表) │
|
||
│ ├─ DeviceCategory=1 → Device_Video_Ext → Owl/ZLM (视频流) │
|
||
│ └─ DeviceCategory=2 → Device_IoT_Ext → MC4.0 (温湿度/控制) │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ 三维地图 (VgoMap) │
|
||
│ └─ 所有设备通过 MapModelId 在地图上统一标记展示 │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
> **文档结束**
|
||
> **版本**: v1.0
|
||
> **最后更新**: 2026-04-29
|
||
> **状态**: 待主人确认后实施
|