# 文档

## default

## 摄像头控制 Controller

MVP API 接口：

- GET /camera/list 获取摄像头列表
- GET /camera/{id} 获取摄像头信息
- POST /camera/switch 切换摄像头通道
- GET /camera/current 获取当前通道

后台 PTZ 接口（可选）：

- POST /camera/{id}/ptz/start 开始 PTZ 控制
- POST /camera/{id}/ptz/stop 停止 PTZ 控制

### 获取摄像头列表

维护人：TG Live

#### URL

- 本地开发环境: `POST` http://localhost:10050/api/camera/list
- 开发环境: `POST` https://tg-live-game.pwtk.cc/api/camera/list

描述：获取摄像头列表

ContentType：`application/json`

#### 请求参数

##### Body Parameter

| 名称      | 类型   | 必填 | 最大长度 | 描述            | 示例值      |
| --------- | ------ | ---- | -------- | --------------- | ----------- |
| machineId | String | 否   | -        | 机器 ID（可选） | machine_001 |

#### 请求示例

```
{
    "machineId": "machine_001"
}
```

#### 响应参数

| 名称 | 类型 | 必填 | 最大长度 | 描述 | 示例值 |
| --- | --- | --- | --- | --- | --- |
| success | Boolean | 否 | - | 请求是否成功 | true |
| errCode | String | 否 | - | 错误码（失败时返回） |  |
| errMessage | String | 否 | - | 错误信息（失败时返回） |  |
| data | array | 否 |  | 响应数据 (ActualType: List) |  |
| └ cameraId | String | 否 | - | 摄像头 ID | cam_001 |
| └ name | String | 否 | - | 摄像头名称 | 主摄像头 |
| └ lssId | String | 否 | - | 绑定的 LSS 节点 ID | lss_001 |
| └ model | String | 否 | - | 摄像头型号 | DS-2CD2143G2-IS |
| └ rtspUrl | String | 否 | - | RTSP 推流地址 | rtsp://admin:password@192.168.1.100:554/Streaming/Channels/101 |
| └ channelNo | String | 否 | - | 通道号 | 1 |
| └ status | String | 否 | - | 摄像头状态: online, offline, connecting, failed, error, unknown | online |
| └ capability | String | 否 | - | 摄像头能力: switch_only, ptz_enabled | ptz_enabled |
| └ ptzSupported | Boolean | 否 | - | 是否支持 PTZ | true |
| └ remark | String | 否 | - | 备注 |  |
| └ enabled | Boolean | 否 | - | 是否启用 | true |

#### 响应示例

```
{
    "success": true,
    "errCode": "string",
    "errMessage": "string",
    "data": [
        {
            "cameraId": "cam_001",
            "name": "主摄像头",
            "lssId": "lss_001",
            "model": "DS-2CD2143G2-IS",
            "rtspUrl": "rtsp://admin:password@192.168.1.100:554/Streaming/Channels/101",
            "channelNo": "1",
            "status": "online",
            "capability": "ptz_enabled",
            "ptzSupported": true,
            "remark": "string",
            "enabled": true
        }
    ]
}
```

#### 错误码

无

### 获取摄像头信息

维护人：TG Live

#### URL

- 本地开发环境: `GET` http://localhost:10050/api/camera/{cameraId}
- 开发环境: `GET` https://tg-live-game.pwtk.cc/api/camera/{cameraId}

描述：获取摄像头信息

ContentType：`application/x-www-form-urlencoded;charset=UTF-8`

#### Path 参数

| 名称     | 必填 | 描述      | 示例值     |
| -------- | ---- | --------- | ---------- |
| cameraId | 是   | 摄像头 ID | camera_001 |

#### 请求参数

#### 响应参数

