336 lines
10 KiB
Markdown
336 lines
10 KiB
Markdown
# SecMPS 整合项目实施手册
|
||
|
||
> **版本**: v3.0
|
||
> **日期**: 2026-05-16
|
||
> **基于**: SecMPS_最终整合方案_v3.0.md
|
||
> **工期**: 18-20 个工作日
|
||
> **开发模式**: 单人 + Agent，Squash Merge 主线策略
|
||
|
||
---
|
||
|
||
## 分支管理策略
|
||
|
||
```
|
||
master ──────────────────────────────────────────────→ v3.0.0
|
||
│ ┌─ squash ─┐ ┌─ squash ─┐ ┌─ squash ─┐
|
||
├── phase/0 ├── phase/1 ├── phase/2 ├── ...
|
||
└── infrastructure └── owl-video └── mc4-iot └──
|
||
```
|
||
|
||
**规则**：每个 Phase 从 `master` 切分支 → 开发完成 → `git merge --squash` 合并回 `master`（一个提交）。出错直接删分支重切，零代价。
|
||
|
||
### 项目约定
|
||
|
||
```
|
||
SecMPS/
|
||
├── api_sqlsugar/ ← Vol.Pro 后端
|
||
├── web.vite/ ← 管理端
|
||
├── warehouse/ ← 用户大屏端
|
||
├── owl_zlmediakit/ ← Owl+ZLM 部署包 (Owl管理端口:15123)
|
||
├── doc/ ← 文档
|
||
└── gateway/ ← IntegrationGateway（独立顶层文件夹）
|
||
```
|
||
|
||
### 每个 Phase 标准流程
|
||
|
||
```bash
|
||
# 开始
|
||
git checkout master
|
||
git checkout -b phase/{n}-{name}
|
||
|
||
# 开发（随时提交）
|
||
git add -A && git commit -m "具体改动描述"
|
||
|
||
# 完成后合并
|
||
git checkout master
|
||
git merge --squash phase/{n}-{name}
|
||
git commit -m "Phase {n}: {标题}"
|
||
git push
|
||
git tag phase-{n}-done
|
||
```
|
||
|
||
---
|
||
|
||
## 前置检查清单（Day 0）
|
||
|
||
| # | 检查项 | 验证方式 | 阻塞 |
|
||
|---|--------|----------|------|
|
||
| 1 | Owl+ZLM 部署运行 | 浏览器访问 http://owl_ip:15123 管理端 | Phase 1 |
|
||
| 2 | 至少1台 GB28181 设备注册到 Owl | Owl `/devices` 有数据 | Phase 1 |
|
||
| 3 | MC4.0 网关可访问 | curl :3000 /api/central/auth/conf/get | Phase 2 |
|
||
| 4 | MC4.0 有设备接入 | 对象树有 type=2 节点 | Phase 2 |
|
||
| 5 | 代码生成器可用 | 新建测试表→生成→确认 | Phase 0 |
|
||
| 6 | MySQL 建表权限 | 执行 CREATE TABLE | Phase 0 |
|
||
| 7 | Node.js >= 20.19 | node -v | Phase 3 |
|
||
|
||
---
|
||
|
||
## Phase 0：基础设施（Day 1-2）
|
||
|
||
```bash
|
||
git checkout master && git checkout -b phase/0-infrastructure
|
||
```
|
||
|
||
### Day 1 — Gateway 骨架 + 数据库
|
||
|
||
**任务 1.1**: 在 `gateway/` 下创建 IntegrationGateway 解决方案。验证: `dotnet build`。
|
||
|
||
**任务 1.2**: Core 层 7 接口 + 10 模型 + AdapterRegistry/TokenManager/RateLimiter。验证: 单元测试 mock 适配器。
|
||
|
||
**任务 1.3**: Host 层 6 Controller (Health/Devices/Points/Streams/Alarms/Sync) + RegisterController。验证: `GET /api/gateway/health` → 200。
|
||
|
||
**任务 1.4**: 6 张表 DDL 执行（base_device/video_channel/video_record/iot_devicedata/iot_alarm/gateway_nodes）。验证: 唯一索引存在。
|
||
|
||
**任务 1.5**: 代码生成器跑 6 张表。验证: 管理端 6 个新菜单可 CRUD。
|
||
|
||
### Day 2 — Vol.Pro 侧 + 字典初始化
|
||
|
||
**任务 2.1**: `GatewayClient.cs` (IDependency) + `GatewayNodeController.cs` (注册/心跳)。验证: 注入 HealthCheckAsync() → true。
|
||
|
||
**任务 2.2**: `DeviceManagerController.cs` (Partial/) — GetRegionTree / GetDevicesByPoint / PUT。验证: Postman 返回 JSON。
|
||
|
||
**任务 2.3**: `SyncDevicesJob` (Quartz) + 心跳超时检测 Job。验证: Quartz 面板看到 Job。
|
||
|
||
**任务 2.4**: ★ 数据字典初始化（8个字典）:
|
||
|
||
| 字典名称 | 字典值 |
|
||
|----------|--------|
|
||
| 设备种类 | 门磁/空调/智能断路器/人行道闸/车辆道闸/... (18个) |
|
||
| 设备分组 | 视频设备/IoT设备/门禁设备/道闸设备/报警设备 |
|
||
| 是否父设备 | 是/否 |
|
||
| 在线状态 | 在线/离线 |
|
||
| 启用状态 | 启用/禁用 |
|
||
| 是否控制点 | 只读/可写 |
|
||
| 告警等级 | 提示/普通/重要/紧急 |
|
||
| 告警状态 | 未确认/已确认/已结束 |
|
||
|
||
**验证**: 在 base_device 编辑表单中 DeviceCategory 下拉框可选到字典值。
|
||
|
||
### 合并
|
||
|
||
```bash
|
||
git add -A && git commit -m "Phase 0 完成"
|
||
git checkout master && git merge --squash phase/0-infrastructure
|
||
git commit -m "Phase 0: Gateway骨架 + 6张表 + 代码生成 + 字典初始化"
|
||
git push && git tag phase-0-done
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 1：Owl 适配器 + 管理端视频设备页（Day 3-6）
|
||
|
||
```bash
|
||
git checkout master && git checkout -b phase/1-owl-video
|
||
```
|
||
|
||
### Day 3 — OwlAdapter
|
||
|
||
创建 `Adapters.Owl` 项目，实现 `IHasFlatDevices+IHasStreams+IAcceptsMetadataPush`。
|
||
|
||
关键实现细节：
|
||
- Token: 调 `GET /login/key` → RSA加密 → `POST /login` → 缓存 JWT（3天有效）
|
||
- 设备同步: `GET /devices` + `GET /channels` → OwlDevice[] → StandardDevice[]
|
||
- Owl 管理端口: **15123**（非 80）
|
||
|
||
验证（Postman → Gateway）:
|
||
```
|
||
GET /health → {"owl":true}
|
||
GET /devices?adapter=owl → Owl设备列表
|
||
GET /streams/owl/{id}/live → WS-FLV地址
|
||
```
|
||
|
||
端到端同步 → `SELECT * FROM base_device WHERE AdapterCode LIKE 'Owl%'` 有数据。
|
||
|
||
### Day 4 — 管理端设备页面框架
|
||
|
||
`DeviceManager/index.vue`（左右分栏） + `RegionTree.vue`（el-tree: 区域→点位→设备） + `DeviceTable.vue`（el-table 可展开）。
|
||
|
||
验证: `/device-manager` 页面可用。
|
||
|
||
### Day 5 — 视频操作 + Jessibuca
|
||
|
||
`VideoDeviceActions.vue`（按钮组）+ `DeviceLivePreview.vue`（Jessibuca 弹窗）+ 云台控制面板（仅方向键 ↑↓←→ + 停止，不包含预置位）。
|
||
|
||
验证: 实时预览播放画面、方向键控制。
|
||
|
||
### Day 6 — 联调 + 边界测试
|
||
|
||
| 测试 | 预期 |
|
||
|------|------|
|
||
| 设备同步 | 表格数据刷新，不重复 |
|
||
| 实时预览 | Jessibuca 播放正常（首发有 1-3s 延迟） |
|
||
| 云台控制 | 方向键有效，预置位不存在 |
|
||
| 多路播放(4路) | 不卡顿 |
|
||
| 离线设备 | 状态显示「离线」 |
|
||
| 框架隔离 | 重跑生成器，DeviceManager/ 文件未丢失 |
|
||
|
||
#### [可选] Owl AI 事件接入
|
||
|
||
OwlAdapter 可选实现 IHasAlarms → 将 Owl `GET /events` 的 YOLO 检测事件映射为 StandardAlarm → 走 A4 告警同步。
|
||
|
||
### 合并
|
||
|
||
```bash
|
||
git add -A && git commit -m "Phase 1 完成"
|
||
git checkout master && git merge --squash phase/1-owl-video
|
||
git commit -m "Phase 1: OwlAdapter + 管理端视频设备页 (RegionTree+Jessibuca)"
|
||
git push && git tag phase-1-done
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 2：MC4.0 适配器 + IoT 管理（Day 7-11）
|
||
|
||
```bash
|
||
git checkout master && git checkout -b phase/2-mc4-iot
|
||
```
|
||
|
||
### Day 7 — Mc4Adapter
|
||
|
||
实现 `IHasOwnDeviceTree+IHasPoints+IHasAlarms`。验证: Postman 调 Gateway `/health`、`/sync`、`/realtime`、`/control`、`/alarms`、`/confirm` 全部通过。
|
||
|
||
### Day 8 — 区域自动匹配
|
||
|
||
SyncEngine.ProcessTreeNode: type=1 → MatchOrCreateRegion, type=2 → UpsertDevice。
|
||
|
||
验证: 同步后 `warehouse_regions` 有 MC4.0 区域，`base_device.PointId` 正确。
|
||
|
||
### Day 9 — IoT 操作 + 实时数据
|
||
|
||
`IoTDeviceActions.vue` + 实时数据弹窗（含开关/滑块控件）。
|
||
|
||
验证: 拖动滑块 → 设备实际值改变。
|
||
|
||
### Day 10 — 告警 + 地图绑定
|
||
|
||
编辑弹窗告警 tab + `MapBindingPanel.vue`。
|
||
|
||
验证: 地图绑定保存后值持久化。
|
||
|
||
### Day 11 — SignalR + Quartz
|
||
|
||
`IoTDataHub.cs` + `RealtimePollJob`(5s) + `AlarmPollJob`(10s)。
|
||
|
||
验证: warehouse 端 SignalR 收到实时数据和告警。
|
||
|
||
### 合并
|
||
|
||
```bash
|
||
git add -A && git commit -m "Phase 2 完成"
|
||
git checkout master && git merge --squash phase/2-mc4-iot
|
||
git commit -m "Phase 2: Mc4Adapter + SyncEngine + SignalR + Quartz + 地图绑定"
|
||
git push && git tag phase-2-done
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 3：warehouse 端 + 全链路联调（Day 12-17）
|
||
|
||
```bash
|
||
git checkout master && git checkout -b phase/3-warehouse
|
||
```
|
||
|
||
### Day 12-13 — 视频播放器
|
||
|
||
Live.vue / History.vue / VideoWall.vue 假数据→真实 API + Jessibuca。
|
||
|
||
验证: 全功能可用。
|
||
|
||
### Day 14-15 — IoT 面板
|
||
|
||
实时数据看板(SignalR) / 控制面板 / 告警面板。
|
||
|
||
验证: warehouse IoT 功能可用。
|
||
|
||
### Day 16-17 — 全链路联调
|
||
|
||
设备同步→入库、区域→点位→设备树、实时预览→播放、云台→转动（仅方向）、实时数据→更新、控制→响应、告警→弹窗(<15s)、确认→双向写回。
|
||
|
||
性能: 9路视频≥15fps, 100设备轮询<3s, 500设备同步<30s。
|
||
|
||
### 合并
|
||
|
||
```bash
|
||
git add -A && git commit -m "Phase 3 完成"
|
||
git checkout master && git merge --squash phase/3-warehouse
|
||
git commit -m "Phase 3: warehouse视频+IoT面板 + 全链路联调"
|
||
git push && git tag phase-3-done
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 4：验证 + 发布（Day 18-20）
|
||
|
||
```bash
|
||
git checkout master && git checkout -b phase/4-verify
|
||
```
|
||
|
||
### Day 18 — 代码隔离验证
|
||
|
||
重跑生成器 → Partial/extension/DeviceManager 目录未被覆盖。
|
||
|
||
### Day 19 — 异常场景
|
||
|
||
Owl/MC4.0/Gateway 宕机不崩溃，Token 过期自动刷新，网关重启 NodeId 复用，并发同步互不干扰。
|
||
|
||
### Day 20 — 文档收尾
|
||
|
||
API 文档、部署手册、组件说明。
|
||
|
||
### 合并 + 发布
|
||
|
||
```bash
|
||
git add -A && git commit -m "Phase 4 完成"
|
||
git checkout master && git merge --squash phase/4-verify
|
||
git commit -m "Phase 4: 代码隔离验证 + 异常测试 + 文档"
|
||
git push && git tag phase-4-done
|
||
|
||
git tag -a v3.0.0 -m "SecMPS v3.0: IntegrationGateway + 统一设备管理"
|
||
git push origin v3.0.0
|
||
```
|
||
|
||
---
|
||
|
||
## 附录 A：每日检查清单
|
||
|
||
```
|
||
□ 新增 C# 服务实现 IDependency
|
||
□ Controller 写在 Partial/ 目录
|
||
□ 前端在 extension/ 目录
|
||
□ 未修改自动生成文件
|
||
□ MC4.0 经 RateLimiter
|
||
□ Owl Token 用 TokenManager
|
||
□ 网关同步走字段分治（管理员字段不覆盖）
|
||
□ parentSourceId 已映射为 ParentDeviceId
|
||
□ 实时数据未写 IoT_DeviceData
|
||
□ dotnet build 零错误
|
||
```
|
||
|
||
## 附录 B：端口分配
|
||
|
||
| 服务 | 端口 |
|
||
|------|------|
|
||
| IntegrationGateway | 5100 |
|
||
| VolPro.WebApi | 9100 |
|
||
| web.vite | 9000 |
|
||
| warehouse | 9200 |
|
||
| Owl 管理端 | **15123** |
|
||
| ZLMediaKit (由Owl管理) | 8000 |
|
||
| MC4.0 | 3000 |
|
||
|
||
## 附录 C：里程碑标签
|
||
|
||
| 标签 | 指向 |
|
||
|------|------|
|
||
| `phase-0-done` | Gateway 骨架 + 6张表 + 字典初始化 |
|
||
| `phase-1-done` | OwlAdapter + 视频设备页 |
|
||
| `phase-2-done` | Mc4Adapter + IoT + SignalR |
|
||
| `phase-3-done` | warehouse + 联调 |
|
||
| `phase-4-done` | 验证 + 文档 |
|
||
| `v3.0.0` | 正式发布 |
|
||
|
||
---
|
||
|
||
> **文档结束**
|
||
> **取代**: SecMPS_整合项目实施手册_v2.1.md
|