# Vol.Pro 统一设备管理：区域树 + 设备层级 + 地图绑定方案

> **版本**: v1.0  
> **日期**: 2026-05-15  
> **状态**: 待确认  
> **前置方案**: Vol.Pro_MC4.0_整合方案_v1.0、Vol.Pro_Owl_ZLMediaKit_整合方案_v1.0、IntegrationGateway 方案 A

---

## 一、需求定义

### 1.1 管理端呈现目标

在 web.vite 实现统一设备管理界面，形态为左侧区域树 + 右侧设备列表的左右分栏布局。

```
┌──────────────────┬───────────────────────────────────────┐
│   左侧：区域树    │   右侧：设备列表（选中区域下的设备）     │
│                  │                                       │
│   📁 厂区        │  ┌ 东北角高位摄像机 █在线  操作↓ ┐    │
│    📁 新库区     │  ├ 人员计数摄像机   █在线  操作↓ ┤    │
│     📁 31号库房 ← 选中  ├ 动环采集器     █在线 [展开▸] ┤    │
│                  │  │  ├ 温湿度探头    26.5℃ █在线  ┤    │
│                  │  │  ├ 空调控制器    制冷  █在线  ┤    │
│                  │  │  ├ 除湿机        关闭  █在线  ┤    │
│                  │  │  └ 紧急报警按钮   正常  █在线  ┤    │
│                  │  └ 电表监测        235V  █在线   ┤    │
└──────────────────┴───────────────────────────────────────┘
```

### 1.2 核心需求

1. **多级区域树**：利用现有 `warehouse_regions` 表（已有 `Id/RegionName/ParentId`）
2. **设备绑定区域**：每个设备通过 `RegionId` 归属到叶子区域
3. **设备父子层级**：采集网关作为父设备，探头/控制器作为子设备展开
4. **地图模型绑定**：每个设备 `MapModelId` 字段供 warehouse 三维地图标记
5. **不同设备不同操作**：视频设备显示播放/云台按钮，IoT 设备显示实时值/控制

---

## 二、数据模型设计

### 2.1 区域表 `warehouse_regions`（现有，不变）

| 字段 | 类型 | 说明 |
|------|------|------|
| Id | int (PK) | 区域ID |
| RegionName | nvarchar(255) | 区域名称 |
| ParentId | int? | 父级区域ID（自引用树） |

### 2.2 统一设备主表 `Base_Device`（修订后新增字段）

| 字段 | 类型 | 说明 |
|------|------|------|
| AdapterCode | nvarchar(50) | 来源适配器：owl/mc4/hikvision_access |
| SourceId | nvarchar(100) | 源系统设备ID |
| IsParent | bit | 是否父设备：0=叶子, 1=可展开（采集器/NVR） |
| ParentDeviceId | uniqueidentifier? | 父设备ID（自引用） |
| **RegionId** | int? | 所属叶子区域ID（FK→warehouse_regions.Id） |
| **MapModelId** | nvarchar(100) | 三维地图模型ID |
| MapModelScale | float | 模型缩放比例 |
| MapModelRotation | nvarchar(100) | 旋转角度JSON |
| ExtraData | nvarchar(max) | 源系统原始数据JSON |
| LocalOverrides | nvarchar(max) | 本地覆盖字段JSON |
| SyncVersion | bigint | 乐观锁版本号 |
| LastSyncTime | datetime | 上次同步时间 |

### 2.3 层级关系示例

```
warehouse_regions:
  Id=1, RegionName="厂区",   ParentId=null
  Id=2, RegionName="新库区",  ParentId=1
  Id=3, RegionName="31号库房", ParentId=2

Base_Device:
  DeviceId=A, RegionId=3, IsParent=0  → 东北角高位摄像机
  DeviceId=B, RegionId=3, IsParent=0  → 人员计数摄像机
  DeviceId=C, RegionId=3, IsParent=1  → 动环采集器（父设备）
  DeviceId=D, RegionId=3, ParentDeviceId=C → 温湿度探头
  DeviceId=E, RegionId=3, ParentDeviceId=C → 空调控制器
  DeviceId=F, RegionId=3, ParentDeviceId=C → 除湿机
```