| 名称 | 类型 | 必填 | 最大长度 | 描述 | 示例值 |
| --- | --- | --- | --- | --- | --- |
| success | Boolean | 否 | - | 请求是否成功 | true |
| errCode | String | 否 | - | 错误码（失败时返回） |  |
| errMessage | String | 否 | - | 错误信息（失败时返回） |  |
| data | object | 否 |  | 响应数据 (ActualType: CameraDTO) |  |
| └ cameraId | String | 否 | - | 摄像头 ID | cam_001 |
| └ name | String | 否 | - | 摄像头名称 | 主摄像头 |
| └ lssId | String | 否 | - | 绑定的 LSS 节点 ID | lss_001 |
| └ model | String | 否 | - | 摄像头型号 | DS-2CD2143G2-IS |
| └ rtspUrl | String | 否 | - | RTSP 推流地址 | rtsp://admin:password@192.168.1.100:554/Streaming/Channels/101 |
| └ channelNo | String | 否 | - | 通道号 | 1 |
| └ status | String | 否 | - | 摄像头状态: online, offline, connecting, failed, error, unknown | online |
| └ capability | String | 否 | - | 摄像头能力: switch_only, ptz_enabled | ptz_enabled |
| └ ptzSupported | Boolean | 否 | - | 是否支持 PTZ | true |
| └ remark | String | 否 | - | 备注 |  |
| └ enabled | Boolean | 否 | - | 是否启用 | true |

#### 响应示例

```
{
    "success": true,
    "errCode": "string",
    "errMessage": "string",
    "data": {
        "cameraId": "cam_001",
        "name": "主摄像头",
        "lssId": "lss_001",
        "model": "DS-2CD2143G2-IS",
        "rtspUrl": "rtsp://admin:password@192.168.1.100:554/Streaming/Channels/101",
        "channelNo": "1",
        "status": "online",
        "capability": "ptz_enabled",
        "ptzSupported": true,
        "remark": "string",
        "enabled": true
    }
}
```

#### 错误码

无

### 切换摄像头通道（MVP 核心）

维护人：TG Live

#### URL

- 本地开发环境: `POST` http://localhost:10050/api/camera/switch
- 开发环境: `POST` https://tg-live-game.pwtk.cc/api/camera/switch

描述：切换摄像头通道（MVP 核心）

ContentType：`application/json`

#### 请求参数

##### Body Parameter

| 名称      | 类型   | 必填 | 最大长度 | 描述        | 示例值      |
| --------- | ------ | ---- | -------- | ----------- | ----------- |
| machineId | String | 是   | -        | 机器 ID     | machine_001 |
| channelId | String | 是   | -        | 目标通道 ID | ch_001      |

#### 请求示例

```
{
    "machineId": "machine_001",
    "channelId": "ch_001"
}
```

#### 响应参数

| 名称          | 类型    | 必填 | 最大长度 | 描述                              | 示例值                           |
| ------------- | ------- | ---- | -------- | --------------------------------- | -------------------------------- |
| success       | Boolean | 否   | -        | 请求是否成功                      | true                             |
| errCode       | String  | 否   | -        | 错误码（失败时返回）              |                                  |
| errMessage    | String  | 否   | -        | 错误信息（失败时返回）            |                                  |
| data          | object  | 否   |          | 响应数据 (ActualType: ChannelDTO) |                                  |
| └ channelId   | String  | 否   | -        | 通道 ID                           | ch_001                           |
| └ name        | String  | 否   | -        | 通道名称                          | 主通道                           |
| └ rtspUrl     | String  | 否   | -        | RTSP 地址                         | rtsp://192.168.1.100:554/stream1 |
| └ defaultView | Boolean | 否   | -        | 是否默认视角                      | true                             |
| └ status      | String  | 否   | -        | 通道状态: ONLINE, OFFLINE         | ONLINE                           |
| └ cameraId    | String  | 否   | -        | 所属摄像头 ID                     | cam_001                          |

#### 响应示例

```
{
    "success": true,
    "errCode": "string",
    "errMessage": "string",
    "data": {
        "channelId": "ch_001",
        "name": "主通道",
        "rtspUrl": "rtsp://192.168.1.100:554/stream1",
        "defaultView": true,
        "status": "ONLINE",
        "cameraId": "cam_001"
    }
}
```

#### 错误码

无

### 获取当前活动通道

维护人：TG Live

#### URL

- 本地开发环境: `GET` http://localhost:10050/api/camera/current
- 开发环境: `GET` https://tg-live-game.pwtk.cc/api/camera/current

描述：获取当前活动通道

ContentType：`application/x-www-form-urlencoded;charset=UTF-8`

#### 请求参数

##### Query Parameter

