# ShowenV2 HTTP API 文档

## 基础信息

- Base URL: `http://<device-ip>:8080`
- API 前缀: `/api`
- 编码: `UTF-8`
- 认证: 当前版本无认证

## 响应约定

- 控制类/写操作接口统一返回：

```json
{
  "status": "ok",
  "message": "开始播放"
}
```

- 失败时返回：

```json
{
  "status": "error",
  "message": "错误描述"
}
```

- 查询类接口直接返回业务 JSON，不包裹 `ok` 字段。

## Web UI

### 控制台页面

```http
GET /
GET /index.html
```

- 当前实现为内嵌单文件 Web UI。
- 暂无独立静态资源目录服务；页面所需 CSS/JS 已内嵌在 HTML 中。

## WebSocket

### 连接地址

```text
ws://<device-ip>:8080/ws
```

### 服务端事件

- `status_update`
- `config_update`
- `state_update`
- `ble_update`

## 播放控制

### 获取播放状态

```http
GET /api/status
```

响应示例：

```json
{
  "running": true,
  "paused": false,
  "in_transition": false,
  "current_index": 0,
  "playlist_length": 3,
  "current_video": "intro"
}
```

### 播放

```http
POST /api/play
```

### 暂停

```http
POST /api/pause
```

### 下一个

```http
POST /api/next
```

### 上一个

```http
POST /api/previous
```

### 跳转到指定视频

```http
POST /api/goto/:index
```

- `index`: 从 `0` 开始的视频索引

### 获取播放列表

```http
GET /api/playlist
```

### 切换场景

```http
POST /api/scene/:name
```

- `name`: 场景名称字符串，不是数字索引

### 触发状态机事件

```http
POST /api/trigger/:name
POST /api/trigger/:name/:value
```

- `value` 为可选路径参数

## 配置

### 获取完整配置

```http
GET /api/config
```

### 获取显示配置

```http
GET /api/config/display
```

### 更新配置

```http
POST /api/config
Content-Type: application/json
```

- 请求体为完整配置 JSON
- 服务端会先校验，再写回配置文件，并向管理层发送热重载请求

## 视频文件管理

### 获取视频列表

```http
GET /api/videos
```

响应示例：

```json
[
  {
    "name": "demo.mp4",
    "size": 1048576
  }
]
```

### 上传视频

```http
POST /api/videos/upload
Content-Type: multipart/form-data
```

- 表单字段名：`file`
- 支持多文件上传

### 删除视频

```http
DELETE /api/videos/:filename
```

## WiFi

### 获取 WiFi 状态

```http
GET /api/wifi/status
```

响应示例：

```json
{
  "connected": true,
  "ssid": "MyWiFi",
  "ip": "192.168.1.10"
}
```

### 扫描 WiFi

```http
GET /api/wifi/scan
POST /api/wifi/scan
```

响应示例：

```json
[
  {
    "ssid": "MyWiFi",
    "signal": -50,
    "security": "WPA2"
  }
]
```

### 连接 WiFi

```http
POST /api/wifi/connect
Content-Type: application/json
```

```json
{
  "ssid": "MyWiFi",
  "password": "password123"
}
```

### 开启热点

```http
POST /api/wifi/ap/start
POST /api/wifi/hotspot/start
Content-Type: application/json
```

请求体可选：

```json
{
  "ssid": "showen",
  "password": "12345678"
}
```

### 关闭热点

```http
POST /api/wifi/ap/stop
POST /api/wifi/hotspot/stop
```

## BLE

### 获取 BLE 状态

```http
GET /api/ble/status
```

响应示例：

```json
{
  "running": true,
  "embedded": true,
  "device_name": "showen"
}
```

### BLE 兼容启动接口

```http
POST /api/ble/start
Content-Type: application/json
```

请求体可选：

```json
{
  "device_name": "showen"
}
```

### BLE 兼容停止接口

```http
POST /api/ble/stop
```

## 与旧文档的差异说明

- 不存在 `/api/stop`
- 不存在 `/api/wifi/disconnect`
- `/api/scene/:name` 使用场景名，不使用数字索引
- 查询接口直接返回业务对象，不再包裹 `{ "ok": true, ... }`