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

git checkout master
git checkout -b phase/{n}-{name}
# 开发 + 提交
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）

Day 1 — 从头搭建网关 + 数据库

任务 1.1 — 创建 Gateway 解决方案

在 gateway/ 目录下:

dotnet new sln -n IntegrationGateway
dotnet new webapi -n IntegrationGateway.Host -f net8.0
dotnet new classlib -n IntegrationGateway.Core -f net8.0
dotnet sln add src/IntegrationGateway.Host src/IntegrationGateway.Core
dotnet add src/IntegrationGateway.Host reference src/IntegrationGateway.Core
dotnet add src/IntegrationGateway.Core package Microsoft.Extensions.Caching.Memory

验证: dotnet build 零错误。

任务 1.2 — Core 层（接口 + 模型 + 基础设施）

Abstractions/ — 7 个分型接口:

• IIntegrationAdapter (基础: AdapterCode/HealthCheck/Initialize)
• IHasOwnDeviceTree (MC4)、IHasFlatDevices (Owl)、IHasPoints (MC4)
• IHasStreams (Owl)、IHasAlarms (通用)、IAcceptsMetadataPush (Owl)

Models/ — 10 个标准化模型:

• StandardDevice/DeviceTreeNode/StandardPoint/PointValue/StandardAlarm
• StreamUrls/SyncReport/PagedResult/AdapterCapabilities/StandardRecording

Infrastructure/ — 3 个基础设施:

• AdapterRegistry (适配器注册与发现)
• TokenManager (通用内存 Token 缓存)
• RateLimiter (SemaphoreSlim 频率控制)

验证: dotnet build 零错误 + 单元测试 mock 适配器通过。

任务 1.3 — Host 层 Controller（7 个）

Controller	对应 API	说明
HealthController	B1	健康检查
DevicesController	B2	设备列表
PointsController	B4/B5	实时数据+控制
StreamsController	B6a/B6b/B7	取流+回放+云台
AlarmsController	B8/B9	告警查询+确认
SyncController	B3	手动同步
RegisterController	A1/A2	网关注册+心跳

验证: 启动 Host，GET /api/gateway/health → 200。

任务 1.4 — 网关配置 + 启动注册

appsettings.json:

{
  "VolProBaseUrl": "http://localhost:9100",
  "NodeCode": "gw-31ku",
  "NodeToken": "xxxxxxxxxx",
  "Urls": "http://*:5100"
}

Program.cs 启动逻辑:

builder.Services.AddControllers();
builder.Services.AddMemoryCache();
builder.Services.AddHttpClient("VolPro", c => {
    c.BaseAddress = new Uri(builder.Configuration["VolProBaseUrl"]);
});
builder.Services.AddSingleton<AdapterRegistry>();
builder.Services.AddSingleton<TokenManager>();
// 启动后自动调 Vol.Pro 注册
app.Lifetime.ApplicationStarted.Register(() => {
    Task.Run(() => RegisterWithVolPro(app));
});

新增 GatewayClient.cs — 封装网关→Vol.Pro 的 HTTP 调用（A1注册/A2心跳/A3设备同步/A4告警同步）。

验证: 网关启动后调 Vol.Pro 的 A1 端点成功，返回 nodeId。

任务 1.5 — 执行 db_init.sql（6张表）

验证: SELECT COUNT(*) FROM base_device → 0，唯一索引 (AdapterCode, SourceId) 存在。

Day 2 — Vol.Pro 侧集成 + 代码生成 + 字典

任务 2.1 — Vol.Pro GatewayClient (后端调网关的 HTTP 封装)

新增 api_sqlsugar/VolPro.Core/Infrastructure/GatewayClient.cs (IDependency)。 封装: 注册/心跳/设备同步/告警同步/实时数据/取流/云台/告警确认。

任务 2.2 — Vol.Pro GatewayNodeController (A组接口服务端)

新增 Controllers/Warehouse/Partial/GatewayNodeController.cs:

• POST /api/gateway/register (A1) — Upsert gateway_nodes, 返回设备列表
• POST /api/gateway/heartbeat (A2) — 更新 LastHeartbeat
• POST /api/gateway/sync/devices (A3) — 设备同步(字段分治+parentSourceId映射)
• POST /api/gateway/sync/alarms (A4) — 告警同步

验证: Postman 模拟网关调 A1 注册，返回 nodeId+设备列表。

任务 2.3 — DeviceManagerController

新增 Controllers/Warehouse/Partial/DeviceManagerController.cs:

• GET GetRegionTree — 区域→点位→设备树
• GET GetDevicesByPoint?pointId= — 点位下设备列表(含子设备)
• PUT {deviceId} — 更新设备(含地图绑定)

验证: Postman GET /api/DeviceManager/GetRegionTree → JSON。

任务 2.4 — 代码生成器

对 6 张表运行 Vol.Pro 代码生成器。

验证: 管理端 6 个新菜单可 CRUD。

任务 2.5 — 字典初始化

在 Vol.Pro 管理端创建 8 个数据字典（设备种类/设备分组/是否父设备/在线状态/启用状态/是否控制点/告警等级/告警状态）。

验证: base_device 编辑表单中 DeviceCategory 下拉可选到字典值。

任务 2.6 — Quartz Job

• SyncDevicesJob — 定时调网关同步
• HeartbeatMonitorJob — 超 30s 无心跳级联设备离线

验证: Quartz 面板看到已注册 Job。

合并

git add -A && git commit -m "Phase 0 完成"
git checkout master && git merge --squash phase/0-infrastructure
git commit -m "Phase 0: 网关骨架 + 6张表 + 代码生成 + 字典 + API"
git push && git tag phase-0-done

---

Phase 1：Owl 适配器 + 视频设备页（Day 3-6）

Owl 端口: 15123（非 80）。PTZ 仅方向键（continuous+stop），不支持预设位。

Day 3 — OwlAdapter

创建 Adapters.Owl，实现 IHasFlatDevices+IHasStreams+IAcceptsMetadataPush。Token: GET /login/key → RSA → POST /login。

Day 4 — 管理端设备页面框架

DeviceManager/index.vue + RegionTree.vue + DeviceTable.vue。

Day 5 — 视频操作 + Jessibuca

VideoDeviceActions.vue + 播放弹窗 + 方向键云台面板。

Day 6 — 联调 + [可选]AI事件接入

---

Phase 2：MC4.0 + IoT（Day 7-11）

同上 v2.1 手册，增加 MC4.0 skip/limit 分页转换。

---

Phase 3：warehouse 联调（Day 12-17）

Phase 4：验证发布（Day 18-20）

同上 v2.1 手册，发布标签 v3.0.0。

---

附录 A：每日检查清单

□ 新增 C# 服务实现 IDependency
□ Controller 在 Partial/ 目录
□ 前端在 extension/ 目录
□ 未修改自动生成文件
□ 网关同步走字段分治
□ parentSourceId 已映射
□ 实时数据未写 IoT_DeviceData
□ dotnet build 零错误

附录 B：端口分配

服务	端口
IntegrationGateway	5100
VolPro.WebApi	9100
web.vite	9000
warehouse	9200
Owl 管理端	15123
MC4.0	3000

附录 C：里程碑

标签	指向
phase-0-done	网关修正 + 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