| 名称      | 类型   | 必填 | 最大长度 | 描述    | 示例值      |
| --------- | ------ | ---- | -------- | ------- | ----------- |
| machineId | string | 是   | -        | 机器 ID | machine_001 |

#### 响应参数

| 名称          | 类型    | 必填 | 最大长度 | 描述                              | 示例值                           |
| ------------- | ------- | ---- | -------- | --------------------------------- | -------------------------------- |
| success       | Boolean | 否   | -        | 请求是否成功                      | true                             |
| errCode       | String  | 否   | -        | 错误码（失败时返回）              |                                  |
| errMessage    | String  | 否   | -        | 错误信息（失败时返回）            |                                  |
| data          | object  | 否   |          | 响应数据 (ActualType: ChannelDTO) |                                  |
| └ channelId   | String  | 否   | -        | 通道 ID                           | ch_001                           |
| └ name        | String  | 否   | -        | 通道名称                          | 主通道                           |
| └ rtspUrl     | String  | 否   | -        | RTSP 地址                         | rtsp://192.168.1.100:554/stream1 |
| └ defaultView | Boolean | 否   | -        | 是否默认视角                      | true                             |
| └ status      | String  | 否   | -        | 通道状态: ONLINE, OFFLINE         | ONLINE                           |
| └ cameraId    | String  | 否   | -        | 所属摄像头 ID                     | cam_001                          |

#### 响应示例

```
{
    "success": true,
    "errCode": "string",
    "errMessage": "string",
    "data": {
        "channelId": "ch_001",
        "name": "主通道",
        "rtspUrl": "rtsp://192.168.1.100:554/stream1",
        "defaultView": true,
        "status": "ONLINE",
        "cameraId": "cam_001"
    }
}
```

#### 错误码

无

### 开始 PTZ 控制（后台专用）

维护人：TG Live

#### URL

- 本地开发环境: `POST` http://localhost:10050/api/camera/{cameraId}/ptz/start
- 开发环境: `POST` https://tg-live-game.pwtk.cc/api/camera/{cameraId}/ptz/start

描述：开始 PTZ 控制（后台专用）

ContentType：`application/x-www-form-urlencoded;charset=UTF-8`

#### Path 参数

| 名称     | 必填 | 描述      | 示例值        |
| -------- | ---- | --------- | ------------- |
| cameraId | 是   | 摄像头 ID | hikvision_ptz |

#### 请求参数

##### Query Parameter

| 名称   | 类型   | 必填 | 最大长度 | 描述        | 示例值 |
| ------ | ------ | ---- | -------- | ----------- | ------ |
| action | string | 是   | -        | PTZ 动作    | up     |
| speed  | int32  | 是   | -        | 速度(1-100) | 50     |

#### 响应参数

| 名称       | 类型    | 必填 | 最大长度 | 描述                        | 示例值 |
| ---------- | ------- | ---- | -------- | --------------------------- | ------ |
| success    | Boolean | 否   | -        | 请求是否成功                | true   |
| errCode    | String  | 否   | -        | 错误码（失败时返回）        |        |
| errMessage | String  | 否   | -        | 错误信息（失败时返回）      |        |
| data       | object  | 否   | -        | 响应数据 (ActualType: Void) |        |

#### 响应示例

```
{
    "success": true,
    "errCode": "string",
    "errMessage": "string",
    "data": {}
}
```

#### 错误码

无

### 停止 PTZ 控制（后台专用）

维护人：TG Live

#### URL

- 本地开发环境: `POST` http://localhost:10050/api/camera/{cameraId}/ptz/stop
- 开发环境: `POST` https://tg-live-game.pwtk.cc/api/camera/{cameraId}/ptz/stop

描述：停止 PTZ 控制（后台专用）

ContentType：`application/x-www-form-urlencoded;charset=UTF-8`

#### Path 参数

| 名称     | 必填 | 描述      | 示例值        |
| -------- | ---- | --------- | ------------- |
| cameraId | 是   | 摄像头 ID | hikvision_ptz |

#### 请求参数

#### 响应参数

