254 lines
8.0 KiB
Markdown
254 lines
8.0 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 标准流程
|
||
|
||
```bash
|
||
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`:
|
||
```json
|
||
{
|
||
"VolProBaseUrl": "http://localhost:9100",
|
||
"NodeCode": "gw-31ku",
|
||
"NodeToken": "xxxxxxxxxx",
|
||
"Urls": "http://*:5100"
|
||
}
|
||
```
|
||
|
||
`Program.cs` 启动逻辑:
|
||
```csharp
|
||
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/Warehouse/Services/GatewayClient.cs` (IDependency)。（不放在 VolPro.Core 下，框架升级会覆盖）
|
||
封装: 注册/心跳/设备同步/告警同步/实时数据/取流/云台/告警确认。
|
||
|
||
**任务 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。
|
||
|
||
### 合并
|
||
|
||
```bash
|
||
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
|