# Vol.Pro 整合项目实施方案

> **版本**: v1.0
> **日期**: 2026-04-29
> **编制**: 浮浮酱
> **状态**: 待实施

---

## 一、项目概述

本项目包含两个子方案：
1. **视频监控方案**: Vol.Pro + Owl + ZLMediaKit（浏览器实时监控、回放、云台控制）
2. **采集网关方案**: Vol.Pro + MC4.0（设备管理、实时数据、反向控制、告警）

两个方案共用 **`Base_Device` 统一设备主表**，实现所有设备的集中管理和三维地图标记。

---

## 二、实施前提条件

### 2.1 环境准备（实施前必须完成）

| # | 检查项 | 通过标准 |
|---|--------|----------|
| 1 | Owl + ZLMediaKit 部署 | Docker运行正常，Web管理端可访问 |
| 2 | MC4.0 采集网关接入 | 设备已接入MC4.0，API可调用 |
| 3 | Vol.Pro 开发环境 | api_sqlsugar/web.vite/warehouse 均可编译运行 |
| 4 | 数据库权限 | 可执行建表SQL，代码生成器可用 |
| 5 | 三维地图模型 | VgoMap中已为设备位置放置模型并记录MapModelId |

### 2.2 必须确认的技术点（实施Day 1前完成）

| # | 确认项 | 确认方式 | 影响 |
|---|--------|----------|------|
| 1 | Owl API完整路径 | 访问Owl Swagger文档 | 所有Owl对接接口 |
| 2 | ZLM播放地址格式 | 调用Owl play接口查看返回URL | 前端播放器配置 |
| 3 | MC4.0 Token机制 | 实测登录接口，确认Header和有效期 | MC4.0所有接口 |
| 4 | MC4.0接口频率限制 | 高频调用测试是否限流 | 轮询任务设计 |

---

## 三、实施策略

### 3.1 分阶段实施

```
Phase 1: 视频监控方案（15个工作日）
    ├─ 优先实施，技术成熟度更高
    ├─ 不依赖MC4.0方案
    └─ 验证Vol.Pro扩展机制的可行性

Phase 2: 采集网关方案（16个工作日）
    ├─ 在视频监控方案完成后实施
    ├─ 可复用Phase 1积累的Vol.Pro扩展经验
    └─ 共用Base_Device主表（Phase 1已创建）
```

### 3.2 实施顺序

| 顺序 | 方案 | 工期 | 前置依赖 |
|------|------|------|----------|
| 1 | 视频监控方案 | 15天 | 无 |
| 2 | 采集网关方案 | 16天 | 视频监控方案完成（复用Base_Device表） |
| **合计** | | **31天** | |

> **可并行优化**：如果人手充足，采集网关方案可在视频监控方案的阶段四/五时并行启动，总工期可缩短至 **20-22天**。

---

## 四、视频监控方案实施计划（15天）

### Week 1: 基础搭建（Day 1-5）

#### Day 1: 数据库与代码生成
- [ ] 执行建表SQL创建4张表：`Base_Device`、`Device_Video_Ext`、`Video_Channel`、`Video_Record`
- [ ] 使用Vol.Pro代码生成器生成4个模块的CRUD代码
- [ ] 验证生成后的增删改查功能正常
- [ ] **验收点**: 管理端可正常增删改查设备/通道/录像

#### Day 2: Owl对接服务搭建
- [ ] 创建 `Warehouse/Services/Owl/IOwlApiService.cs`
- [ ] 创建 `Warehouse/Services/Owl/OwlApiService.cs`
- [ ] 实现JWT Token获取与缓存（内存/Redis）
- [ ] **验收点**: 可成功获取Owl Token并缓存

#### Day 3: Owl设备同步
- [ ] 实现设备同步逻辑（调用Owl `/devices`）
- [ ] 实现通道同步逻辑（调用Owl `/channels`）
- [ ] 实现数据写入Base_Device + Device_Video_Ext + Video_Channel
- [ ] **验收点**: 执行同步后，Vol.Pro数据库中有Owl设备数据

#### Day 4: 取流与回放接口
- [ ] 实现 `GetLiveUrl` 接口（调用Owl play）
- [ ] 实现 `GetPlaybackUrl` 接口（调用Owl recordings）
- [ ] 实现 `StopPlay` 接口
- [ ] **验收点**: Postman可调用获取流地址

#### Day 5: 云台与快照接口
- [ ] 实现 `PtzControl` 接口
- [ ] 实现 `GetSnapshot` 接口
- [ ] 创建 `VideoStreamController.cs`
- [ ] **验收点**: Postman可调用云台控制和获取快照

### Week 2: 前端与管理端（Day 6-10）

#### Day 6: 管理端设备列表扩展
- [ ] 创建 `extension/warehouse/Base_Device.jsx`
- [ ] 添加"同步设备"按钮
- [ ] 添加DeviceCategory=1筛选（默认显示视频监控设备）
- [ ] 添加"查看通道"操作列
- [ ] **验收点**: 管理端设备列表有同步按钮和通道查看