| 名称       | 类型    | 必填 | 最大长度 | 描述                        | 示例值 |
| ---------- | ------- | ---- | -------- | --------------------------- | ------ |
| success    | Boolean | 否   | -        | 请求是否成功                | true   |
| errCode    | String  | 否   | -        | 错误码（失败时返回）        |        |
| errMessage | String  | 否   | -        | 错误信息（失败时返回）      |        |
| data       | object  | 否   | -        | 响应数据 (ActualType: Void) |        |

#### 响应示例

```
{
    "success": true,
    "errCode": "string",
    "errMessage": "string",
    "data": {}
}
```

#### 错误码

无

### PTZ 直接控制（兼容前端 pan/tilt/zoom 方式）

与前端海康调试接口一致：直接传 pan/tilt/zoom 值

维护人：TG Live

#### URL

- 本地开发环境: `POST` http://localhost:10050/api/camera/{cameraId}/ptz/control
- 开发环境: `POST` https://tg-live-game.pwtk.cc/api/camera/{cameraId}/ptz/control

描述：PTZ 直接控制（兼容前端 pan/tilt/zoom 方式）

与前端海康调试接口一致：直接传 pan/tilt/zoom 值

ContentType：`application/json`

#### Path 参数

| 名称     | 必填 | 描述      | 示例值        |
| -------- | ---- | --------- | ------------- |
| cameraId | 是   | 摄像头 ID | hikvision_ptz |

#### 请求参数

##### Body Parameter

| 名称    | 类型    | 必填 | 最大长度 | 描述                                                   | 示例值 |
| ------- | ------- | ---- | -------- | ------------------------------------------------------ | ------ |
| pan     | Integer | 否   | 100      | 水平移动速度<br>负值向左，正值向右<br>范围: -100 ~ 100 | 0      |
| tilt    | Integer | 否   | 100      | 垂直移动速度<br>负值向下，正值向上<br>范围: -100 ~ 100 | 0      |
| zoom    | Integer | 否   | 100      | 缩放速度<br>负值缩小，正值放大<br>范围: -100 ~ 100     | 0      |
| channel | Integer | 否   | -        | 通道号（可选，默认 1）                                 | 0      |

#### 请求示例

```
{
    "pan": 0,
    "tilt": 0,
    "zoom": 0,
    "channel": 0
}
```

#### 响应参数

| 名称       | 类型    | 必填 | 最大长度 | 描述                        | 示例值 |
| ---------- | ------- | ---- | -------- | --------------------------- | ------ |
| success    | Boolean | 否   | -        | 请求是否成功                | true   |
| errCode    | String  | 否   | -        | 错误码（失败时返回）        |        |
| errMessage | String  | 否   | -        | 错误信息（失败时返回）      |        |
| data       | object  | 否   | -        | 响应数据 (ActualType: Void) |        |

#### 响应示例

```
{
    "success": true,
    "errCode": "string",
    "errMessage": "string",
    "data": {}
}
```

#### 错误码

无

### 获取预置位列表

<p>异步获取摄像头的预置位列表，结果通过 Ably 推送返回。</p>
<p>预置位是摄像头保存的固定位置点，可快速跳转到该位置。</p>

维护人：TG Live

#### URL

- 本地开发环境: `GET` http://localhost:10050/api/camera/control/{cameraId}/preset/list
- 开发环境: `GET` https://tg-live-game.pwtk.cc/api/camera/control/{cameraId}/preset/list

描述：获取预置位列表

<p>异步获取摄像头的预置位列表，结果通过 Ably 推送返回。</p>
<p>预置位是摄像头保存的固定位置点，可快速跳转到该位置。</p>

ContentType：`application/x-www-form-urlencoded;charset=UTF-8`

#### Path 参数

| 名称     | 必填 | 描述      | 示例值        |
| -------- | ---- | --------- | ------------- |
| cameraId | 是   | 摄像头 ID | hikvision_ptz |

#### 请求参数

##### Query Parameter

| 名称    | 类型  | 必填 | 最大长度 | 描述                                     | 示例值 |
| ------- | ----- | ---- | -------- | ---------------------------------------- | ------ |
| channel | int32 | 否   | -        | 通道号（可选，默认使用摄像头配置的通道） | 1      |

#### 响应参数

