# 文档

## 摄像头控制 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

- 本地开发环境: `GET` http://localhost:10050/api/camera/list

描述：获取摄像头列表

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

#### 请求参数

##### Query Parameter

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

#### 响应参数

| 名称 | 类型 | 必填 | 最大长度 | 描述 | 示例值 |
| --- | --- | --- | --- | --- | --- |
| code | Integer | 否 | - | 响应码 | 200 |
| message | String | 否 | - | 响应消息 | 操作成功 |
| data | array | 否 |  | 响应数据 (ActualType: List) |  |
| └ cameraId | String | 否 | - | 摄像头 ID | cam_001 |
| └ name | String | 否 | - | 摄像头名称 | 主摄像头 |
| └ machineId | String | 否 | - | 所属机器 ID | machine_001 |
| └ status | String | 否 | - | 摄像头状态: ONLINE, OFFLINE | ONLINE |
| └ capability | String | 否 | - | 摄像头能力: switch_only, ptz_enabled | ptz_enabled |
| └ ptzSupported | Boolean | 否 | - | 是否支持 PTZ | true |
| └ channels | List<ChannelDTO> | 否 |  | 通道列表 (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 |
| timestamp | Long | 否 | - | 时间戳 | 1703145600000 |
| traceId | String | 否 | - | 请求追踪 ID | trace-123456 |

#### 响应示例

```
{
    "code": 200,
    "message": "操作成功",
    "data": [
        {
            "cameraId": "cam_001",
            "name": "主摄像头",
            "machineId": "machine_001",
            "status": "ONLINE",
            "capability": "ptz_enabled",
            "ptzSupported": true,
            "channels": [
                {
                    "channelId": "ch_001",
                    "name": "主通道",
                    "rtspUrl": "rtsp://192.168.1.100:554/stream1",
                    "defaultView": true,
                    "status": "ONLINE",
                    "cameraId": "cam_001"
                }
            ]
        }
    ],
    "timestamp": 1703145600000,
    "traceId": "trace-123456"
}
```

#### 错误码

无

### 获取摄像头信息

维护人：TG Live

#### URL

- 本地开发环境: `GET` http://localhost:10050/api/camera/{cameraId}

描述：获取摄像头信息

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

#### Path 参数

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

#### 请求参数

#### 响应参数

| 名称 | 类型 | 必填 | 最大长度 | 描述 | 示例值 |
| --- | --- | --- | --- | --- | --- |
| code | Integer | 否 | - | 响应码 | 200 |
| message | String | 否 | - | 响应消息 | 操作成功 |
| data | object | 否 |  | 响应数据 (ActualType: CameraDTO) |  |
| └ cameraId | String | 否 | - | 摄像头 ID | cam_001 |
| └ name | String | 否 | - | 摄像头名称 | 主摄像头 |
| └ machineId | String | 否 | - | 所属机器 ID | machine_001 |
| └ status | String | 否 | - | 摄像头状态: ONLINE, OFFLINE | ONLINE |
| └ capability | String | 否 | - | 摄像头能力: switch_only, ptz_enabled | ptz_enabled |
| └ ptzSupported | Boolean | 否 | - | 是否支持 PTZ | true |
| └ channels | List<ChannelDTO> | 否 |  | 通道列表 (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 |
| timestamp | Long | 否 | - | 时间戳 | 1703145600000 |
| traceId | String | 否 | - | 请求追踪 ID | trace-123456 |

#### 响应示例

```
{
    "code": 200,
    "message": "操作成功",
    "data": {
        "cameraId": "cam_001",
        "name": "主摄像头",
        "machineId": "machine_001",
        "status": "ONLINE",
        "capability": "ptz_enabled",
        "ptzSupported": true,
        "channels": [
            {
                "channelId": "ch_001",
                "name": "主通道",
                "rtspUrl": "rtsp://192.168.1.100:554/stream1",
                "defaultView": true,
                "status": "ONLINE",
                "cameraId": "cam_001"
            }
        ]
    },
    "timestamp": 1703145600000,
    "traceId": "trace-123456"
}
```

#### 错误码

无

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

维护人：TG Live

#### URL

- 本地开发环境: `POST` http://localhost:10050/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"
}
```

#### 响应参数

| 名称          | 类型    | 必填 | 最大长度 | 描述                              | 示例值                           |
| ------------- | ------- | ---- | -------- | --------------------------------- | -------------------------------- |
| code          | Integer | 否   | -        | 响应码                            | 200                              |
| message       | 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                          |
| timestamp     | Long    | 否   | -        | 时间戳                            | 1703145600000                    |
| traceId       | String  | 否   | -        | 请求追踪 ID                       | trace-123456                     |

#### 响应示例

```
{
    "code": 200,
    "message": "操作成功",
    "data": {
        "channelId": "ch_001",
        "name": "主通道",
        "rtspUrl": "rtsp://192.168.1.100:554/stream1",
        "defaultView": true,
        "status": "ONLINE",
        "cameraId": "cam_001"
    },
    "timestamp": 1703145600000,
    "traceId": "trace-123456"
}
```

#### 错误码

无

### 获取当前活动通道

维护人：TG Live

#### URL

- 本地开发环境: `GET` http://localhost:10050/api/camera/current

描述：获取当前活动通道

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

#### 请求参数

##### Query Parameter

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

#### 响应参数

| 名称          | 类型    | 必填 | 最大长度 | 描述                              | 示例值                           |
| ------------- | ------- | ---- | -------- | --------------------------------- | -------------------------------- |
| code          | Integer | 否   | -        | 响应码                            | 200                              |
| message       | 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                          |
| timestamp     | Long    | 否   | -        | 时间戳                            | 1703145600000                    |
| traceId       | String  | 否   | -        | 请求追踪 ID                       | trace-123456                     |

#### 响应示例

```
{
    "code": 200,
    "message": "操作成功",
    "data": {
        "channelId": "ch_001",
        "name": "主通道",
        "rtspUrl": "rtsp://192.168.1.100:554/stream1",
        "defaultView": true,
        "status": "ONLINE",
        "cameraId": "cam_001"
    },
    "timestamp": 1703145600000,
    "traceId": "trace-123456"
}
```

#### 错误码

无

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

维护人：TG Live

#### URL

- 本地开发环境: `POST` http://localhost:10050/api/camera/{cameraId}/ptz/start

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

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

#### Path 参数

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

#### 请求参数

##### Query Parameter

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

#### 响应参数

| 名称      | 类型    | 必填 | 最大长度 | 描述                        | 示例值        |
| --------- | ------- | ---- | -------- | --------------------------- | ------------- |
| code      | Integer | 否   | -        | 响应码                      | 200           |
| message   | String  | 否   | -        | 响应消息                    | 操作成功      |
| data      | object  | 否   | -        | 响应数据 (ActualType: Void) |               |
| timestamp | Long    | 否   | -        | 时间戳                      | 1703145600000 |
| traceId   | String  | 否   | -        | 请求追踪 ID                 | trace-123456  |

#### 响应示例

```
{
    "code": 200,
    "message": "操作成功",
    "data": {},
    "timestamp": 1703145600000,
    "traceId": "trace-123456"
}
```

#### 错误码

无

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

维护人：TG Live

#### URL

- 本地开发环境: `POST` http://localhost:10050/api/camera/{cameraId}/ptz/stop

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

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

#### Path 参数

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

#### 请求参数

#### 响应参数

| 名称      | 类型    | 必填 | 最大长度 | 描述                        | 示例值        |
| --------- | ------- | ---- | -------- | --------------------------- | ------------- |
| code      | Integer | 否   | -        | 响应码                      | 200           |
| message   | String  | 否   | -        | 响应消息                    | 操作成功      |
| data      | object  | 否   | -        | 响应数据 (ActualType: Void) |               |
| timestamp | Long    | 否   | -        | 时间戳                      | 1703145600000 |
| traceId   | String  | 否   | -        | 请求追踪 ID                 | trace-123456  |

#### 响应示例

```
{
    "code": 200,
    "message": "操作成功",
    "data": {},
    "timestamp": 1703145600000,
    "traceId": "trace-123456"
}
```

#### 错误码

无

## 摄像头管理

### 获取摄像头列表

维护人：TG Live

#### URL

- 本地开发环境: `GET` http://localhost:10050/api/admin/cameras/list

描述：获取摄像头列表

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

#### 请求参数

##### Query Parameter

| 名称      | 类型   | 必填 | 最大长度 | 描述                            | 示例值      |
| --------- | ------ | ---- | -------- | ------------------------------- | ----------- |
| machineId | string | 否   | -        | 机器 ID（可选），不传则返回全部 | machine_001 |

#### 响应参数

| 名称 | 类型 | 必填 | 最大长度 | 描述 | 示例值 |
| --- | --- | --- | --- | --- | --- |
| code | Integer | 否 | - | 响应码 | 200 |
| message | String | 否 | - | 响应消息 | 操作成功 |
| data | array | 否 |  | 响应数据 (ActualType: List) |  |
| └ id | Long | 否 | - | 主键 ID | 1 |
| └ cameraId | String | 否 | - | 摄像头 ID | cam_001 |
| └ name | String | 否 | - | 名称 | 主摄像头 |
| └ ip | String | 否 | - | IP 地址 | 192.168.1.100 |
| └ port | Integer | 否 | - | 端口 | 80 |
| └ username | String | 否 | - | 用户名 | admin |
| └ brand | String | 否 | - | 品牌 | hikvision |
| └ capability | String | 否 | - | 能力: switch_only, ptz_enabled | ptz_enabled |
| └ status | String | 否 | - | 状态: ONLINE, OFFLINE | ONLINE |
| └ machineId | String | 否 | - | 所属机器 ID | machine_001 |
| └ machineName | String | 否 | - | 所属机器名称 | 1 号机 |
| └ enabled | Boolean | 否 | - | 是否启用 | true |
| └ channels | List<ChannelInfoDTO> | 否 |  | 通道列表 (ActualType: ChannelInfoDTO) |  |
| └ id | Long | 否 | - | 主键 ID | 1 |
| └ 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 |
| └ createdAt | LocalDateTime | 否 | - | 创建时间 | 2026-01-07T10:00:00 |
| └ updatedAt | LocalDateTime | 否 | - | 更新时间 | 2026-01-07T10:00:00 |
| timestamp | Long | 否 | - | 时间戳 | 1703145600000 |
| traceId | String | 否 | - | 请求追踪 ID | trace-123456 |

#### 响应示例

```
{
    "code": 200,
    "message": "操作成功",
    "data": [
        {
            "id": 1,
            "cameraId": "cam_001",
            "name": "主摄像头",
            "ip": "192.168.1.100",
            "port": 80,
            "username": "admin",
            "brand": "hikvision",
            "capability": "ptz_enabled",
            "status": "ONLINE",
            "machineId": "machine_001",
            "machineName": "1号机",
            "enabled": true,
            "channels": [
                {
                    "id": 1,
                    "channelId": "ch_001",
                    "name": "主通道",
                    "rtspUrl": "rtsp://192.168.1.100:554/stream1",
                    "defaultView": true,
                    "status": "ONLINE"
                }
            ],
            "createdAt": "2026-01-07T10:00:00",
            "updatedAt": "2026-01-07T10:00:00"
        }
    ],
    "timestamp": 1703145600000,
    "traceId": "trace-123456"
}
```

#### 错误码

无

### 获取摄像头详情

维护人：TG Live

#### URL

- 本地开发环境: `GET` http://localhost:10050/api/admin/cameras/detail

描述：获取摄像头详情

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

#### 请求参数

##### Query Parameter

| 名称 | 类型  | 必填 | 最大长度 | 描述          | 示例值 |
| ---- | ----- | ---- | -------- | ------------- | ------ |
| id   | int64 | 是   | -        | 摄像头主键 ID | 1      |

#### 响应参数

| 名称 | 类型 | 必填 | 最大长度 | 描述 | 示例值 |
| --- | --- | --- | --- | --- | --- |
| code | Integer | 否 | - | 响应码 | 200 |
| message | String | 否 | - | 响应消息 | 操作成功 |
| data | object | 否 |  | 响应数据 (ActualType: CameraInfoDTO) |  |
| └ id | Long | 否 | - | 主键 ID | 1 |
| └ cameraId | String | 否 | - | 摄像头 ID | cam_001 |
| └ name | String | 否 | - | 名称 | 主摄像头 |
| └ ip | String | 否 | - | IP 地址 | 192.168.1.100 |
| └ port | Integer | 否 | - | 端口 | 80 |
| └ username | String | 否 | - | 用户名 | admin |
| └ brand | String | 否 | - | 品牌 | hikvision |
| └ capability | String | 否 | - | 能力: switch_only, ptz_enabled | ptz_enabled |
| └ status | String | 否 | - | 状态: ONLINE, OFFLINE | ONLINE |
| └ machineId | String | 否 | - | 所属机器 ID | machine_001 |
| └ machineName | String | 否 | - | 所属机器名称 | 1 号机 |
| └ enabled | Boolean | 否 | - | 是否启用 | true |
| └ channels | List<ChannelInfoDTO> | 否 |  | 通道列表 (ActualType: ChannelInfoDTO) |  |
| └ id | Long | 否 | - | 主键 ID | 1 |
| └ 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 |
| └ createdAt | LocalDateTime | 否 | - | 创建时间 | 2026-01-07T10:00:00 |
| └ updatedAt | LocalDateTime | 否 | - | 更新时间 | 2026-01-07T10:00:00 |
| timestamp | Long | 否 | - | 时间戳 | 1703145600000 |
| traceId | String | 否 | - | 请求追踪 ID | trace-123456 |

#### 响应示例

```
{
    "code": 200,
    "message": "操作成功",
    "data": {
        "id": 1,
        "cameraId": "cam_001",
        "name": "主摄像头",
        "ip": "192.168.1.100",
        "port": 80,
        "username": "admin",
        "brand": "hikvision",
        "capability": "ptz_enabled",
        "status": "ONLINE",
        "machineId": "machine_001",
        "machineName": "1号机",
        "enabled": true,
        "channels": [
            {
                "id": 1,
                "channelId": "ch_001",
                "name": "主通道",
                "rtspUrl": "rtsp://192.168.1.100:554/stream1",
                "defaultView": true,
                "status": "ONLINE"
            }
        ],
        "createdAt": "2026-01-07T10:00:00",
        "updatedAt": "2026-01-07T10:00:00"
    },
    "timestamp": 1703145600000,
    "traceId": "trace-123456"
}
```

#### 错误码

无

### 添加摄像头

维护人：TG Live

#### URL

- 本地开发环境: `POST` http://localhost:10050/api/admin/cameras/add

描述：添加摄像头

ContentType：`application/json`

#### 请求参数

##### Body Parameter

| 名称 | 类型 | 必填 | 最大长度 | 描述 | 示例值 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| cameraId | String | 是 | 50 | 摄像头 ID（唯一标识）<br>Validate[max: 50; ] | cam_001 |
| name | String | 是 | 100 | 名称<br>Validate[max: 100; ] | 主摄像头 |
| ip | String | 是 | - | IP 地址<br>Validate[regexp: ^((25[0-5] | 2[0-4]\\d | [01]?\\d\\d?)\\.){3}(25[0-5] | 2[0-4]\\d | [01]?\\d\\d?)$; ] | 192.168.1.100 |
| port | Integer | 否 | - | 端口 | 80 |
| username | String | 否 | 50 | 用户名<br>Validate[max: 50; ] | admin |
| password | String | 否 | 100 | 密码<br>Validate[max: 100; ] | password123 |
| brand | String | 否 | 30 | 品牌<br>Validate[max: 30; ] | hikvision |
| capability | String | 否 | - | 能力: switch_only, ptz_enabled<br>Validate[regexp: ^(switch_only | ptz_enabled)$; ] | ptz_enabled |
| machineId | String | 否 | - | 所属机器 ID | machine_001 |
| channels | List<CameraAddRequest$ChannelAddRequest> | 否 |  | 通道列表 (ActualType: ChannelAddRequest) |  |
| └ channelId | String | 是 | - | 通道 ID | ch_001 |
| └ name | String | 是 | - | 通道名称 | 主通道 |
| └ rtspUrl | String | 否 | - | RTSP 地址 | rtsp://192.168.1.100:554/stream1 |
| └ defaultView | Boolean | 否 | - | 是否默认视角 | true |

#### 请求示例

```
{
    "cameraId": "cam_001",
    "name": "主摄像头",
    "ip": "192.168.1.100",
    "port": 80,
    "username": "admin",
    "password": "password123",
    "brand": "hikvision",
    "capability": "ptz_enabled",
    "machineId": "machine_001",
    "channels": [
        {
            "channelId": "ch_001",
            "name": "主通道",
            "rtspUrl": "rtsp://192.168.1.100:554/stream1",
            "defaultView": true
        }
    ]
}
```

#### 响应参数

| 名称 | 类型 | 必填 | 最大长度 | 描述 | 示例值 |
| --- | --- | --- | --- | --- | --- |
| code | Integer | 否 | - | 响应码 | 200 |
| message | String | 否 | - | 响应消息 | 操作成功 |
| data | object | 否 |  | 响应数据 (ActualType: CameraInfoDTO) |  |
| └ id | Long | 否 | - | 主键 ID | 1 |
| └ cameraId | String | 否 | - | 摄像头 ID | cam_001 |
| └ name | String | 否 | - | 名称 | 主摄像头 |
| └ ip | String | 否 | - | IP 地址 | 192.168.1.100 |
| └ port | Integer | 否 | - | 端口 | 80 |
| └ username | String | 否 | - | 用户名 | admin |
| └ brand | String | 否 | - | 品牌 | hikvision |
| └ capability | String | 否 | - | 能力: switch_only, ptz_enabled | ptz_enabled |
| └ status | String | 否 | - | 状态: ONLINE, OFFLINE | ONLINE |
| └ machineId | String | 否 | - | 所属机器 ID | machine_001 |
| └ machineName | String | 否 | - | 所属机器名称 | 1 号机 |
| └ enabled | Boolean | 否 | - | 是否启用 | true |
| └ channels | List<ChannelInfoDTO> | 否 |  | 通道列表 (ActualType: ChannelInfoDTO) |  |
| └ id | Long | 否 | - | 主键 ID | 1 |
| └ 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 |
| └ createdAt | LocalDateTime | 否 | - | 创建时间 | 2026-01-07T10:00:00 |
| └ updatedAt | LocalDateTime | 否 | - | 更新时间 | 2026-01-07T10:00:00 |
| timestamp | Long | 否 | - | 时间戳 | 1703145600000 |
| traceId | String | 否 | - | 请求追踪 ID | trace-123456 |

#### 响应示例

```
{
    "code": 200,
    "message": "操作成功",
    "data": {
        "id": 1,
        "cameraId": "cam_001",
        "name": "主摄像头",
        "ip": "192.168.1.100",
        "port": 80,
        "username": "admin",
        "brand": "hikvision",
        "capability": "ptz_enabled",
        "status": "ONLINE",
        "machineId": "machine_001",
        "machineName": "1号机",
        "enabled": true,
        "channels": [
            {
                "id": 1,
                "channelId": "ch_001",
                "name": "主通道",
                "rtspUrl": "rtsp://192.168.1.100:554/stream1",
                "defaultView": true,
                "status": "ONLINE"
            }
        ],
        "createdAt": "2026-01-07T10:00:00",
        "updatedAt": "2026-01-07T10:00:00"
    },
    "timestamp": 1703145600000,
    "traceId": "trace-123456"
}
```

#### 错误码

无

### 更新摄像头

维护人：TG Live

#### URL

- 本地开发环境: `POST` http://localhost:10050/api/admin/cameras/update

描述：更新摄像头

ContentType：`application/json`

#### 请求参数

##### Body Parameter

| 名称 | 类型 | 必填 | 最大长度 | 描述 | 示例值 |
| --- | --- | --- | --- | --- | --- |
| id | Long | 否 | - | 摄像头数据库 ID | 1 |
| name | String | 否 | - | 名称 | 主摄像头 |
| ip | String | 否 | - | IP 地址 | 192.168.1.100 |
| port | Integer | 否 | - | 端口 | 80 |
| username | String | 否 | - | 用户名 | admin |
| password | String | 否 | - | 密码（不传或为空则不修改） | password123 |
| brand | String | 否 | - | 品牌 | hikvision |
| capability | String | 否 | - | 能力: switch_only, ptz_enabled | ptz_enabled |
| machineId | String | 否 | - | 所属机器 ID | machine_001 |
| enabled | Boolean | 否 | - | 启用状态 | true |
| channels | List<CameraUpdateRequest$ChannelUpdateRequest> | 否 |  | 通道列表 (ActualType: ChannelUpdateRequest) |  |
| └ id | Long | 否 | - | 通道数据库 ID | 1 |
| └ channelId | String | 否 | - | 通道 ID | ch_001 |
| └ name | String | 否 | - | 通道名称 | 主通道 |
| └ rtspUrl | String | 否 | - | RTSP 地址 | rtsp://192.168.1.100:554/stream1 |
| └ defaultView | Boolean | 否 | - | 是否默认视角 | true |

#### 请求示例

```
{
    "id": 1,
    "name": "主摄像头",
    "ip": "192.168.1.100",
    "port": 80,
    "username": "admin",
    "password": "password123",
    "brand": "hikvision",
    "capability": "ptz_enabled",
    "machineId": "machine_001",
    "enabled": true,
    "channels": [
        {
            "id": 1,
            "channelId": "ch_001",
            "name": "主通道",
            "rtspUrl": "rtsp://192.168.1.100:554/stream1",
            "defaultView": true
        }
    ]
}
```

#### 响应参数

| 名称 | 类型 | 必填 | 最大长度 | 描述 | 示例值 |
| --- | --- | --- | --- | --- | --- |
| code | Integer | 否 | - | 响应码 | 200 |
| message | String | 否 | - | 响应消息 | 操作成功 |
| data | object | 否 |  | 响应数据 (ActualType: CameraInfoDTO) |  |
| └ id | Long | 否 | - | 主键 ID | 1 |
| └ cameraId | String | 否 | - | 摄像头 ID | cam_001 |
| └ name | String | 否 | - | 名称 | 主摄像头 |
| └ ip | String | 否 | - | IP 地址 | 192.168.1.100 |
| └ port | Integer | 否 | - | 端口 | 80 |
| └ username | String | 否 | - | 用户名 | admin |
| └ brand | String | 否 | - | 品牌 | hikvision |
| └ capability | String | 否 | - | 能力: switch_only, ptz_enabled | ptz_enabled |
| └ status | String | 否 | - | 状态: ONLINE, OFFLINE | ONLINE |
| └ machineId | String | 否 | - | 所属机器 ID | machine_001 |
| └ machineName | String | 否 | - | 所属机器名称 | 1 号机 |
| └ enabled | Boolean | 否 | - | 是否启用 | true |
| └ channels | List<ChannelInfoDTO> | 否 |  | 通道列表 (ActualType: ChannelInfoDTO) |  |
| └ id | Long | 否 | - | 主键 ID | 1 |
| └ 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 |
| └ createdAt | LocalDateTime | 否 | - | 创建时间 | 2026-01-07T10:00:00 |
| └ updatedAt | LocalDateTime | 否 | - | 更新时间 | 2026-01-07T10:00:00 |
| timestamp | Long | 否 | - | 时间戳 | 1703145600000 |
| traceId | String | 否 | - | 请求追踪 ID | trace-123456 |

#### 响应示例

```
{
    "code": 200,
    "message": "操作成功",
    "data": {
        "id": 1,
        "cameraId": "cam_001",
        "name": "主摄像头",
        "ip": "192.168.1.100",
        "port": 80,
        "username": "admin",
        "brand": "hikvision",
        "capability": "ptz_enabled",
        "status": "ONLINE",
        "machineId": "machine_001",
        "machineName": "1号机",
        "enabled": true,
        "channels": [
            {
                "id": 1,
                "channelId": "ch_001",
                "name": "主通道",
                "rtspUrl": "rtsp://192.168.1.100:554/stream1",
                "defaultView": true,
                "status": "ONLINE"
            }
        ],
        "createdAt": "2026-01-07T10:00:00",
        "updatedAt": "2026-01-07T10:00:00"
    },
    "timestamp": 1703145600000,
    "traceId": "trace-123456"
}
```

#### 错误码

无

### 删除摄像头

维护人：TG Live

#### URL

- 本地开发环境: `POST` http://localhost:10050/api/admin/cameras/delete

描述：删除摄像头

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

#### 请求参数

##### Query Parameter

| 名称 | 类型  | 必填 | 最大长度 | 描述          | 示例值 |
| ---- | ----- | ---- | -------- | ------------- | ------ |
| id   | int64 | 是   | -        | 摄像头主键 ID | 1      |

#### 响应参数

| 名称      | 类型    | 必填 | 最大长度 | 描述                        | 示例值        |
| --------- | ------- | ---- | -------- | --------------------------- | ------------- |
| code      | Integer | 否   | -        | 响应码                      | 200           |
| message   | String  | 否   | -        | 响应消息                    | 操作成功      |
| data      | object  | 否   | -        | 响应数据 (ActualType: Void) |               |
| timestamp | Long    | 否   | -        | 时间戳                      | 1703145600000 |
| traceId   | String  | 否   | -        | 请求追踪 ID                 | trace-123456  |

#### 响应示例

```
{
    "code": 200,
    "message": "操作成功",
    "data": {},
    "timestamp": 1703145600000,
    "traceId": "trace-123456"
}
```

#### 错误码

无

### 检测摄像头连通性

维护人：TG Live

#### URL

- 本地开发环境: `POST` http://localhost:10050/api/admin/cameras/check

描述：检测摄像头连通性

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

#### 请求参数

##### Query Parameter

| 名称 | 类型  | 必填 | 最大长度 | 描述          | 示例值 |
| ---- | ----- | ---- | -------- | ------------- | ------ |
| id   | int64 | 是   | -        | 摄像头主键 ID | 1      |

#### 响应参数

| 名称      | 类型    | 必填 | 最大长度 | 描述                           | 示例值        |
| --------- | ------- | ---- | -------- | ------------------------------ | ------------- |
| code      | Integer | 否   | -        | 响应码                         | 200           |
| message   | String  | 否   | -        | 响应消息                       | 操作成功      |
| data      | boolean | 否   | -        | 响应数据 (ActualType: Boolean) |               |
| timestamp | Long    | 否   | -        | 时间戳                         | 1703145600000 |
| traceId   | String  | 否   | -        | 请求追踪 ID                    | trace-123456  |

#### 响应示例

```
{
    "code": 200,
    "message": "操作成功",
    "data": false,
    "timestamp": 1703145600000,
    "traceId": "trace-123456"
}
```

#### 错误码

无

## 机器管理

### 获取机器列表

维护人：TG Live

#### URL

- 本地开发环境: `GET` http://localhost:10050/api/admin/machines/list

描述：获取机器列表

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

#### 请求参数

#### 响应参数

| 名称          | 类型          | 必填 | 最大长度 | 描述                        | 示例值              |
| ------------- | ------------- | ---- | -------- | --------------------------- | ------------------- |
| code          | Integer       | 否   | -        | 响应码                      | 200                 |
| message       | String        | 否   | -        | 响应消息                    | 操作成功            |
| data          | array         | 否   |          | 响应数据 (ActualType: List) |                     |
| └ id          | Long          | 否   | -        | 主键 ID                     | 1                   |
| └ machineId   | String        | 否   | -        | 机器 ID                     | machine_001         |
| └ name        | String        | 否   | -        | 名称                        | 1 号机              |
| └ location    | String        | 否   | -        | 位置                        | A 区 1 楼           |
| └ description | String        | 否   | -        | 描述                        | 主力机器            |
| └ enabled     | Boolean       | 否   | -        | 是否启用                    | true                |
| └ cameraCount | Integer       | 否   | -        | 摄像头数量                  | 3                   |
| └ createdAt   | LocalDateTime | 否   | -        | 创建时间                    | 2026-01-07T10:00:00 |
| └ updatedAt   | LocalDateTime | 否   | -        | 更新时间                    | 2026-01-07T10:00:00 |
| timestamp     | Long          | 否   | -        | 时间戳                      | 1703145600000       |
| traceId       | String        | 否   | -        | 请求追踪 ID                 | trace-123456        |

#### 响应示例

```
{
    "code": 200,
    "message": "操作成功",
    "data": [
        {
            "id": 1,
            "machineId": "machine_001",
            "name": "1号机",
            "location": "A区1楼",
            "description": "主力机器",
            "enabled": true,
            "cameraCount": 3,
            "createdAt": "2026-01-07T10:00:00",
            "updatedAt": "2026-01-07T10:00:00"
        }
    ],
    "timestamp": 1703145600000,
    "traceId": "trace-123456"
}
```

#### 错误码

无

### 获取机器详情

维护人：TG Live

#### URL

- 本地开发环境: `GET` http://localhost:10050/api/admin/machines/detail

描述：获取机器详情

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

#### 请求参数

##### Query Parameter

| 名称 | 类型  | 必填 | 最大长度 | 描述        | 示例值 |
| ---- | ----- | ---- | -------- | ----------- | ------ |
| id   | int64 | 是   | -        | 机器主键 ID | 1      |

#### 响应参数

| 名称          | 类型          | 必填 | 最大长度 | 描述                              | 示例值              |
| ------------- | ------------- | ---- | -------- | --------------------------------- | ------------------- |
| code          | Integer       | 否   | -        | 响应码                            | 200                 |
| message       | String        | 否   | -        | 响应消息                          | 操作成功            |
| data          | object        | 否   |          | 响应数据 (ActualType: MachineDTO) |                     |
| └ id          | Long          | 否   | -        | 主键 ID                           | 1                   |
| └ machineId   | String        | 否   | -        | 机器 ID                           | machine_001         |
| └ name        | String        | 否   | -        | 名称                              | 1 号机              |
| └ location    | String        | 否   | -        | 位置                              | A 区 1 楼           |
| └ description | String        | 否   | -        | 描述                              | 主力机器            |
| └ enabled     | Boolean       | 否   | -        | 是否启用                          | true                |
| └ cameraCount | Integer       | 否   | -        | 摄像头数量                        | 3                   |
| └ createdAt   | LocalDateTime | 否   | -        | 创建时间                          | 2026-01-07T10:00:00 |
| └ updatedAt   | LocalDateTime | 否   | -        | 更新时间                          | 2026-01-07T10:00:00 |
| timestamp     | Long          | 否   | -        | 时间戳                            | 1703145600000       |
| traceId       | String        | 否   | -        | 请求追踪 ID                       | trace-123456        |

#### 响应示例

```
{
    "code": 200,
    "message": "操作成功",
    "data": {
        "id": 1,
        "machineId": "machine_001",
        "name": "1号机",
        "location": "A区1楼",
        "description": "主力机器",
        "enabled": true,
        "cameraCount": 3,
        "createdAt": "2026-01-07T10:00:00",
        "updatedAt": "2026-01-07T10:00:00"
    },
    "timestamp": 1703145600000,
    "traceId": "trace-123456"
}
```

#### 错误码

无

### 添加机器

维护人：TG Live

#### URL

- 本地开发环境: `POST` http://localhost:10050/api/admin/machines/add

描述：添加机器

ContentType：`application/json`

#### 请求参数

##### Body Parameter

| 名称        | 类型   | 必填 | 最大长度 | 描述                                       | 示例值      |
| ----------- | ------ | ---- | -------- | ------------------------------------------ | ----------- |
| machineId   | String | 是   | 50       | 机器 ID（唯一标识）<br>Validate[max: 50; ] | machine_001 |
| name        | String | 是   | 100      | 名称<br>Validate[max: 100; ]               | 1 号机      |
| location    | String | 否   | 200      | 位置<br>Validate[max: 200; ]               | A 区 1 楼   |
| description | String | 否   | 500      | 描述<br>Validate[max: 500; ]               | 主力机器    |

#### 请求示例

```
{
    "machineId": "machine_001",
    "name": "1号机",
    "location": "A区1楼",
    "description": "主力机器"
}
```

#### 响应参数

| 名称          | 类型          | 必填 | 最大长度 | 描述                              | 示例值              |
| ------------- | ------------- | ---- | -------- | --------------------------------- | ------------------- |
| code          | Integer       | 否   | -        | 响应码                            | 200                 |
| message       | String        | 否   | -        | 响应消息                          | 操作成功            |
| data          | object        | 否   |          | 响应数据 (ActualType: MachineDTO) |                     |
| └ id          | Long          | 否   | -        | 主键 ID                           | 1                   |
| └ machineId   | String        | 否   | -        | 机器 ID                           | machine_001         |
| └ name        | String        | 否   | -        | 名称                              | 1 号机              |
| └ location    | String        | 否   | -        | 位置                              | A 区 1 楼           |
| └ description | String        | 否   | -        | 描述                              | 主力机器            |
| └ enabled     | Boolean       | 否   | -        | 是否启用                          | true                |
| └ cameraCount | Integer       | 否   | -        | 摄像头数量                        | 3                   |
| └ createdAt   | LocalDateTime | 否   | -        | 创建时间                          | 2026-01-07T10:00:00 |
| └ updatedAt   | LocalDateTime | 否   | -        | 更新时间                          | 2026-01-07T10:00:00 |
| timestamp     | Long          | 否   | -        | 时间戳                            | 1703145600000       |
| traceId       | String        | 否   | -        | 请求追踪 ID                       | trace-123456        |

#### 响应示例

```
{
    "code": 200,
    "message": "操作成功",
    "data": {
        "id": 1,
        "machineId": "machine_001",
        "name": "1号机",
        "location": "A区1楼",
        "description": "主力机器",
        "enabled": true,
        "cameraCount": 3,
        "createdAt": "2026-01-07T10:00:00",
        "updatedAt": "2026-01-07T10:00:00"
    },
    "timestamp": 1703145600000,
    "traceId": "trace-123456"
}
```

#### 错误码

无

### 更新机器

维护人：TG Live

#### URL

- 本地开发环境: `POST` http://localhost:10050/api/admin/machines/update

描述：更新机器

ContentType：`application/json`

#### 请求参数

##### Body Parameter

| 名称        | 类型    | 必填 | 最大长度 | 描述          | 示例值    |
| ----------- | ------- | ---- | -------- | ------------- | --------- |
| id          | Long    | 否   | -        | 机器数据库 ID | 1         |
| name        | String  | 否   | -        | 名称          | 1 号机    |
| location    | String  | 否   | -        | 位置          | A 区 1 楼 |
| description | String  | 否   | -        | 描述          | 主力机器  |
| enabled     | Boolean | 否   | -        | 启用状态      | true      |

#### 请求示例

```
{
    "id": 1,
    "name": "1号机",
    "location": "A区1楼",
    "description": "主力机器",
    "enabled": true
}
```

#### 响应参数

| 名称          | 类型          | 必填 | 最大长度 | 描述                              | 示例值              |
| ------------- | ------------- | ---- | -------- | --------------------------------- | ------------------- |
| code          | Integer       | 否   | -        | 响应码                            | 200                 |
| message       | String        | 否   | -        | 响应消息                          | 操作成功            |
| data          | object        | 否   |          | 响应数据 (ActualType: MachineDTO) |                     |
| └ id          | Long          | 否   | -        | 主键 ID                           | 1                   |
| └ machineId   | String        | 否   | -        | 机器 ID                           | machine_001         |
| └ name        | String        | 否   | -        | 名称                              | 1 号机              |
| └ location    | String        | 否   | -        | 位置                              | A 区 1 楼           |
| └ description | String        | 否   | -        | 描述                              | 主力机器            |
| └ enabled     | Boolean       | 否   | -        | 是否启用                          | true                |
| └ cameraCount | Integer       | 否   | -        | 摄像头数量                        | 3                   |
| └ createdAt   | LocalDateTime | 否   | -        | 创建时间                          | 2026-01-07T10:00:00 |
| └ updatedAt   | LocalDateTime | 否   | -        | 更新时间                          | 2026-01-07T10:00:00 |
| timestamp     | Long          | 否   | -        | 时间戳                            | 1703145600000       |
| traceId       | String        | 否   | -        | 请求追踪 ID                       | trace-123456        |

#### 响应示例

```
{
    "code": 200,
    "message": "操作成功",
    "data": {
        "id": 1,
        "machineId": "machine_001",
        "name": "1号机",
        "location": "A区1楼",
        "description": "主力机器",
        "enabled": true,
        "cameraCount": 3,
        "createdAt": "2026-01-07T10:00:00",
        "updatedAt": "2026-01-07T10:00:00"
    },
    "timestamp": 1703145600000,
    "traceId": "trace-123456"
}
```

#### 错误码

无

### 删除机器

维护人：TG Live

#### URL

- 本地开发环境: `POST` http://localhost:10050/api/admin/machines/delete

描述：删除机器

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

#### 请求参数

##### Query Parameter

| 名称 | 类型  | 必填 | 最大长度 | 描述        | 示例值 |
| ---- | ----- | ---- | -------- | ----------- | ------ |
| id   | int64 | 是   | -        | 机器主键 ID | 1      |

#### 响应参数

| 名称      | 类型    | 必填 | 最大长度 | 描述                        | 示例值        |
| --------- | ------- | ---- | -------- | --------------------------- | ------------- |
| code      | Integer | 否   | -        | 响应码                      | 200           |
| message   | String  | 否   | -        | 响应消息                    | 操作成功      |
| data      | object  | 否   | -        | 响应数据 (ActualType: Void) |               |
| timestamp | Long    | 否   | -        | 时间戳                      | 1703145600000 |
| traceId   | String  | 否   | -        | 请求追踪 ID                 | trace-123456  |

#### 响应示例

```
{
    "code": 200,
    "message": "操作成功",
    "data": {},
    "timestamp": 1703145600000,
    "traceId": "trace-123456"
}
```

#### 错误码

无

## 管理员认证

### 登录

维护人：TG Live

#### URL

- 本地开发环境: `POST` http://localhost:10050/api/admin/auth/login

描述：登录

ContentType：`application/json`

#### 请求参数

##### Body Parameter

| 名称     | 类型   | 必填 | 最大长度 | 描述                          | 示例值 |
| -------- | ------ | ---- | -------- | ----------------------------- | ------ |
| username | String | 是   | 50       | 用户名<br>Validate[max: 50; ] | admin  |
| password | String | 是   | 100      | 密码<br>Validate[max: 100; ]  | 123456 |

#### 请求示例

```
{
    "username": "admin",
    "password": "123456"
}
```

#### 响应参数

| 名称 | 类型 | 必填 | 最大长度 | 描述 | 示例值 |
| --- | --- | --- | --- | --- | --- |
| code | Integer | 否 | - | 响应码 | 200 |
| message | String | 否 | - | 响应消息 | 操作成功 |
| data | object | 否 |  | 响应数据 (ActualType: LoginResponse) |  |
| └ token | String | 否 | - | JWT Token | eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiJ9.xxx |
| └ tokenType | String | 否 | - | Token 类型 | Bearer |
| └ expiresIn | Long | 否 | - | 过期时间（秒） | 86400 |
| └ admin | AdminInfoDTO | 否 |  | 用户信息 |  |
| └ id | Long | 否 | - | 用户 ID | 1 |
| └ username | String | 否 | - | 用户名 | admin |
| └ nickname | String | 否 | - | 昵称 | 管理员 |
| └ role | String | 否 | - | 角色 | ADMIN |
| └ lastLoginAt | LocalDateTime | 否 | - | 最后登录时间 | 2026-01-07T10:00:00 |
| timestamp | Long | 否 | - | 时间戳 | 1703145600000 |
| traceId | String | 否 | - | 请求追踪 ID | trace-123456 |

#### 响应示例

```
{
    "code": 200,
    "message": "操作成功",
    "data": {
        "token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiJ9.xxx",
        "tokenType": "Bearer",
        "expiresIn": 86400,
        "admin": {
            "id": 1,
            "username": "admin",
            "nickname": "管理员",
            "role": "ADMIN",
            "lastLoginAt": "2026-01-07T10:00:00"
        }
    },
    "timestamp": 1703145600000,
    "traceId": "trace-123456"
}
```

#### 错误码

无

### 登出

维护人：TG Live

#### URL

- 本地开发环境: `POST` http://localhost:10050/api/admin/auth/logout

描述：登出

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

#### 请求参数

#### 响应参数

| 名称      | 类型    | 必填 | 最大长度 | 描述                        | 示例值        |
| --------- | ------- | ---- | -------- | --------------------------- | ------------- |
| code      | Integer | 否   | -        | 响应码                      | 200           |
| message   | String  | 否   | -        | 响应消息                    | 操作成功      |
| data      | object  | 否   | -        | 响应数据 (ActualType: Void) |               |
| timestamp | Long    | 否   | -        | 时间戳                      | 1703145600000 |
| traceId   | String  | 否   | -        | 请求追踪 ID                 | trace-123456  |

#### 响应示例

```
{
    "code": 200,
    "message": "操作成功",
    "data": {},
    "timestamp": 1703145600000,
    "traceId": "trace-123456"
}
```

#### 错误码

无

### 获取当前用户信息

维护人：TG Live

#### URL

- 本地开发环境: `GET` http://localhost:10050/api/admin/auth/info

描述：获取当前用户信息

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

#### 请求参数

#### 响应参数

| 名称          | 类型          | 必填 | 最大长度 | 描述                                | 示例值              |
| ------------- | ------------- | ---- | -------- | ----------------------------------- | ------------------- |
| code          | Integer       | 否   | -        | 响应码                              | 200                 |
| message       | String        | 否   | -        | 响应消息                            | 操作成功            |
| data          | object        | 否   |          | 响应数据 (ActualType: AdminInfoDTO) |                     |
| └ id          | Long          | 否   | -        | 用户 ID                             | 1                   |
| └ username    | String        | 否   | -        | 用户名                              | admin               |
| └ nickname    | String        | 否   | -        | 昵称                                | 管理员              |
| └ role        | String        | 否   | -        | 角色                                | ADMIN               |
| └ lastLoginAt | LocalDateTime | 否   | -        | 最后登录时间                        | 2026-01-07T10:00:00 |
| timestamp     | Long          | 否   | -        | 时间戳                              | 1703145600000       |
| traceId       | String        | 否   | -        | 请求追踪 ID                         | trace-123456        |

#### 响应示例

```
{
    "code": 200,
    "message": "操作成功",
    "data": {
        "id": 1,
        "username": "admin",
        "nickname": "管理员",
        "role": "ADMIN",
        "lastLoginAt": "2026-01-07T10:00:00"
    },
    "timestamp": 1703145600000,
    "traceId": "trace-123456"
}
```

#### 错误码

无

### 修改密码

维护人：TG Live

#### URL

- 本地开发环境: `POST` http://localhost:10050/api/admin/auth/password

描述：修改密码

ContentType：`application/json`

#### 请求参数

##### Body Parameter

| 名称        | 类型   | 必填 | 最大长度 | 描述                                         | 示例值      |
| ----------- | ------ | ---- | -------- | -------------------------------------------- | ----------- |
| oldPassword | String | 是   | -        | 旧密码                                       | oldpassword |
| newPassword | String | 是   | 100      | 新密码（6-100 字符）<br>Validate[max: 100; ] | newpassword |

#### 请求示例

```
{
    "oldPassword": "oldpassword",
    "newPassword": "newpassword"
}
```

#### 响应参数

| 名称      | 类型    | 必填 | 最大长度 | 描述                        | 示例值        |
| --------- | ------- | ---- | -------- | --------------------------- | ------------- |
| code      | Integer | 否   | -        | 响应码                      | 200           |
| message   | String  | 否   | -        | 响应消息                    | 操作成功      |
| data      | object  | 否   | -        | 响应数据 (ActualType: Void) |               |
| timestamp | Long    | 否   | -        | 时间戳                      | 1703145600000 |
| traceId   | String  | 否   | -        | 请求追踪 ID                 | trace-123456  |

#### 响应示例

```
{
    "code": 200,
    "message": "操作成功",
    "data": {},
    "timestamp": 1703145600000,
    "traceId": "trace-123456"
}
```

#### 错误码

无

## 统计

### 获取仪表盘统计数据

维护人：TG Live

#### URL

- 本地开发环境: `GET` http://localhost:10050/api/admin/stats/dashboard

描述：获取仪表盘统计数据

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

#### 请求参数

#### 响应参数

| 名称             | 类型    | 必填 | 最大长度 | 描述                                     | 示例值        |
| ---------------- | ------- | ---- | -------- | ---------------------------------------- | ------------- |
| code             | Integer | 否   | -        | 响应码                                   | 200           |
| message          | String  | 否   | -        | 响应消息                                 | 操作成功      |
| data             | object  | 否   |          | 响应数据 (ActualType: DashboardStatsDTO) |               |
| └ machineTotal   | Long    | 否   | -        | 机器总数                                 | 10            |
| └ machineEnabled | Long    | 否   | -        | 启用的机器数                             | 8             |
| └ cameraTotal    | Long    | 否   | -        | 摄像头总数                               | 20            |
| └ cameraOnline   | Long    | 否   | -        | 在线摄像头数                             | 15            |
| └ cameraOffline  | Long    | 否   | -        | 离线摄像头数                             | 5             |
| └ channelTotal   | Long    | 否   | -        | 通道总数                                 | 40            |
| timestamp        | Long    | 否   | -        | 时间戳                                   | 1703145600000 |
| traceId          | String  | 否   | -        | 请求追踪 ID                              | trace-123456  |

#### 响应示例

```
{
    "code": 200,
    "message": "操作成功",
    "data": {
        "machineTotal": 10,
        "machineEnabled": 8,
        "cameraTotal": 20,
        "cameraOnline": 15,
        "cameraOffline": 5,
        "channelTotal": 40
    },
    "timestamp": 1703145600000,
    "traceId": "trace-123456"
}
```

#### 错误码

无
