docs(video): WVP-Platform 迁移提案 (proposal + tasks + design)

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

openspec/changes/add-video-module-wvp-migration/proposal.md

@@ -0,0 +1,138 @@
+# 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 |