SecMPS/doc/整合方案/SecMPS_整合项目实施手册_v3.0.md

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 标准流程

# 开始
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）

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 下拉框可选到字典值。

合并

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）

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 告警同步。

合并

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）

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 收到实时数据和告警。

合并

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）

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。

合并

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）

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 文档、部署手册、组件说明。

合并 + 发布

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