# SecMPS 整合方案（最终版）：IntegrationGateway + 统一设备管理

> **版本**: v2.0  
> **日期**: 2026-05-15  
> **状态**: 待实施  
> **替代**: Vol.Pro_MC4.0_整合方案_v1.0、Vol.Pro_Owl_ZLMediaKit_整合方案_v1.0、Vol.Pro_统一设备管理_区域树与地图绑定方案_v1.0

---

## 一、总体架构

```
前端层
  web.vite 管理端（设备管理页+标准CRUD）  warehouse 大屏（Map/Live/IoT/Alarm）
         │ HTTP REST                                 │ HTTP REST + SignalR
         ▼                                            ▼
Vol.Pro 后端 (api_sqlsugar)
  DeviceManagerController / GatewayClient / 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
```

---

## 二、IntegrationGateway 设计

### 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
```

### 2.2 适配器能力矩阵

| 接口 | Owl | MC4.0 | 门禁(未来) |
|------|:---:|:-----:|:----------:|
| IHasOwnDeviceTree | ❌ | ✅ | ❌ |
| IHasFlatDevices | ✅ | ❌ | ✅ |
| IHasPoints | ❌ | ✅ | ❌ |
| IHasStreams | ✅ | ❌ | ❌ |
| IHasAlarms | ⚠️ | ✅ | ✅ |
| IAcceptsMetadataPush | ✅ | ❌ | ⚠️ |

### 2.3 双向同步引擎

| 方向 | 说明 | MC4.0 | Owl |
|------|------|-------|-----|
| PullToVolPro | 第三方→Vol.Pro | FullReplace | Merge |
| PushToSource | Vol.Pro→第三方 | 告警确认/控制 | 元数据/PTZ |
| Bidirectional | 先写第三方再更新本地 | 告警确认 | — |

### 2.4 Gateway API

```
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
```

---

## 三、数据模型

### 3.1 区域表 warehouse_regions（现有）

| 字段 | 说明 |
|------|------|
| Id | int PK |
| RegionName | nvarchar(255) |
| ParentId | int? (自引用树) |

### 3.2 统一设备主表 Base_Device（新建）

| 字段 | 类型 | 说明 |
|------|------|------|
| 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 | |

唯一约束: (AdapterCode, SourceId)

### 3.3 扩展表

- **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）

### 3.4 层级示例

```
warehouse_regions: 厂区 → 新库区 → 31号库房
Base_Device (RegionId=3):
  东北角高位摄像机          (Category=1)
  人员计数摄像机            (Category=1)
  动环采集器               (Category=2, IsParent=1)
  ├── 温湿度探头            (ParentDeviceId=采集器)
  ├── 空调控制器            (ParentDeviceId=采集器)
  ├── 除湿机                (ParentDeviceId=采集器)
  └── 紧急报警按钮          (ParentDeviceId=采集器)
```

---

## 四、管理端统一设备页面

### 4.1 布局

```
┌──────────────────┬───────────────────────────────────────┐
│  顶部工具栏       │                                       │
├──────────────────┼───────────────────────────────────────┤
│  左侧区域树       │  右侧设备列表                           │
│                  │                                       │
│  📁 厂区         │  区域: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-道闸 | 抬杆/落杆/查看记录 |

---

## 五、同步策略

### MC4.0 → 区域树+设备
- `type=1` 节点 → 名称匹配 warehouse_regions → 绑区或新建
- `type=2` 节点 → Upsert Base_Device, RegionId=叶子区域
- 模式: FullReplace, 频率限制: 2次/秒

### Owl → 设备
- `GET /devices` → Upsert Base_Device (Category=1, IsParent=1)
- `GET /channels` → Upsert Base_Device (ParentDeviceId=NVR)
- Owl 无区域概念 → RegionId=NULL, 管理员手动分配
- 模式: Merge

### 反方向写回

| 操作 | Owl | MC4.0 |
|------|:---:|:-----:|
| 设备改名 | ✅ PUT /devices/:id | ❌ |
| 告警确认 | ⚠️ | ✅ |
| 设备控制 | ✅ PTZ | ✅ 点位写值 |

---

## 六、部署拓扑

```
Docker: Owl+ZLM (:80,:5060)  │  Docker: MC4.0 (:3000)
                             │
              ┌──────────────┴──────────────┐
              │    IntegrationGateway :5100  │
              └──────────────┬──────────────┘
                             │
              ┌──────────────┴──────────────┐
              │      VolPro.WebApi :9100     │
              │      MySQL / Redis           │
              └──────────────┬──────────────┘
                             │
          ┌──────────────────┴──────────────────┐
          │ web.vite :9000    warehouse :9200    │
          └─────────────────────────────────────┘
```

---

## 七、实施路线

| 阶段 | 工期 | 内容 |
|------|------|------|
| Phase 0 | Day 1-2 | Gateway骨架 + Base_Device建表 + 代码生成 |
| 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 个工作日**

---

## 八、新增整合流程

以接入「海康门禁」为例：
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 天**

---

## 九、代码组织规范

| 代码类型 | 路径 | 被覆盖? |
|----------|------|:---:|
| 第三方对接 | IntegrationGateway/ | ❌ |
| 扩展Controller | Controllers/*/Partial/ | ❌ |
| Entity扩展 | DomainModels/*/partial/ | ❌ |
| 前端业务逻辑 | extension/warehouse/*.jsx | ❌ |
| 自定义页面 | views/warehouse/DeviceManager/ | ❌ |
| 自动生成代码 | 生成器默认路径 | ✅ |

---

> **文档结束**  
> **取代**: Vol.Pro_MC4.0_整合方案_v1.0、Vol.Pro_Owl_ZLMediaKit_整合方案_v1.0、Vol.Pro_统一设备管理_区域树与地图绑定方案_v1.0、Vol.Pro_整合项目_实施方案_v1.0