# 海康 NVR HLS 回放控制台设计

**状态：** 已获用户确认，修改仅保留在本地工作区，不提交 Git。

## 1. 目标

为现有海康 NVR SDK 控制的 HLS 回放能力增加一个可直接打开的浏览器播放器。用户只需要在页面选择设备、日期和时间并点击查询，页面负责创建、轮询和控制回放会话，不再手工重复调用 Swagger 接口。

播放器覆盖当前后端已经支持的能力：

- 固定按北京时间输入和展示查询、跳转时间；
- 展示实际存在的连续录像区间；
- 自动创建 HLS 会话并等待 `STARTING -> PLAYING`；
- 播放、暂停、恢复、1/2/4/8 倍速、时间轴跳转和全屏；
- HLS 地址只在浏览器同源页面中使用，不向页面返回 NVR 密码。

## 2. 已确认的配置策略

采用用户选择的 B 方案：NVR IP、SDK/RTSP 端口、账号和密码固定在 Spring Boot 后端配置中。页面只接收通道、码流类型和时间范围。

配置前缀为 `hik.playback.ui`：

```yaml
hik:
  playback:
    ui:
      device-name: 海康 NVR
      nvr-ip: ${HIK_NVR_IP:192.168.1.249}
      sdk-port: ${HIK_NVR_SDK_PORT:8000}
      rtsp-port: ${HIK_NVR_RTSP_PORT:554}
      username: ${HIK_NVR_USERNAME:admin}
      password: ${HIK_NVR_PASSWORD:}
      default-channel: 1
      default-stream-type: 1
```

密码使用环境变量 `HIK_NVR_PASSWORD`，不会写入 HTML、Swagger 响应或日志。若密码为空，配置接口仍可打开页面，但创建会话时返回明确的配置错误。

## 3. 后端接口

### 3.1 读取页面配置

`GET /hik/nvr/playback/hls/ui/config`

返回页面需要的非敏感配置、设备树和默认通道。返回对象不包含 `password`，并通过 `configured` 标识后端是否已经具备创建会话的必要配置。

### 3.2 页面创建回放

`POST /hik/nvr/playback/hls/ui/sessions`

请求体只包含：

```json
{
  "channel": 1,
  "streamType": 1,
  "startTime": "2026-07-13 12:00:00",
  "endTime": "2026-07-13 13:00:00"
}
```

控制台控制请求继续复用现有 `/sessions/{sessionId}/controls` 和 `DELETE /sessions/{sessionId}`，避免复制回放状态机。

## 4. 前端实现

不引入 Node、React 或 Thymeleaf，使用 Spring Boot 静态资源目录中的 `playback.html`，通过 `http://localhost:18080/playback.html` 打开。这样与后端同源，接口无需额外 CORS 配置。

页面采用“工业监控台”视觉方向：冷白工作区、深海军蓝文字、单一高亮蓝色、细边框卡片、淡网格背景和有限的入场动画。布局包含：

1. 左侧设备树：固定 NVR、分组和可选通道；
2. 顶部时间查询栏：日期、开始时间、结束时间、查询和重置；
3. 中央视频舞台：HLS 视频、状态徽标、错误/等待提示和当前北京时间；
4. 下方录像轨道：按请求时间范围绘制实际录像块，点击轨道发送 `SEEK`；
5. 控制栏：到起点、暂停/恢复、到末尾、当前时间、音量、1/2/4/8 倍速和全屏。

播放器使用 hls.js CDN，在 Chrome/Edge 中加载 HLS；Safari 等支持原生 HLS 的浏览器直接设置 `video.src`。当后端返回新的 `generation` 或 HLS 地址时，销毁旧实例并重新加载，防止跳转后继续使用旧切片。

## 5. 状态与错误处理

- 页面加载时读取配置；读取失败显示连接错误，不阻止页面布局展示。
- 查询时禁用查询按钮，创建成功后轮询会话状态；`STARTING` 显示“等待首个关键帧”，`PLAYING` 才加载 m3u8。
- 404、409、502、503 等后端错误解析 `message` 并显示在视频舞台和顶部状态栏。
- 页面关闭或切换查询时，删除旧会话，释放 SDK、FFmpeg 和 ZLMediaKit 资源。
- 暂停、恢复、倍速和跳转均由后端 SDK 控制；前端不使用 `video.playbackRate` 伪造 NVR 倍速。

## 6. 文件变更

- 新增 `HikNvrPlaybackUiProperties`、页面配置 DTO、页面创建请求 DTO；
- 新增 `HikNvrPlaybackUiController`；
- 在 `application.yml` 增加 `hik.playback.ui` 固定配置；
- 新增 `src/main/resources/static/playback.html`；
- 新增后端控制器单元测试和页面接口契约测试；
- 更新设计文档与实施计划，所有变更不提交 Git。

## 7. 自审结论

- 配置策略与用户确认的 B 方案一致，页面不要求用户输入 NVR 账号密码；
- 页面只依赖现有 HLS 会话服务，不改变 SDK、FFmpeg 或 ZLMediaKit 数据通路；
- 倍速范围与现有服务的 1/2/4/8 约束一致；
- HLS `STARTING` 轮询和 generation 重载覆盖了此前 VLC/HLS 首帧延迟及跳转旧切片问题；
- 静态页面无需新增前端构建环境，适合当前 Spring Boot 项目；
- 密码使用环境变量，避免将用户提供的凭据硬编码到仓库。