XW-AIOT/aiot-platform-cloud
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
feat/iot-2.0
aiot-platform-cloud/openspec/changes/add-video-module-wvp-migration/proposal.md
lzh 599314e026 docs(video): WVP-Platform 迁移提案 (proposal + tasks + design) 
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
2026-04-05 18:18:53 +08:00

7.4 KiB
Raw Permalink Blame History

Proposal: 迁移 WVP-Platform 到 viewsh-module-video

Change ID: add-video-module-wvp-migration Status: Draft Branch: feature/video-module Source: C:\workspace\java17\wvp-platform (WVP-PRO v2.7.4, feature 分支)

Context

项目需要视频监控管理能力（摄像头管理、国标 GB28181 信令、视频流、NVR 对接）。WVP-Platform 是一个成熟的开源 GB28181 视频平台（796 个 Java 文件），需要将其核心代码迁移到已创建的 viewsh-module-video 微服务模块中。

已完成

  • viewsh-module-video 模块骨架已创建（api + server），端口 48093
  • 网关路由已配置（video-admin-api / video-app-api）
  • 分支 feature/video-module 已建立并提交骨架

核心决策（已确认）

决策项 结论
ORM 全部改为 MyBatis Plus（BaseMapperX）
认证 丢弃 WVP 认证，用 viewsh 框架 Security
数据库 独立 aiot-video 数据库
AI 模块 一起迁移
JT1078 本次不迁，后续再说
OkHttp 保留（调用 ZLMediaKit REST API）

Scope

迁移范围（~700 文件）

WVP 模块 文件数 说明
gb28181/ ~261 GB28181 国标核心（SIP 信令、设备、通道、播放、级联）
media/ ~78 流媒体集成（ZLMediaKit + ABL 适配器）
aiot/ ~50 AI 告警、边缘设备、ROI、截图
streamProxy/ ~15 拉流代理
streamPush/ ~15 推流管理
storager/ ~15 Redis 缓存存储、Mapper（RedisCatchStorageImpl 被 67 个文件引用）
vmanager/ ~40 录像计划、云端录像、RTP 配置
service/ ~30 通用业务服务
common/ ~20 公共工具
conf/（部分） ~15 SIP/Media/Redis/WebSocket/线程池配置
utils/ ~10 工具类

不迁移

WVP 模块 原因
conf/security/ 用 viewsh 框架认证替换
vmanager/user/ 用 viewsh-module-system 替代
jt1078/ 后续再迁
conf/ftpServer/ 非核心，按需
conf/MybatisConfig.java 框架已有
conf/SpringDocConfig.java 框架已有
User/Role 相关 Mapper 和 DO 框架已有

Constraints（约束集）

Hard Constraints（硬约束）

  1. HC-01 SIP 协议栈不可替换 — JAIN SIP 1.3.0-91 是 GB28181 核心，没有替代方案
  2. HC-02 启动顺序必须保留 — SipLayer(@Order 10) → MediaServerConfig(@Order 12) → PlatformService(@Order 15) → DeviceService(@Order 16)
  3. HC-03 异步处理必须保留 — SIP 信令处理通过 @Async("taskExecutor") 异步执行，阻塞会导致设备超时
  4. HC-04 ZLMediaKit Hook 路径必须保留 — /index/hook/* 是 ZLM 配置的回调地址，改路径需要同步改 ZLM 配置
  5. HC-05 DO 继承框架标准基类 — 业务表 DO 继承 TenantBaseDO（含 tenantId/createTime/updateTime/creator/updater/deleted），共享表 DO 继承 BaseDO。统一使用逻辑删除，WVP 原有 39 处硬删除（DELETE FROM）改为 MyBatis Plus 的 deleteById()/delete(wrapper)。含唯一索引的表需将 deleted 加入联合唯一索引
  6. HC-06 Mapper 必须继承 BaseMapperX — viewsh 框架的 ORM 标准
  7. HC-09 RedisTemplate 隔离 — WVP 用 FastJSON2 序列化的 RedisTemplate 必须声明为独立 Bean（videoRedisTemplate），不能覆盖框架的 Jackson 版本，否则其他模块 Redis 全部崩溃
  8. HC-10 不引入 PageHelper — WVP 用 PageHelper 分页，但不能引入 pagehelper-spring-boot-starter，会和 MyBatis Plus 分页插件冲突导致 double pagination
  9. HC-11 fastjson2 extension 用 spring6 版本 — WVP 依赖 fastjson2-extension-spring5，必须改为 fastjson2-extension-spring6（Spring Boot 3.x 基于 Spring 6）
  10. HC-12 Java 版本兼容 — WVP 编译目标是 JDK 21，但经扫描实际未使用 Java 21 专有语法（仅用了 isBlank 等 Java 11 特性），风险低，编译目标改为 17 即可
  11. HC-13 多租户支持 — WVP 表需要加 tenant_id 列，DO 继承含 tenantId 的 VideoBaseDO，框架租户拦截器自动追加 WHERE tenant_id=?。少数全局共享表（如 media_server）需加入 viewsh.tenant.ignore-tables 排除
  12. HC-07 独立数据库 — video-server 连接独立的 aiot-video 库，通过多数据源配置
  13. HC-08 WVP 源从 feature 分支获取 — WVP 项目在 C:\workspace\java17\wvp-platform，需确认其 feature 分支

Soft Constraints（软约束）

  1. SC-01 包名规范 — com.viewsh.module.video.*，符合项目命名规范
  2. SC-02 Controller 路径 — 放到 controller/admin/ 包下，框架自动加 /admin-api 前缀
  3. SC-03 分页统一 — PageHelper → MyBatis Plus Page + PageResult
  4. SC-04 Redis key 隔离 — 加 video: 前缀，避免和其他模块冲突
  5. SC-05 异常码段 — 1-060-000-000 段

Dependencies（依赖关系）

框架已有（直接复用）

  • Hutool 5.8.42、Guava 33.5.0、HttpClient、fastexcel

必须新增

依赖 版本 用途
jain-sip-ri 1.3.0-91 GB28181 SIP 协议栈
dom4j 2.1.4 SIP XML 消息解析
okhttp 4.12.0 调用 ZLMediaKit REST API
okhttp-digest 3.1.1 HTTP Digest 认证
bouncycastle 1.78.1 SIP 认证加密
fastjson2 2.0.57 Redis 序列化（WVP 用 v2）
fastjson2-extension-spring6 2.0.57 Spring 6 适配（不能用 spring5 版本）

按需引入

依赖 版本 用途
paho.mqttv5 1.2.5 AI MQTT 推送（框架有 v3，WVP 用 v5）
jts-core 1.18.2 地理位置计算
cos_api 5.6.227 AI 截图上传腾讯云（可后续替换为 MinIO）

Success Criteria

  1. SC-BUILD: mvn compile -pl viewsh-module-video/viewsh-module-video-server 编译通过
  2. SC-BOOT: VideoServerApplication 启动成功，SIP 端口监听正常
  3. SC-SWAGGER: 访问 http://localhost:48093/doc.html 能看到接口文档
  4. SC-GATEWAY: 通过网关 http://localhost:48080/admin-api/video/ 能路由到 video-server
  5. SC-SIP: 模拟器或真实摄像头能通过 SIP 注册到平台
  6. SC-PLAY: 点播一路摄像头，返回可用的播放地址
  7. SC-DB: 独立 aiot-video 数据库中表结构完整，CRUD 正常

Risks

风险 等级 缓解措施
ORM 改造量大（23 个 Mapper） 高 分批改造，先简单后复杂；复杂 JOIN SQL 保留 @Select
SIP 初始化顺序问题 中 @Order 值从 10/12/15/16 改为 100/102/105/106，给框架 Bean 留空间
RedisTemplate Bean 冲突 高 WVP 用独立 videoRedisTemplate Bean，内部 30+ 文件加 @Qualifier
硬删除改逻辑删除 中 WVP 39 处 DELETE FROM 改为 MyBatis Plus deleteById()，唯一索引加 deleted 字段
Java 版本兼容性 低 经扫描 WVP 未使用 Java 21 专有语法，仅改编译目标即可
多租户改造 中 所有业务表加 tenant_id 列，共享表（media_server）加入 ignore-tables
PageHelper 与 MyBatis Plus 冲突 中 绝不引入 pagehelper 依赖，改用 MyBatis Plus 分页
WVP 内部循环依赖 低 application.yaml 已配 allow-circular-references=true
表结构改造（加 VideoBaseDO 字段） 中 编写 SQL 迁移脚本，加 createTime/updateTime/creator/updater