#### Day 7: 管理端通道列表扩展
- [ ] 创建 `extension/warehouse/Video_Channel.jsx`
- [ ] 添加"实时预览"按钮（弹窗播放）
- [ ] 添加"云台控制"按钮
- [ ] 添加"回放"按钮
- [ ] **验收点**: 管理端通道列表可播放视频

#### Day 8: 播放器集成
- [ ] 引入Jessibuca/mpegts.js播放器组件
- [ ] 创建 `VideoPlayer.vue`（实时播放弹窗）
- [ ] 创建 `VideoPlayback.vue`（回放查询页面）
- [ ] **验收点**: 浏览器可播放实时视频和回放

#### Day 9: warehouse用户端改造 - Live.vue
- [ ] 替换硬编码数据为真实API调用
- [ ] 集成Jessibuca播放器
- [ ] 摄像头列表从Video_Channel API获取
- [ ] **验收点**: warehouse Live.vue可播放实时视频

#### Day 10: warehouse用户端改造 - History.vue + VideoWall.vue
- [ ] 改造History.vue实现回放查询和HLS播放
- [ ] 改造VideoWall.vue（图片→真实播放器）
- [ ] 对接云台控制API
- [ ] **验收点**: 回放和视频墙功能正常

### Week 3: 联调与优化（Day 11-15）

#### Day 11-12: 联调测试
- [ ] 设备注册到Owl后同步到Vol.Pro
- [ ] 实时播放测试（WebRTC/FLV）
- [ ] 回放功能测试
- [ ] 云台控制测试
- [ ] 多路视频墙测试
- [ ] **验收点**: 所有功能端到端可用

#### Day 13: 框架升级测试
- [ ] 重新运行代码生成器
- [ ] 验证所有自定义代码（Partial/extension）未被覆盖
- [ ] **验收点**: 代码生成器不覆盖自定义代码

#### Day 14-15: 缓冲优化
- [ ] 性能优化（视频墙路数限制、流释放）
- [ ] 安全加固（播放地址代理、权限校验）
- [ ] 文档补充

---

## 五、采集网关方案实施计划（16天）

### Week 1: 基础搭建（Day 1-5）

#### Day 1: 数据库与代码生成
- [ ] 执行建表SQL：`Device_IoT_Ext`、`IoT_DevicePoint`、`IoT_DeviceData`、`IoT_Alarm`
- [ ] 使用Vol.Pro代码生成器生成CRUD代码
- [ ] **注意**: Base_Device表已在视频监控方案中创建，无需重复创建
- [ ] **验收点**: 管理端可正常增删改查

#### Day 2: MC4.0对接服务搭建
- [ ] 创建 `IMc4ApiService.cs` / `Mc4ApiService.cs`
- [ ] 实现Token管理（登录/缓存/刷新）
- [ ] 实现请求频率控制（SemaphoreSlim，每秒最多2次）
- [ ] **验收点**: 可成功获取MC4.0 Token

#### Day 3: 对象树与点表同步
- [ ] 实现对象树同步（`/object/tree`）
- [ ] 实现点表同步（`/device/point/get`）
- [ ] 数据写入Base_Device + Device_IoT_Ext + IoT_DevicePoint
- [ ] **验收点**: 执行同步后Vol.Pro中有MC4.0设备数据

#### Day 4: 实时数据与控制接口
- [ ] 实现 `GetRealtime` 接口（调用MC4.0读数据）
- [ ] 实现 `Control` 接口（反向控制）
- [ ] **验收点**: Postman可读取实时数据和控制设备

#### Day 5: 告警接口
- [ ] 实现 `GetAlarms` 接口
- [ ] 实现 `ConfirmAlarm` / `EndAlarm` 接口
- [ ] 创建 `IoTStreamController.cs`
- [ ] **验收点**: Postman可查询和确认告警

### Week 2: 实时推送与管理端（Day 6-10）

#### Day 6: SignalR Hub搭建
- [ ] 创建 `IoTDataHub.cs`
- [ ] 实现设备分组订阅（SubscribeDevice/UnsubscribeDevice）
- [ ] 实现告警管理员组订阅（SubscribeAlarmAdmin）
- [ ] **验收点**: 前端可连接SignalR并订阅设备

#### Day 7: 实时数据轮询Job
- [ ] 创建 `RealtimeDataPollJob.cs`
- [ ] 每5秒轮询MC4.0实时数据
- [ ] **不入库，直接SignalR推送给前端**
- [ ] **验收点**: 前端实时收到数据更新

#### Day 8: 告警轮询Job
- [ ] 创建 `AlarmPollJob.cs`
- [ ] 每10秒轮询MC4.0告警
- [ ] 新告警写入IoT_Alarm表
- [ ] 按设备分组SignalR推送
- [ ] **验收点**: 新告警实时推送到前端

