# 海康威视视频应用服务 API — Spring Boot 集成

## 功能概述

| 接口 | 说明 |
|------|------|
| `GET  /api/cameras` | 分页获取摄像头资源列表 |
| `GET  /api/cameras/{cameraIndexCode}` | 查询摄像头详情 |
| `GET  /api/cameras/{cameraIndexCode}/preview-url` | 快捷获取实时预览播放地址 |
| `POST /api/cameras/preview-url` | 获取实时预览播放地址（完整参数） |
| `POST /api/cameras/playback-url` | 获取录像回放播放地址 |

---

## Web 监控界面

启动后访问 `http://localhost:8080` 即可打开视频监控界面：

- 左侧配置平台 IP / AppKey / AppSecret，点击「连接插件 & 初始化」
- 自动加载摄像头列表，点击任意摄像头即可播放实时视频
- 支持**实时预览** / **录像回放**切换
- 支持 1/4/9 分屏显示
- 抓图、本地录像等快捷操作

> **前提：** 在 Windows 客户端安装海康官方 `VideoWebPlugin.exe`，
> 并将 JS 插件文件放入 `src/main/resources/static/js/` 目录。

---

## 快速开始

### 1. 配置 application.yml

```yaml
hikvision:
  api:
    host: https://192.168.1.100       # 平台IP或域名
    app-key: your_app_key             # 开放平台应用AppKey
    app-secret: your_app_secret       # 开放平台应用AppSecret
```

> AppKey/AppSecret 在海康 iSecure Center 开放平台 → 应用管理 → 创建应用 后获取。

### 2. 编译运行

```bash
mvn clean package -DskipTests
java -jar target/hikvision-video-api-1.0.0.jar
```

---

## 接口调用示例

### 获取摄像头列表

```bash
curl "http://localhost:8080/api/cameras?pageNo=1&pageSize=20"
```

响应：
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "total": 100,
    "pageNo": 1,
    "pageSize": 20,
    "totalPage": 5,
    "list": [
      {
        "cameraIndexCode": "abc123",
        "cameraName": "1号楼入口",
        "onlineStatus": "1",
        "installPlace": "1号楼大门"
      }
    ]
  }
}
```

---

### 获取实时预览播放地址（RTSP）

```bash
curl "http://localhost:8080/api/cameras/abc123/preview-url?protocol=1"
```

响应：
```json
{
  "code": 200,
  "data": {
    "url": "rtsp://192.168.1.100:554/openUrl/xxxtoken"
  }
}
```

### 获取实时预览播放地址（HLS）

```bash
curl -X POST http://localhost:8080/api/cameras/preview-url \
  -H "Content-Type: application/json" \
  -d '{
    "cameraIndexCode": "abc123",
    "streamType": 0,
    "protocol": 3,
    "transmode": 1
  }'
```

响应：
```json
{
  "code": 200,
  "data": {
    "url": "https://192.168.1.100/openUrl/xxxtoken/index.m3u8"
  }
}
```

---

### 获取录像回放播放地址

```bash
curl -X POST http://localhost:8080/api/cameras/playback-url \
  -H "Content-Type: application/json" \
  -d '{
    "cameraIndexCode": "abc123",
    "beginTime": "2024-01-01T00:00:00.000+08:00",
    "endTime":   "2024-01-01T01:00:00.000+08:00",
    "protocol": 1,
    "recordType": 0
  }'
```

---

## 协议类型说明

| protocol值 | 协议 | 说明 |
|------------|------|------|
| 1 | RTSP | 适合 VLC、ffmpeg 等本地播放 |
| 2 | RTMP | 适合 Flash/流媒体服务器转发 |
| 3 | HLS | 适合 Web 页面播放（video.js、hls.js） |
| 4 | FLV (HTTP-FLV) | 适合 Web 低延时播放（flv.js） |

---

## 项目结构

```
src/main/java/com/hikvision/video/
├── HikvisionVideoApplication.java     # 启动类
├── config/
│   └── HikvisionProperties.java       # 配置读取
├── controller/
│   └── VideoController.java           # REST接口
├── model/
│   └── HikModels.java                 # 请求/响应模型
├── service/
│   └── HikvisionVideoService.java     # 业务逻辑 & API调用
└── util/
    ├── HikvisionSignUtil.java          # HMAC-SHA256签名
    └── HttpUtil.java                   # HTTP请求工具
```

---

## 签名说明

海康 API 采用 **HMAC-SHA256** 签名鉴权，签名字符串格式：

```
{METHOD}\n
{Accept}\n
{Content-Type}\n
x-ca-key:{AppKey}\n
x-ca-nonce:{随机UUID}\n
x-ca-timestamp:{毫秒时间戳}\n
{请求路径}
```

签名结果 Base64 编码后放入请求头 `X-Ca-Signature`。

---

## 常见错误码

| code | 含义 | 解决方案 |
|------|------|---------|
| 0 | 成功 | — |
| 401 | 鉴权失败 | 检查 AppKey/AppSecret 配置 |
| 1001 | 参数错误 | 检查 cameraIndexCode 是否存在 |
| 17004 | 摄像头离线 | 检查设备在线状态 |
| 10001 | 无权限 | 检查应用是否有摄像头访问权限 |