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

SecMPS 整合项目实施手册

版本: v3.0
日期: 2026-05-16
基于: SecMPS_最终整合方案_v3.0.md
工期: 18-20 个工作日
开发模式: 单人 + Agent，Squash Merge 主线策略

---

网关代码兼容性评估

基于 v3.0 方案对 Phase 0 已生成的 gateway/ 代码进行评估

组件	状态	说明
Core/Abstractions (7接口)	✅ 可用	与 v3.0 完全兼容
Core/Models (10模型)	✅ 可用	与 v3.0 完全兼容
Core/Infrastructure (AdapterRegistry/TokenManager/RateLimiter)	✅ 可用	无变更
Host/Program.cs	⚠️ 需微调	增加 HttpClient 注册
Host/HealthController	✅ 可用	B1 接口无变更
Host/DevicesController	✅ 可用	B2 接口无变更
Host/PointsController	✅ 可用	B4/B5 接口无变更
Host/AlarmsController	✅ 可用	B8/B9 接口无变更
Host/SyncController	✅ 可用	B3 接口无变更
Host/StreamsController	⚠️ 需增加	缺少 B6b playback 端点
Host/RegisterController	❌ 缺失	需新建 A1/A2 接口
appsettings.json	❌ 需重写	需改为 v3.0 格式
IGatewayClient (调用Vol.Pro)	❌ 缺失	需新建

结论

现有代码 70% 可用，需 5 处改动：

1. 重写 appsettings.json（删除适配器硬编码，改为 VolProUrl/NodeCode/NodeToken）
2. 新增 RegisterController.cs（A1 注册 + A2 心跳）
3. StreamsController.cs 增加 B6b playback 端点
4. Program.cs 增加 HttpClient 注册 + 网关启动时调 Vol.Pro 注册
5. 新增 GatewayClient.cs（网关调用 Vol.Pro API 的 HTTP 封装）

预计改动量：约 200 行新增代码，不改动现有接口和模型。

---

分支管理策略

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/ 代码（5 处改动，约 200 行）

1. 重写 appsettings.json:

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

2. 新增 RegisterController.cs:

• POST /api/gateway/register — 网关启动注册（Upsert 数据库）
• POST /api/gateway/heartbeat — 网关每 15s 心跳

3. StreamsController.cs 增加:

• GET {adapter}/{channelId}/playback?start=&end= — 回放取流

4. Program.cs 增加:

builder.Services.AddHttpClient("VolPro", c => {
    c.BaseAddress = new Uri(builder.Configuration["VolProBaseUrl"]);
});
// 启动后自动注册
var registry = app.Services.GetRequiredService<AdapterRegistry>();
var http = app.Services.GetRequiredService<IHttpClientFactory>();
await RegisterWithVolPro(registry, http, app.Configuration);

5. 新增 GatewayClient.cs: 网关调用 Vol.Pro API 的封装类（注册/心跳/同步设备/同步告警）

验证: dotnet build 零错误 + Gateway /health 200

任务 1.2: 执行 db_init.sql（6张表）。验证: 唯一索引存在。

任务 1.3: Vol.Pro 侧 GatewayClient 实现 + GatewayNodeController.cs（A1/A2/A3/A4 服务端）。验证: 可成功注册并心跳。

Day 2 — 代码生成 + 字典初始化

任务 2.1: 代码生成器跑 6 张表。

任务 2.2: DeviceManagerController.cs (Partial/)。

任务 2.3: 字典初始化（8个）。

任务 2.4: SyncDevicesJob + 心跳超时检测 Job。

合并

git add -A && git commit -m "Phase 0 完成"
git checkout master && git merge --squash phase/0-infrastructure
git commit -m "Phase 0: 网关修正 + 6张表 + 代码生成 + 字典"
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