# API 文档

## 目录

- [认证接口](#认证接口)
- [输入控制接口](#输入控制接口)
- [流媒体接口](#流媒体接口)
- [文件传输接口](#文件传输接口)
- [WebSocket 消息类型](#websocket-消息类型)

---

## 认证接口

### POST /login

Web 登录接口，用于用户身份认证。

**请求体**

```json
{
  "password": "your_password"
}
```

**参数说明**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| password | string | 否 | 用户密码（如果服务器未配置密码则不需要） |

**响应示例**

成功响应（200）：
```json
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "message": "Authentication disabled"
}
```

失败响应（400）：
```json
{
  "success": false,
  "error": "Password is required"
}
```

失败响应（401）：
```json
{
  "success": false,
  "error": "Invalid password"
}
```

---

### POST /api/auth/login

API 登录接口，功能与 `/login` 相同。

**请求体**

```json
{
  "password": "your_password"
}
```

**响应示例**

成功响应（200）：
```json
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

---

### POST /api/auth/verify

Token 验证接口，用于验证 JWT Token 是否有效。

**请求头**

```
Authorization: Bearer <token>
```

**响应示例**

成功响应（200）：
```json
{
  "success": true,
  "valid": true,
  "userId": "default-user"
}
```

失败响应（401）：
```json
{
  "success": false,
  "valid": false,
  "error": "No token provided"
}
```

---

## 输入控制接口

所有输入控制接口需要在请求头中携带有效的 Token：

```
Authorization: Bearer <token>
```

### 鼠标操作

#### POST /api/input/mouse/move

移动鼠标到指定坐标。

**请求体**

```json
{
  "x": 100,
  "y": 200
}
```

**参数说明**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| x | number | 是 | 目标 X 坐标 |
| y | number | 是 | 目标 Y 坐标 |

**响应示例**

成功响应（200）：
```json
{
  "success": true
}
```

失败响应（400）：
```json
{
  "success": false,
  "error": "Invalid coordinates"
}
```

---

#### POST /api/input/mouse/down

按下鼠标按键。

**请求体**

```json
{
  "button": "left"
}
```

**参数说明**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| button | string | 否 | left | 鼠标按键：`left`、`right`、`middle` |

**响应示例**

```json
{
  "success": true
}
```

---

#### POST /api/input/mouse/up

释放鼠标按键。

**请求体**

```json
{
  "button": "left"
}
```

**参数说明**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| button | string | 否 | left | 鼠标按键：`left`、`right`、`middle` |

**响应示例**

```json
{
  "success": true
}
```

---

#### POST /api/input/mouse/click

点击鼠标按键。

**请求体**

```json
{
  "button": "left"
}
```

**参数说明**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| button | string | 否 | left | 鼠标按键：`left`、`right`、`middle` |

**响应示例**

```json
{
  "success": true
}
```

---

#### POST /api/input/mouse/wheel

鼠标滚轮滚动。

**请求体**

```json
{
  "delta": 100
}
```

**参数说明**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| delta | number | 是 | 滚动量（正数向上，负数向下） |

**响应示例**

```json
{
  "success": true
}
```

---

### 键盘操作

#### POST /api/input/keyboard/down

按下键盘按键。

**请求体**

```json
{
  "key": "a"
}
```

**参数说明**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| key | string | 是 | 按键名称（如 `a`、`enter`、`ctrl`、`shift` 等） |

**响应示例**

```json
{
  "success": true
}
```

---

#### POST /api/input/keyboard/up

释放键盘按键。

**请求体**

```json
{
  "key": "a"
}
```

**参数说明**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| key | string | 是 | 按键名称 |

**响应示例**

```json
{
  "success": true
}
```

---

#### POST /api/input/keyboard/press

按下并释放键盘按键（单击）。

**请求体**

```json
{
  "key": "enter"
}
```

**参数说明**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| key | string | 是 | 按键名称 |

**响应示例**

```json
{
  "success": true
}
```

---

#### POST /api/input/keyboard/type

输入文本字符串。

**请求体**

```json
{
  "text": "Hello World"
}
```

**参数说明**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| text | string | 是 | 要输入的文本内容 |

**响应示例**

```json
{
  "success": true
}
```

---

## 流媒体接口

### GET /api/stream/info

获取流媒体信息。

**响应示例**

```json
{
  "success": true,
  "stream": {
    "status": "running",
    "resolution": {
      "width": 1920,
      "height": 1080
    },
    "fps": 30,
    "bitrate": 2000,
    "gop": 60,
    "encoder": "libx264"
  }
}
```

**字段说明**

| 字段 | 类型 | 说明 |
|------|------|------|
| status | string | 流状态：`running` 或 `stopped` |
| resolution | object | 屏幕分辨率 |
| fps | number | 帧率 |
| bitrate | number | 比特率（kbps） |
| gop | number | GOP 大小 |
| encoder | string | 编码器名称 |

---

### POST /api/stream/start

启动流媒体。

**响应示例**

```json
{
  "success": true,
  "message": "Stream started"
}
```

已运行时响应：
```json
{
  "success": true,
  "message": "Stream is already running"
}
```

---

### POST /api/stream/stop

停止流媒体。

**响应示例**

```json
{
  "success": true,
  "message": "Stream stopped"
}
```

未运行时响应：
```json
{
  "success": true,
  "message": "Stream is not running"
}
```

---

## 文件传输接口

### GET /api/files

获取文件列表。

**响应示例**

```json
{
  "files": [
    {
      "name": "example.txt",
      "size": 1024,
      "modifiedTime": "2024-01-01T12:00:00.000Z"
    }
  ]
}
```

---

### GET /api/files/browse

浏览目录内容。

**查询参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| path | string | 否 | 目录路径（默认为根目录） |

**请求示例**

```
GET /api/files/browse?path=documents
```

**响应示例**

```json
{
  "path": "documents",
  "directories": ["folder1", "folder2"],
  "files": [
    {
      "name": "file1.txt",
      "size": 1024,
      "modifiedTime": "2024-01-01T12:00:00.000Z"
    }
  ]
}
```

---

### POST /api/files/upload/start

开始上传会话（分块上传第一步）。

**请求体**

```json
{
  "filename": "example.zip",
  "totalChunks": 10,
  "fileSize": 52428800
}
```

**参数说明**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| filename | string | 是 | 文件名 |
| totalChunks | number | 是 | 总分块数 |
| fileSize | number | 是 | 文件总大小（字节） |

**响应示例**

```json
{
  "fileId": "a1b2c3d4e5f6g7h8",
  "chunkSize": 5242880,
  "message": "Upload session started"
}
```

---

### POST /api/files/upload/chunk

上传文件分块（分块上传第二步）。

**请求体**

Content-Type: `multipart/form-data`

| 字段 | 类型 | 说明 |
|------|------|------|
| fileId | string | 上传会话 ID |
| chunkIndex | number | 分块索引（从 0 开始） |
| chunk | file | 分块数据 |

**响应示例**

```json
{
  "success": true,
  "chunkIndex": 0
}
```

---

### POST /api/files/upload/merge

合并文件分块（分块上传第三步）。

**请求体**

```json
{
  "fileId": "a1b2c3d4e5f6g7h8",
  "totalChunks": 10,
  "filename": "example.zip"
}
```

**参数说明**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| fileId | string | 是 | 上传会话 ID |
| totalChunks | number | 是 | 总分块数 |
| filename | string | 是 | 最终文件名 |

**响应示例**

```json
{
  "success": true,
  "filename": "example.zip"
}
```

---

### GET /api/files/:filename

下载文件。

**路径参数**

| 参数 | 类型 | 说明 |
|------|------|------|
| filename | string | 文件名 |

**请求头**

支持 Range 请求，可用于断点续传：

```
Range: bytes=0-1023
```

**响应示例**

成功响应（200 或 206）：
- Content-Type: `application/octet-stream`
- Accept-Ranges: `bytes`
- Content-Length: 文件大小
- Content-Range: 范围（仅 206 响应）

失败响应（404）：
```json
{
  "error": "File not found"
}
```

---

### DELETE /api/files/:filename

删除文件。

**路径参数**

| 参数 | 类型 | 说明 |
|------|------|------|
| filename | string | 文件名 |

**响应示例**

成功响应（200）：
```json
{
  "success": true
}
```

失败响应（404）：
```json
{
  "error": "File not found"
}
```

---

## WebSocket 消息类型

### 客户端发送的消息类型

| 消息类型 | 说明 | 数据格式 |
|----------|------|----------|
| `mouseMove` | 鼠标移动 | `{ x: number, y: number }` |
| `mouseDown` | 鼠标按下 | `{ button: 'left' \| 'right' \| 'middle' }` |
| `mouseUp` | 鼠标释放 | `{ button: 'left' \| 'right' \| 'middle' }` |
| `mouseWheel` | 鼠标滚轮 | `{ delta: number }` |
| `keyDown` | 键盘按下 | `{ key: string }` |
| `keyUp` | 键盘释放 | `{ key: string }` |
| `clipboardGet` | 获取剪贴板内容 | 无额外数据 |
| `clipboardSet` | 设置剪贴板内容 | `{ content: string }` |

### 服务端发送的消息类型

| 消息类型 | 说明 | 数据格式 |
|----------|------|----------|
| `screenInfo` | 屏幕信息 | `{ width: number, height: number }` |
| `clipboardData` | 剪贴板数据 | `{ content: string }` |
| `clipboardResult` | 剪贴板操作结果 | `{ success: boolean }` |
| `clipboardTooLarge` | 剪贴板数据过大 | `{ message: string }` |

### 消息格式示例

**客户端发送鼠标移动：**
```json
{
  "type": "mouseMove",
  "data": {
    "x": 100,
    "y": 200
  }
}
```

**客户端发送键盘按键：**
```json
{
  "type": "keyDown",
  "data": {
    "key": "ctrl"
  }
}
```

**服务端发送屏幕信息：**
```json
{
  "type": "screenInfo",
  "data": {
    "width": 1920,
    "height": 1080
  }
}
```

**客户端请求剪贴板：**
```json
{
  "type": "clipboardGet"
}
```

**服务端返回剪贴板数据：**
```json
{
  "type": "clipboardData",
  "data": {
    "content": "复制的文本内容"
  }
}
```

---

## 错误响应格式

所有接口在发生错误时返回统一的错误格式：

```json
{
  "success": false,
  "error": "错误描述信息"
}
```

常见 HTTP 状态码：

| 状态码 | 说明 |
|--------|------|
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 401 | 未授权（Token 无效或过期） |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |