# 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` 排除
7. **HC-07 独立数据库** — video-server 连接独立的 `aiot-video` 库，通过多数据源配置
8. **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 |