# 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

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

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

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

---

## 5. API 封装层

### 5.1 新增 `api/gateway.js`

```typescript
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 需要验证