---

## 三、MC4.0 同步到区域树

MC4.0 对象树中 `type=1`（区域节点）→ 与 `warehouse_regions` 名称匹配后自动绑区。`type=2`（设备节点）→ 写入 `Base_Device`，`RegionId` 设为所属叶子区域。

**关键决策**：Vol.Pro 区域不由 MC4.0 全量控制。管理员可手动创建区域，同步不覆盖。Owl 设备无区域概念，同步后 `RegionId=NULL`，由管理员手动分配。

---

## 四、前端实现方案

### 4.1 文件结构

```
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
    │   └── DeviceSyncToolbar.vue
    └── api/deviceManager.js

web.vite/src/router/index.js      # 新增 /device-manager 路由
```

### 4.2 关键组件逻辑

**RegionTree.vue** — el-tree 加载 `/api/DeviceManager/GetRegionTree`，每个节点显示设备数量徽标。

**DeviceTable.vue** — el-table 使用 `tree-props="{ children: 'subDevices', hasChildren: 'IsParent' }"` 实现可展开行。操作列按 `DeviceCategory` 分发不同按钮组件。

**MapBindingPanel.vue** — 编辑弹出框的一个 Tab，含 MapModelId 下拉选择、缩放/旋转输入、经纬度输入。

### 4.3 与生成页面关系

`Base_Device` 的标准 CRUD 生成页面保留作为兜底（数据批量维护）。在其 extension 中加跳转按钮：

```jsx
// extension/warehouse/Base_Device/Base_Device.jsx
onInit() {
  this.buttons.unshift({
    name: '设备管理',
    icon: 'el-icon-s-grid',
    type: 'primary',
    onClick: () => this.$router.push('/device-manager')
  });
}
```

---

## 五、后端 API

| 接口 | 说明 |
|------|------|
| GET `/api/DeviceManager/GetRegionTree` | 区域树（含设备数量） |
| GET `/api/DeviceManager/GetDevicesByRegion?regionId=3` | 区域下设备列表（含子设备） |
| PUT `/api/DeviceManager/{deviceId}` | 更新设备（含地图绑定字段） |

Controller 写在 `Controllers/Warehouse/Partial/DeviceManagerController.cs`（扩展目录，不被代码生成器覆盖）。

---

## 六、操作按钮矩阵

| DeviceCategory | 操作按钮 |
|---------------|----------|
| 1-视频监控 | 实时预览、云台控制、查看回放、获取快照、同步通道 |
| 2-IoT采集 | 查看实时数据、设备控制、刷新点位、查看告警 |
| 3-门禁 | 远程开门、查看记录、查看告警 |
| 4-道闸 | 抬杆、落杆、查看记录 |
| 5-报警 | 查看告警、布防/撤防 |

父设备（IsParent=1）额外显示展开/收起子设备。

---

## 七、实施变更汇总

| 层级 | 变更项 | 复杂度 |
|------|--------|--------|
| 数据库 | Base_Device 新增8个字段 | 中 |
| 后端 | DeviceManagerController 新建 | 中 |
| 后端 | SyncEngine 区域匹配逻辑 | 高 |
| 前端 | 6个新Vue组件 + 路由 | 高 |
| Gateway | Mc4Adapter 对象树区域提取 | 中 |

**预计工期**：5-7 个工作日（前后端各2-3天，联调1天）。

---

> **文档结束**  
> **关联**: Vol.Pro_MC4.0_整合方案_v1.0、Vol.Pro_Owl_ZLMediaKit_整合方案_v1.0、Vol.Pro_整合项目_实施方案_v1.0