| 名称       | 类型    | 必填 | 最大长度 | 描述                          | 示例值 |
| ---------- | ------- | ---- | -------- | ----------------------------- | ------ |
| success    | Boolean | 否   | -        | 请求是否成功                  | true   |
| errCode    | String  | 否   | -        | 错误码（失败时返回）          |        |
| errMessage | String  | 否   | -        | 错误信息（失败时返回）        |        |
| data       | string  | 否   | -        | 响应数据 (ActualType: String) |        |

#### 响应示例

```
{
    "success": true,
    "errCode": "string",
    "errMessage": "string",
    "data": "string"
}
```

#### 错误码

无

### 跳转到预置位

<p>控制摄像头快速移动到指定的预置位位置。</p>
<p>预置位编号从 1 开始，需确保该预置位已存在。</p>

维护人：TG Live

#### URL

- 本地开发环境: `POST` http://localhost:10050/api/camera/control/{cameraId}/preset/goto
- 开发环境: `POST` https://tg-live-game.pwtk.cc/api/camera/control/{cameraId}/preset/goto

描述：跳转到预置位

<p>控制摄像头快速移动到指定的预置位位置。</p>
<p>预置位编号从 1 开始，需确保该预置位已存在。</p>

ContentType：`application/json`

#### Path 参数

| 名称     | 必填 | 描述      | 示例值        |
| -------- | ---- | --------- | ------------- |
| cameraId | 是   | 摄像头 ID | hikvision_ptz |

#### 请求参数

##### Body Parameter

| 名称        | 类型    | 必填 | 最大长度 | 描述       | 示例值 |
| ----------- | ------- | ---- | -------- | ---------- | ------ |
| presetIndex | Integer | 是   | -        | 预置位编号 | 1      |

#### 请求示例

```
{
    "presetIndex": 1
}
```

#### 响应参数

| 名称       | 类型    | 必填 | 最大长度 | 描述                          | 示例值 |
| ---------- | ------- | ---- | -------- | ----------------------------- | ------ |
| success    | Boolean | 否   | -        | 请求是否成功                  | true   |
| errCode    | String  | 否   | -        | 错误码（失败时返回）          |        |
| errMessage | String  | 否   | -        | 错误信息（失败时返回）        |        |
| data       | string  | 否   | -        | 响应数据 (ActualType: String) |        |

#### 响应示例

```
{
    "success": true,
    "errCode": "string",
    "errMessage": "string",
    "data": "string"
}
```

#### 错误码

无

### 设置预置位（保存当前位置）

<p>将摄像头当前的 PTZ 位置保存为预置位。</p>
<p>如果指定的预置位编号已存在，将覆盖原有设置。</p>

维护人：TG Live

#### URL

- 本地开发环境: `POST` http://localhost:10050/api/camera/control/{cameraId}/preset/set
- 开发环境: `POST` https://tg-live-game.pwtk.cc/api/camera/control/{cameraId}/preset/set

描述：设置预置位（保存当前位置）

<p>将摄像头当前的 PTZ 位置保存为预置位。</p>
<p>如果指定的预置位编号已存在，将覆盖原有设置。</p>

ContentType：`application/json`

#### Path 参数

| 名称     | 必填 | 描述      | 示例值        |
| -------- | ---- | --------- | ------------- |
| cameraId | 是   | 摄像头 ID | hikvision_ptz |

#### 请求参数

##### Body Parameter

| 名称        | 类型    | 必填 | 最大长度 | 描述                                      | 示例值 |
| ----------- | ------- | ---- | -------- | ----------------------------------------- | ------ |
| presetIndex | Integer | 是   | -        | 预置位编号                                | 1      |
| presetName  | String  | 否   | 50       | 预置位名称（可选）<br>Validate[max: 50; ] | 位置 1 |

#### 请求示例

```
{
    "presetIndex": 1,
    "presetName": "位置1"
}
```

#### 响应参数

| 名称       | 类型    | 必填 | 最大长度 | 描述                          | 示例值 |
| ---------- | ------- | ---- | -------- | ----------------------------- | ------ |
| success    | Boolean | 否   | -        | 请求是否成功                  | true   |
| errCode    | String  | 否   | -        | 错误码（失败时返回）          |        |
| errMessage | String  | 否   | -        | 错误信息（失败时返回）        |        |
| data       | string  | 否   | -        | 响应数据 (ActualType: String) |        |

