SecMPS/doc/设计文档/客户端改造方案v1.0.md

warehouse 客户端改造方案 v1.0

版本: 1.0
日期: 2025-05-17
现状: warehouse 大屏客户端使用硬编码 Mock 数据，尚未对接网关
目标: 所有子系统（视频/IoT/告警/地图）通过 IntegrationGateway 获取真实数据

---

1. 仓库客户端现状分析

1.1 技术栈

层面	选型
框架	Vue 3 + TypeScript + Vite
UI	Element Plus
图表	ECharts
实时通信	SignalR
3D 地图	VgoMap SDK
HTTP	Axios（api/http.js）
状态管理	Pinia + Vuex
API 基址	window.apiConfig.baseURL（默认 http://localhost:9100）

1.2 页面清单与数据现状

页面	文件	当前数据源	需改造
3D 地图	view/Map.vue	VgoMap SDK，无设备标记	✅
数据大屏	view/DataView.vue	VolPro API（安全提示等）+ Mock	✅
实时视频	view/video/Live.vue	硬编码 5 个 Mock 摄像头	✅
视频墙	view/video/VideoWall.vue	需查看	❓
录像回放	view/video/History.vue	需查看	❓
设备详情	view/DeviceInfo.vue	Props 传入 Mock 数据	✅
环境变量	view/environment/EnvVarManagement.vue	需查看	✅
紧急报警	view/emergency-alarm/EmergencyAlarmRecord.vue	Mock / VolPro API	✅
入侵报警	view/intrusion-alarm/AlarmRecord.vue	Mock	✅
门禁	view/access/AccessRecord.vue	Mock	⏭️ Phase 3
巡更	view/patrol/	Mock	⏭️ Phase 3
钥匙	view/key/	Mock	⏭️ Phase 3
车辆	view/carmanager/	Mock	⏭️ Phase 3
访客	view/visitor/	Mock	⏭️ Phase 3
无人机	view/drone/	Mock	⏭️ Phase 3
对讲	view/intercom/	Mock	⏭️ Phase 3

1.3 HTTP 层现状

api/http.js 封装了 Axios，通过 window.apiConfig.baseURL 配置后端地址（默认 http://localhost:9100），支持 POST/GET 两种方式，自动附带 JWT Token。网关接口（:5100）和 Vol.Pro 接口（:9100）同域还是跨域取决于部署架构。

---

2. 数据流改造

2.1 架构决策：直连网关 vs 经 Vol.Pro 中转

方案	路径	优点	缺点
A. 直连网关	warehouse → GW(:5100)	延迟低，零额外开发	需网关暴露 CORS
B. 经 Vol.Pro 中转	warehouse → VP(:9100) → GW(:5100)	统一鉴权，网关不外露	延迟 +1 跳，需写 Controller

推荐方案 A：warehouse 客户端与大屏同一网络，网关开 CORS 即可。视频流和实时数据对延迟敏感，不宜多一跳。

2.2 服务路由总览

warehouse 客户端
├── Vol.Pro API (axios baseURL)     → http://localhost:9100   (权限/字典/CRUD)
└── 网关 B 接口 (直接 fetch)         → http://localhost:5100   (设备/视频/IoT/告警)

---

3. 逐页面改造方案

3.1 实时视频（Live.vue）

现状：硬编码 5 个 Mock 摄像机，无真实流

改造：

1. 页面加载时调用网关 GET /api/gateway/devices?adapter=Owl:main&page=1&size=100
2. 摄像机列表从 StandardDevice[] 映射到 Camera[] 接口
3. 选中摄像机后调用 GET /api/gateway/streams/{adapterCode}/{sourceId}/live 获取 WS-FLV 地址
4. 用 <video> 标签 autoplay muted 播放（替换占位 div）
5. 增加云台方向控制面板（复用 base_device.vue 的云台 UI）
6. 增加录像回放入口（调 B6b 获取 HLS 地址）

改动量：~150 行

3.2 视频墙（VideoWall.vue）+ 回放（History.vue）

现状：需查看文件

改造：

• 视频墙：多路视频同屏，从网关获取多个通道的流地址并行播放
• 回放：时间轴选择 → GET /api/gateway/streams/{adapter}/{id}/playback?start=&end=

改动量：~100 行

3.3 环境变量（EnvVarManagement.vue）

现状：需查看文件，预期是表格/图表展示温湿度等

改造：

1. 从网关获取 MC4 IoT 设备列表：GET /api/gateway/tree?adapter=MC4:31ku
2. 筛选 DeviceGroup=IoT设备 的设备
3. 轮询 GET /api/gateway/realtime/{adapter}/{deviceId} 获取实时值
4. 替换 Mock 数据，驱动 ECharts 曲线图实时更新

