# 海康 NVR 一分钟录像下载接口

## 接口

`POST /hik/nvr/playback/clips/download`

接口以 `centerTime` 为中心，默认下载前 30 秒和后 30 秒，总计 1 分钟。NVR
端口、账号和密码全部从 `basedata_eqpbook_nvr` 读取；请求只提交共用设备树中的
`nvrIp + channel`。

请求示例：

```json
{
  "nvrIp": "192.168.1.249",
  "channel": 1,
  "centerTime": "2026-07-28 11:55:00"
}
```

该请求对应的录像范围为：

```text
2026-07-28 11:54:30 - 2026-07-28 11:55:30
```

`streamType` 默认是 `1`（主码流）；`beforeSeconds` 和 `afterSeconds` 默认都是
`30`，也可以显式传入，单侧允许范围为 `0-300` 秒。

## PowerShell 下载命令

Windows PowerShell 中的 `curl` 可能是 `Invoke-WebRequest` 的别名，因此需要明确
使用 `curl.exe`：

```powershell
curl.exe --fail-with-body -X POST "http://localhost:28081/hik/nvr/playback/clips/download" `
  -H "Content-Type: application/json" `
  --data-raw '{"nvrIp":"192.168.1.249","channel":1,"centerTime":"2026-07-28 11:55:00"}' `
  --output "hik-clip-20260728-115500.mp4"
```

也可以使用 PowerShell 原生命令：

```powershell
$body = @{
  nvrIp = "192.168.1.249"
  channel = 1
  centerTime = "2026-07-28 11:55:00"
} | ConvertTo-Json

Invoke-WebRequest `
  -Method Post `
  -Uri "http://localhost:28081/hik/nvr/playback/clips/download" `
  -ContentType "application/json" `
  -Body $body `
  -OutFile "hik-clip-20260728-115500.mp4"
```

## 历史回放页面下载

历史回放页面顶部查询区已增加“下载时刻”和“下载1分钟”，并继续复用外层共用
设备树当前选择的 `nvrIp + channel`：

1. 在“回放日期”中选择录像日期。
2. 在“下载时刻（前后各30秒）”中填写需要下载的时刻，例如 `11:55:00`。
3. 点击“下载1分钟”，页面会下载 `11:54:30 - 11:55:30` 的 MP4。

如果“下载时刻”留空，页面会使用当前正在回放的设备时刻作为中心。下载期间不会
停止已有的历史回放会话；同一页面一次只会提交一个下载任务。

目标时间尚未到达时，页面会在发送请求前弹窗提醒；直接调用接口也会被后端拒绝。
目标时间没有录像、录像中间断档或前后不足 30 秒时，页面会弹窗展示后端返回的
具体原因，不会下载空文件或不完整片段。

## 处理规则

- 先查询目标一分钟是否由一段连续录像完整覆盖。
- 未来中心时刻返回 `400`。
- 没有录像时返回 `404`。
- 录像中间断档或前后不足 30 秒时返回 `409`，不会生成伪造的一分钟文件。
- 海康 SDK 把录像下载到服务端独立临时目录。
- FFmpeg 优先保留视频原码流并将音频转换为 AAC，封装成支持快速起播的 MP4。
- 音频封装失败时自动降级为纯视频 MP4。
- HTTP 下载完成、处理失败或客户端中途断开后，服务端都会清理该请求的临时文件。

Swagger UI 中可查看完整字段和错误响应：

```text
http://localhost:28081/swagger-ui/index.html
```