#### Day 9: 管理端设备列表扩展
- [ ] 扩展 `Base_Device.jsx`（添加采集设备相关按钮）
- [ ] 添加"同步对象树"按钮（仅DeviceCategory=2显示）
- [ ] 添加"同步点表"操作列
- [ ] 添加"查看实时数据"按钮
- [ ] **验收点**: 管理端可同步和查看采集设备

#### Day 10: 管理端告警列表扩展
- [ ] 扩展告警列表页
- [ ] 添加"确认"和"结束"操作按钮
- [ ] 告警等级颜色标识（紧急=红色，重要=橙色）
- [ ] **验收点**: 管理端可处理告警

### Week 3: warehouse用户端与联调（Day 11-16）

#### Day 11-12: warehouse用户端开发
- [ ] 开发实时数据看板（设备列表+实时数值+SignalR接收）
- [ ] 开发设备控制面板（开关/滑块/输入框）
- [ ] 开发告警信息面板（实时告警+历史查询）
- [ ] **验收点**: warehouse可查看实时数据和控制设备

#### Day 13-14: 联调测试
- [ ] MC4.0设备接入测试
- [ ] 实时数据读取测试（验证SignalR推送，不入库）
- [ ] 反向控制测试
- [ ] 告警轮询与推送测试（10秒轮询+分组推送）
- [ ] 请求频率控制测试（每秒不超过2次）
- [ ] 多设备并发测试
- [ ] **验收点**: 所有功能端到端可用

#### Day 15: 框架升级测试
- [ ] 重新运行代码生成器
- [ ] 验证自定义代码未被覆盖
- [ ] **验收点**: 代码独立性验证通过

#### Day 16: 缓冲优化
- [ ] 性能优化
- [ ] 文档补充
- [ ] 问题修复

---

## 六、关键里程碑与验收标准

| 里程碑 | 时间 | 验收标准 |
|--------|------|----------|
| M1: 视频监控后端完成 | Day 5 | Owl对接服务所有接口Postman测试通过 |
| M2: 视频监控前端完成 | Day 10 | warehouse Live/History/VideoWall功能可用 |
| M3: 视频监控联调完成 | Day 15 | 所有功能端到端可用，框架升级测试通过 |
| M4: 采集网关后端完成 | Day 5 | MC4.0对接服务所有接口Postman测试通过 |
| M5: 采集网关前端完成 | Day 12 | warehouse实时数据/控制/告警功能可用 |
| M6: 采集网关联调完成 | Day 16 | 所有功能端到端可用，框架升级测试通过 |

---

## 七、风险控制

| 风险 | 影响 | 应对措施 |
|------|------|----------|
| Owl API路径不准确 | 所有取流/云台接口404 | Day 1实测Swagger确认路径 |
| MC4.0 Token快速过期 | 频繁重新登录 | Day 1实测Token有效期，设计自动刷新 |
| ZLM WebRTC配置失败 | 无法使用WebRTC | 默认使用WS-FLV，WebRTC作为可选优化 |
| MC4.0接口限流 | 轮询任务失败 | SemaphoreSlim频率控制，失败时告警 |
| 数据量爆炸 | SQL Server性能下降 | 实时数据不入库，仅SignalR推送 |
| 前端播放器兼容性 | 部分浏览器无法播放 | 提供FLV/HLS多协议降级 |

---

## 八、实施检查清单

### 每日检查项
- [ ] 今日代码是否写在独立文件（不修改框架代码）
- [ ] 新服务是否实现IDependency接口
- [ ] Controller是否使用partial或全新文件
- [ ] 前端扩展是否写在extension目录

### 阶段验收检查项
- [ ] 重新运行代码生成器，确认自定义代码未被覆盖
- [ ] 所有API接口Postman测试通过
- [ ] 前端功能在Chrome/Firefox/Edge测试通过
- [ ] 性能测试（视频墙最大路数、MC4.0轮询频率）

---

## 九、相关文档索引

| 文档 | 路径 | 说明 |
|------|------|------|
| 视频监控整合方案 | `doc/整合方案/Vol.Pro_Owl_ZLMediaKit_整合方案_v1.0.md` | 详细技术方案 |
| 采集网关整合方案 | `doc/整合方案/Vol.Pro_MC4.0_整合方案_v1.0.md` | 详细技术方案 |
| MC4.0 API文档 | `doc/对接文档/MC4.0对外API.md` | MC4.0接口定义 |
| 联网部署手册 | `owl_zlmediakit/联网部署手册.md` | Owl+ZLM部署指南 |
| 超时排查手册 | `owl_zlmediakit/排查手册-访问超时.md` | 网络问题排查 |

---

> **文档结束**
> **版本**: v1.0
> **最后更新**: 2026-04-29
> **状态**: 待主人确认后实施