inspect-nvr/docs/superpowers/plans/2026-07-14-hik-nvr-playback-console.md

海康 NVR HLS 回放控制台实施计划

本计划对应 docs/superpowers/specs/2026-07-14-hik-nvr-playback-console-design.md。所有修改留在本地，不提交 Git。

1. 新增页面配置模型

文件：

• src/main/java/com/inspect/nvr/hik/config/HikNvrPlaybackUiProperties.java
• src/main/java/com/inspect/nvr/hik/domain/HikNvrPlaybackUiConfig.java
• src/main/java/com/inspect/nvr/hik/domain/HikNvrPlaybackUiSessionRequest.java

实现：

• 绑定 hik.playback.ui，保存 NVR 地址、端口、账号、密码、默认通道和设备树通道；
• toPublicConfig() 只返回页面所需非敏感字段；
• toPlaybackRequest() 将页面请求与后端固定配置合并，拒绝缺少密码或基础连接参数的配置；
• 请求 DTO 只允许 channel、streamType、startTime、endTime。

2. 新增页面接口

文件： src/main/java/com/inspect/nvr/hik/controller/HikNvrPlaybackUiController.java

实现：

• GET /hik/nvr/playback/hls/ui/config 返回安全的页面配置；
• POST /hik/nvr/playback/hls/ui/sessions 合并固定配置后调用现有 HLS 服务；
• 复用已有异常处理和会话控制接口，不复制回放状态机；
• 增加 OpenAPI 中文说明和请求示例。

3. 增加运行配置

文件： src/main/resources/application.yml

增加 hik.playback.ui 默认项，地址默认使用当前 NVR 192.168.1.249，密码默认空并支持环境变量覆盖；增加可配置的设备分组和通道列表。

4. 实现播放器页面

文件： src/main/resources/static/playback.html

实现：

• 工业监控台视觉：冷白网格背景、海军蓝文字、蓝色状态色、卡片和时间轨道；
• 设备树、日期/时间查询、视频舞台、状态徽标、录像区间轨道、控制栏和全屏；
• 使用 hls.js CDN 或浏览器原生 HLS 播放；
• 创建会话后轮询 STARTING/PLAYING，只在 HLS 就绪后加载 m3u8；
• 控制按钮调用暂停、恢复、1/2/4/8 倍速、SEEK 和删除接口；
• 处理 generation 变化、旧会话清理、错误提示、音量和时间轴点击跳转；
• 不在任何 HTML、脚本或请求体中出现 NVR 密码。

5. 测试与验证

文件： src/test/java/com/inspect/nvr/hik/controller/HikNvrPlaybackUiControllerTest.java

• 验证配置响应不包含 password；
• 验证页面创建请求只向现有服务传入后端固定凭据和页面时间参数；
• 验证空密码配置返回明确的 400；
• 运行 mvn test，确认既有 62 个测试及新增测试通过；
• 使用 Maven 打包后检查 target/classes/static/playback.html；
• 若本地应用可访问，使用 HTTP 请求验证配置接口、静态页面和缺少密码时的错误响应。