From fe90fbea3ab876fcf1e9a7ad78e072b8018ebcc5 Mon Sep 17 00:00:00 2001 From: g82tt Date: Sat, 16 May 2026 14:20:21 +0800 Subject: [PATCH] v3.0_manual_and_db --- doc/db_init.sql | 2 +- doc/整合方案/SecMPS_整合项目实施手册_v3.0.md | 335 +++++++++++++++++++ 2 files changed, 336 insertions(+), 1 deletion(-) create mode 100644 doc/整合方案/SecMPS_整合项目实施手册_v3.0.md diff --git a/doc/db_init.sql b/doc/db_init.sql index cab9b07..6c51b81 100644 --- a/doc/db_init.sql +++ b/doc/db_init.sql @@ -1,5 +1,5 @@ -- ============================================ --- SecMPS v2.0 数据库建表脚本（6张表） +-- SecMPS v3.0 数据库建表脚本（6张表） -- 数据库: gljs_main -- 扩展表已合并到 Base_Device.ExtraData(JSON) -- ============================================ diff --git a/doc/整合方案/SecMPS_整合项目实施手册_v3.0.md b/doc/整合方案/SecMPS_整合项目实施手册_v3.0.md new file mode 100644 index 0000000..b2937c5 --- /dev/null +++ b/doc/整合方案/SecMPS_整合项目实施手册_v3.0.md @@ -0,0 +1,335 @@ +# 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 标准流程 + +```bash +# 开始 +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） + +```bash +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 下拉框可选到字典值。 + +### 合并 + +```bash +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） + +```bash +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 告警同步。 + +### 合并 + +```bash +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） + +```bash +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 收到实时数据和告警。 + +### 合并 + +```bash +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） + +```bash +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。 + +### 合并 + +```bash +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） + +```bash +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 文档、部署手册、组件说明。 + +### 合并 + 发布 + +```bash +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