# 海康 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 请求验证配置接口、静态页面和缺少密码时的错误响应。