改动量：~120 行

3.4 设备详情（DeviceInfo.vue）

现状：从 DataView.vue 接收 props，展示设备基础信息 + 实时画面（占位图）+ 曲线（Mock）+ 控制按钮

改造：

1. 设备类型判断从 mock type → row.DeviceCategory 字段
2. "实时画面" Tab — 视频设备时调网关 B6a 显示真实流
3. "实时曲线" Tab — IoT 设备时调网关 B4 获取实时值
4. "设备控制" Tab — 调网关 B5 写值
5. 在线率/达标率 — 从 row.IsOnline 和实时值计算

改动量：~200 行

3.5 紧急报警 + 入侵报警

现状：部分调 VolPro API，部分 Mock

改造：

1. 告警列表从网关 GET /api/gateway/alarms/{adapter}?from=&to= 获取
2. 确认/结束告警 → POST /api/gateway/alarms/{adapter}/{alarmId}/confirm
3. 告警等级颜色映射（提示/普通/重要/紧急）
4. 点击告警行 → 联动地图定位到设备

改动量：~100 行

3.6 3D 地图（Map.vue / DataView.vue）

现状：VgoMap 加载 3D 模型，无设备标记

改造：

1. DataView.vue 初始化时调 VolPro API 获取 base_device WHERE Enable=启用 的设备列表
2. 遍历设备，读取 MapModelId、MapModelScale、MapModelRotation 字段
3. 调用 VgoMap SDK 在 3D 场景中放置设备标记（map.addMarker 或模型加载 API）
4. 设备在线状态 → 标记颜色（绿/灰）
5. 点击标记 → 弹出 DeviceInfo.vue 卡片
6. 告警设备 → 红色闪烁标记

改动量：~150 行

---

4. 数据模型映射

4.1 StandardDevice → Camera

interface Camera {
  id: string           // StandardDevice.SourceId
  name: string         // StandardDevice.Name
  location: string     // StandardDevice.Extra?.location || ''
  status: string       // StandardDevice.IsOnline ? 'online' : 'offline'
  adapterCode: string  // StandardDevice.AdapterCode (用于后续 API 调用)
  streamUrl?: string   // 通过 B6a 动态获取
  hasPtz: boolean      // StandardDevice.Extra?.hasPtz === '1'
}

4.2 StandardDevice → MapMarker

interface MapMarker {
  deviceId: number     // StandardDevice.DeviceId
  modelId: string      // StandardDevice.MapModelId
  scale: number        // StandardDevice.MapModelScale
  rotation: JSON       // StandardDevice.MapModelRotation
  isOnline: boolean    // StandardDevice.IsOnline
  category: string     // StandardDevice.DeviceCategory
}

4.3 PointValue → ChartData

interface ChartSeries {
  name: string         // `点位${pv.PointIndex}`
  data: number[]       // [pv.Value, ...] (时间序列)
  timeLabels: string[] // [pv.UpdateTime, ...]
}

---

5. API 封装层

5.1 新增 api/gateway.js

const GW_BASE = 'http://localhost:5100';

export async function gwGet(url: string) {
  const resp = await fetch(`${GW_BASE}${url}`);
  return resp.json();
}

export async function gwPost(url: string, body?: object) {
  const resp = await fetch(`${GW_BASE}${url}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: body ? JSON.stringify(body) : undefined
  });
  return resp.json();
}

5.2 现有 api/http.js 不修改

Vol.Pro 后端 API（权限、字典、CRUD、安全提示）继续走 api/http.js，不加网关逻辑。

---

6. 与 VolPro 管理端的职责分工

功能	管理端（web.vite）	大屏端（warehouse）
设备 CRUD	✅ 设备管理页面	❌
网关注册/心跳	✅ A1-A4	❌
区域树管理	✅ GetRegionTree	❌
实时视频播放	✅ 预览按钮	✅ 多路视频墙
云台控制	✅ 方向键	✅ 方向键
视频回放	✅ 回放按钮	✅ 时间轴回放
IoT 实时曲线	❌	✅ ECharts 大屏
告警弹窗联动	❌	✅ 告警+地图+预案
3D 模型绑定	✅ 编辑面板	✅ 加载标记

---

7. 实施计划

阶段	内容	预计工时
W1	新增 api/gateway.js + 实时视频页改造	2h
W2	视频墙 + 录像回放改造	2h
W3	环境变量 IoT 实时数据改造	2h
W4	设备详情页对接真实数据	2h
W5	报警页面对接网关告警	2h
W6	3D 地图加载设备标记	3h
W7	联调 + 异常处理 + 限流	3h

---

风险: 网关 CORS 配置、VgoMap SDK 设备标记 API 需要验证