5af7fc18a5
- Fix state_machine reset_state_progress: reset sequence index before validation to prevent out-of-bounds error on state transitions - Fix video transformer test: use ±1 tolerance for OpenCV interpolation - Add core integration tests (service_manager, dependencies, messages) - Add HTTP compat routes (/index.html, POST /api/wifi/scan, hotspot aliases) - Rewrite clients/docs/API.md to match actual implementation - Fix BLE unused imports warning - CEO task planning for next round (ConfigReload, playlist snapshot) cargo check: 0 warnings, cargo test: 22/22 passed Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
314 lines
3.6 KiB
Markdown
314 lines
3.6 KiB
Markdown
# 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, ... }`
|