# LED 与 Kodi 控制接口文档（Flask API）

本项目提供一个基于 Flask 的 HTTP API 与网页界面，用于控制展品 LED 灯效与 Kodi 播放。

## 环境与运行

1. 安装依赖
```bash
pip install -r requirements.txt
```

2. 启动服务
```bash
python flask_api.py
```
或双击 `start_server.bat`

3. 访问
- 网页界面：`http://localhost:5000`
- API 根路径同上（默认端口 5000，已启用 CORS）

## 返回格式约定

- 所有接口均返回 JSON
- 统一字段：
  - `success`：布尔，是否成功
  - `message`：字符串，结果说明
  - `data`：对象，可选，承载具体数据

---

## 页面

- **GET** `/`
  - 返回 `templates/index.html` 页面

---

## LED 灯效控制

- **GET** `/api/led/status`
  - 说明：获取当前 LED 灯效运行状态
  - 成功响应示例：
```json
{
  "success": true,
  "data": {
    "is_running": true,
    "message": "灯效正在运行"
  }
}
```

- **POST** `/api/led/start`
  - 说明：按展品 ID 启动灯效
  - 请求体（JSON）：
```json
{ "exhibit_id": 0 }
```
  - 校验：`exhibit_id` 必须为大于等于 0 的整数
  - 成功响应示例：
```json
{
  "success": true,
  "message": "展品 0 的灯效已启动",
  "data": { "exhibit_id": 0, "is_running": true }
}
```

- **POST** `/api/led/stop`
  - 说明：停止当前灯效
  - 成功响应示例：
```json
{ "success": true, "message": "灯效已停止", "data": { "is_running": false } }
```

---

## Kodi 播放控制

- **GET** `/api/kodi/status`
  - 说明：获取 Kodi 播放线程状态
  - 成功响应示例：
```json
{
  "success": true,
  "data": {
    "is_running": false,
    "message": "Kodi播放线程已停止"
  }
}
```

- **POST** `/api/kodi/start`
  - 说明：启动或切换 Kodi 播放到指定 `video_id`
  - 请求体（JSON）：
```json
{ "video_id": 1 }
```
  - 校验：`video_id` 必须为大于等于 0 的整数
  - 成功响应示例：
```json
{ "success": true, "message": "Kodi开始/切换播放 视频ID=1", "data": { "video_id": 1 } }
```

- **POST** `/api/kodi/stop`
  - 说明：停止 Kodi 播放
  - 成功响应示例：
```json
{ "success": true, "message": "Kodi播放已停止" }
```

---

## 失败与错误码

- 参数缺失/非法：HTTP 400
  - 示例：
```json
{ "success": false, "message": "缺少展品ID参数" }
```

- 服务器内部错误：HTTP 500
  - 示例：
```json
{ "success": false, "message": "启动灯效失败: error detail" }
```

---

## curl 示例

```bash
# LED 状态
curl -s http://localhost:5000/api/led/status | jq

# 启动 LED（展品ID=0）
curl -s -X POST http://localhost:5000/api/led/start \
  -H "Content-Type: application/json" \
  -d '{"exhibit_id": 0}' | jq

# 停止 LED
curl -s -X POST http://localhost:5000/api/led/stop | jq

# Kodi 状态
curl -s http://localhost:5000/api/kodi/status | jq

# 启动/切换 Kodi（视频ID=1）
curl -s -X POST http://localhost:5000/api/kodi/start \
  -H "Content-Type: application/json" \
  -d '{"video_id": 1}' | jq

# 停止 Kodi
curl -s -X POST http://localhost:5000/api/kodi/stop | jq
```

---

## 目录结构（节选）

```
LEDEffectFramework_V1/
├── flask_api.py          # Flask API 入口
├── application/
│   ├── wled_thread.py    # LED 业务逻辑入口
│   └── kodi_thread.py    # Kodi 业务逻辑入口
├── hardware/             # 硬件/控制模块
├── templates/
│   └── index.html        # 网页界面
├── requirements.txt
├── start_server.bat
└── README_API.md
```

## 备注

- 端口、跨域等在 `flask_api.py` 中配置，默认 `0.0.0.0:5000`
- 具体硬件行为取决于 `application/*` 与 `hardware/*` 实现