8.7 KiB
SecMPS 整合项目实施手册
版本: v2.1
日期: 2026-05-15
基于: SecMPS_最终整合方案_v2.0.md
工期: 18-20 个工作日
开发模式: 单人 + Agent，Squash Merge 主线策略
分支管理策略
master ──────────────────────────────────────────────→ v2.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 部署包
├── doc/ ← 文档
└── gateway/ ← IntegrationGateway（★ 独立顶层文件夹）
整个网关项目放在
gateway/目录下，与 Vol.Pro 物理隔离。新建适配器时同样在此目录下添加项目。
初始化
git remote -v # 确认 origin → gitea.1vs5.top
每个 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 部署运行 | 浏览器访问 Owl 管理端 | Phase 1 |
| 2 | 至少1台 GB28181 设备注册 | 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 new sln + Host webapi + Core classlib)。验证: dotnet build。
任务 1.2: Core 层 7 接口 + 8 模型 + AdapterRegistry/TokenManager/RateLimiter。验证: 单元测试 mock 适配器。
任务 1.3: Host 层 HealthController/DevicesController/PointsController/StreamsController/AlarmsController/SyncController。验证: GET /api/gateway/health → 200。
任务 1.4: 8 张表 DDL 执行。验证: SELECT COUNT(*) FROM Base_Device → 0，唯一索引存在。
任务 1.5: 代码生成器跑 8 张表。验证: 管理端 8 个新菜单可 CRUD。
Day 2 — Vol.Pro 侧
任务 2.1: GatewayClient.cs (IDependency)。验证: 注入后 HealthCheckAsync() → true。
任务 2.2: DeviceManagerController.cs (Partial/) — GetRegionTree / GetDevicesByRegion / PUT。验证: Postman 返回 JSON。
任务 2.3: SyncDevicesJob (Quartz)。验证: Quartz 面板看到 Job。
合并
git add -A && git commit -m "Phase 0 完成"
git checkout master && git merge --squash phase/0-infrastructure
git commit -m "Phase 0: Gateway骨架 + 8张表 + GatewayClient + DeviceManagerController"
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。
验证（Postman → Gateway）:
GET /health → {"owl":true}
GET /devices?adapter=owl → Owl设备列表
GET /streams/owl/{id}/live → WS-FLV地址
端到端同步 → SELECT * FROM Base_Device WHERE AdapterCode='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 — 联调 + 边界测试
设备同步不重复、4路播放不卡顿、离线设备状态正确、生成器重跑文件不丢失。
合并
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+DeviceTable+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.RegionId 正确。
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 — 全链路联调
设备同步→入库、区域树→el-tree、实时预览→播放、云台→转动、实时数据→更新、控制→响应、告警→弹窗(<15s)、确认→MC4.0。
性能: 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 过期自动刷新，并发同步互不干扰。
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 v2.0.0 -m "SecMPS v2.0: IntegrationGateway + 统一设备管理"
git push origin v2.0.0
附录 A：每日检查清单
□ 新增 C# 服务实现 IDependency
□ Controller 写在 Partial/ 目录
□ 前端在 extension/ 目录
□ 未修改自动生成文件
□ MC4.0 经 RateLimiter
□ Owl Token 用 TokenManager
□ 实时数据未写 IoT_DeviceData
□ dotnet build 零错误
附录 B：端口分配
| 服务 | 端口 |
|---|---|
| IntegrationGateway | 5100 |
| VolPro.WebApi | 9100 |
| web.vite | 9000 |
| warehouse | 9200 |
| Owl | 80 |
| MC4.0 | 3000 |
附录 C：里程碑标签
| 标签 | 指向 |
|---|---|
phase-0-done |
Gateway 骨架 + 建表 |
phase-1-done |
Owl + 视频设备页 |
phase-2-done |
MC4 + IoT + SignalR |
phase-3-done |
warehouse + 联调 |
phase-4-done |
验证 + 文档 |
v2.0.0 |
正式发布 |
文档结束
取代: SecMPS_整合项目实施手册_v2.0.md