#### 响应示例

```
{
    "success": true,
    "errCode": "string",
    "errMessage": "string",
    "data": "string"
}
```

#### 错误码

无

### 删除预置位

<p>删除摄像头的指定预置位。</p>
<p>删除后该预置位编号将不可用，直到重新设置。</p>

维护人：TG Live

#### URL

- 本地开发环境: `POST` http://localhost:10050/api/camera/control/{cameraId}/preset/remove
- 开发环境: `POST` https://tg-live-game.pwtk.cc/api/camera/control/{cameraId}/preset/remove

描述：删除预置位

<p>删除摄像头的指定预置位。</p>
<p>删除后该预置位编号将不可用，直到重新设置。</p>

ContentType：`application/json`

#### Path 参数

| 名称     | 必填 | 描述      | 示例值        |
| -------- | ---- | --------- | ------------- |
| cameraId | 是   | 摄像头 ID | hikvision_ptz |

#### 请求参数

##### Body Parameter

| 名称        | 类型    | 必填 | 最大长度 | 描述       | 示例值 |
| ----------- | ------- | ---- | -------- | ---------- | ------ |
| presetIndex | Integer | 是   | -        | 预置位编号 | 1      |

#### 请求示例

```
{
    "presetIndex": 1
}
```

#### 响应参数

| 名称       | 类型    | 必填 | 最大长度 | 描述                          | 示例值 |
| ---------- | ------- | ---- | -------- | ----------------------------- | ------ |
| success    | Boolean | 否   | -        | 请求是否成功                  | true   |
| errCode    | String  | 否   | -        | 错误码（失败时返回）          |        |
| errMessage | String  | 否   | -        | 错误信息（失败时返回）        |        |
| data       | string  | 否   | -        | 响应数据 (ActualType: String) |        |

#### 响应示例

```
{
    "success": true,
    "errCode": "string",
    "errMessage": "string",
    "data": "string"
}
```

#### 错误码

无

### 回放记忆路线（前端用户接口）

<p>触发指定摄像头的记忆路线回放，摄像头将按录制顺序自动执行所有 PTZ 动作。</p>

维护人：TG Live

#### URL

- 本地开发环境: `POST` http://localhost:10050/api/camera/{cameraId}/patrol/play
- 开发环境: `POST` https://tg-live-game.pwtk.cc/api/camera/{cameraId}/patrol/play

描述：回放记忆路线（前端用户接口）

<p>触发指定摄像头的记忆路线回放，摄像头将按录制顺序自动执行所有 PTZ 动作。</p>

ContentType：`application/json`

#### Path 参数

| 名称     | 必填 | 描述      | 示例值  |
| -------- | ---- | --------- | ------- |
| cameraId | 是   | 摄像头 ID | cam_001 |

#### 请求参数

##### Body Parameter

| 名称        | 类型    | 必填 | 最大长度 | 描述                                                   | 示例值   |
| ----------- | ------- | ---- | -------- | ------------------------------------------------------ | -------- |
| tourId      | String  | 是   | -        | 轨迹 ID                                                | tour_001 |
| loopEnabled | Boolean | 否   | -        | 覆盖循环设置：是否循环执行（可选，不传则使用轨迹配置） | true     |
| loopCount   | Integer | 否   | -        | 覆盖循环设置：循环次数（可选，不传则使用轨迹配置）     | 3        |

#### 请求示例

```
{
    "tourId": "tour_001",
    "loopEnabled": true,
    "loopCount": 3
}
```

#### 响应参数

| 名称       | 类型    | 必填 | 最大长度 | 描述                          | 示例值 |
| ---------- | ------- | ---- | -------- | ----------------------------- | ------ |
| success    | Boolean | 否   | -        | 请求是否成功                  | true   |
| errCode    | String  | 否   | -        | 错误码（失败时返回）          |        |
| errMessage | String  | 否   | -        | 错误信息（失败时返回）        |        |
| data       | string  | 否   | -        | 响应数据 (ActualType: String) |        |

#### 响应示例

```
{
    "success": true,
    "errCode": "string",
    "errMessage": "string",
    "data": "string"
}
```

#### 错误码

无