# API 接口文档

本文档基于 `flask_api.py` 整理，描述了 TV Show 控制系统的后端接口。

**基础信息**
- **默认端口**: `5050`
- **认证方式**: 基于 Session 的登录认证 (装饰器 `@login_required`)
  - 未登录访问 API 接口返回 HTTP 401 及 `{"success": False, "message": "未登录"}`
  - 未登录访问页面会重定向到 `/login`
- **数据格式**: 请求和响应主要使用 JSON 格式 (图片上传接口除外)

---

## 1. 认证与基础页面

### 登录
- **接口地址**: `/login`
- **请求方式**: `POST`
- **请求类型**: `application/x-www-form-urlencoded`
- **请求参数**:
  - `username`: 用户名 (默认: admin)
  - `password`: 密码 (默认: HNYZ0821)
- **响应**: 登录成功重定向至首页，失败返回登录页并提示错误。

### 登出
- **接口地址**: `/logout`
- **请求方式**: `GET`
- **说明**: 清除 Session 并重定向到登录页。

---

## 2. LED 灯效控制

### 获取 LED 状态
- **接口地址**: `/api/led/status`
- **请求方式**: `GET`
- **响应示例**:
  ```json
  {
      "success": true,
      "data": {
          "is_running": true,
          "message": "灯效正在运行"
      }
  }
  ```

### 启动展品灯效
- **接口地址**: `/api/led/start`
- **请求方式**: `POST`
- **请求头**: `Content-Type: application/json`
- **请求参数**:
  ```json
  {
      "exhibit_id": 1  // (必填) 展品ID，整数 >= 0
  }
  ```
- **响应示例**:
  ```json
  {
      "success": true,
      "message": "展品 1 的灯效已启动",
      "data": { "exhibit_id": 1, "is_running": true }
  }
  ```

### 停止灯效
- **接口地址**: `/api/led/stop`
- **请求方式**: `POST`
- **说明**: 停止当前正在运行的灯效。
- **响应示例**:
  ```json
  {
      "success": true,
      "message": "灯效已停止",
      "data": { "is_running": false }
  }
  ```

---

## 3. Kodi 播放控制

### 获取 Kodi 播放线程状态
- **接口地址**: `/api/kodi/status`
- **请求方式**: `GET`
- **说明**: 检查后台 Kodi 控制线程是否存活。

### 获取 Kodi 客户端列表
- **接口地址**: `/api/kodi/clients`
- **请求方式**: `GET`
- **响应**: 返回所有配置的 Kodi 客户端详情列表。

### 获取视频列表
- **接口地址**: `/api/kodi/videos`
- **请求方式**: `GET`
- **响应**: 返回可播放的视频列表信息。

### 启动/切换视频播放
- **接口地址**: `/api/kodi/start`
- **请求方式**: `POST`
- **请求头**: `Content-Type: application/json`
- **请求参数**:
  ```json
  {
      "video_id": 1,    // (必填) 视频ID，整数 >= 0
      "volume": 50      // (可选) 音量，0-100 的整数，不填则不改变音量
  }
  ```
- **响应示例**:
  ```json
  {
      "success": true,
      "message": "Kodi开始/切换播放 视频ID=1 音量=50",
      "data": { "video_id": 1, "volume": 50 }
  }
  ```

### 设置全局音量
- **接口地址**: `/api/kodi/set_volume`
- **请求方式**: `POST`
- **请求头**: `Content-Type: application/json`
- **请求参数**:
  ```json
  {
      "volume": 60      // (必填) 音量值，0-100
  }
  ```

### 播放图片
- **接口地址**: `/api/kodi/play_image`
- **请求方式**: `POST`
- **说明**: 支持 **文件上传** 或 **URL** 两种方式，同时需要指定客户端索引。

**方式一 (文件上传):**
- **Content-Type**: `multipart/form-data`
- **参数**:
  - `file`: (文件对象) 图片文件 (支持 jpg, png, jpeg, gif, bmp, webp)
  - `kodi_client_index`: (整数) 客户端索引

**方式二 (JSON URL):**
- **Content-Type**: `application/json`
- **参数**:
  ```json
  {
      "image_url": "http://example.com/image.jpg",
      "kodi_client_index": 0
  }
  ```

### 播放 RTSP 视频流
- **接口地址**: `/api/kodi/play_rtsp`
- **请求方式**: `POST`
- **请求头**: `Content-Type: application/json`
- **请求参数**:
  ```json
  {
      "rtsp_url": "rtsp://...",  // (必填) RTSP流地址
      "kodi_client_index": 0,    // (必填) 客户端索引
      "volume": 0                // (可选) 音量，默认0
  }
  ```

### 撤销独立状态
- **接口地址**: `/api/kodi/revoke_individual_state`
- **请求方式**: `POST`
- **说明**: 将所有处于独立播放状态（如播放图片、RTSP）的客户端重置回默认状态。

### 启动所有 Kodi 应用
- **接口地址**: `/api/kodi/start_all_apps`
- **请求方式**: `POST`
- **说明**: 尝试在所有客户端上启动 Kodi 应用程序。

---

## 4. 电视 (MiTV) 电源控制

> **注意**: 以下接口均为异步执行，API 会立即返回成功消息，实际操作在后台进行。

### 唤醒指定电视
- **接口地址**: `/api/mitv/turn_on`
- **请求方式**: `POST`
- **请求头**: `Content-Type: application/json`
- **请求参数**:
  ```json
  {
      "kodi_id": 1  // (必填) 对应 Kodi 客户端的 ID/索引
  }
  ```

### 息屏指定电视
- **接口地址**: `/api/mitv/turn_off`
- **请求方式**: `POST`
- **请求头**: `Content-Type: application/json`
- **请求参数**:
  ```json
  {
      "kodi_id": 1
  }
  ```

### 唤醒所有电视
- **接口地址**: `/api/mitv/turn_on_all`
- **请求方式**: `POST`
- **说明**: 发送指令唤醒配置中的所有电视。

### 息屏所有电视
- **接口地址**: `/api/mitv/turn_off_all`
- **请求方式**: `POST`
- **说明**: 发送指令息屏配置中的所有电视。

---

## 5. 其他

### 文件访问
- **接口地址**: `/uploads/<filename>`
- **请求方式**: `GET`
- **说明**: 访问通过 `/api/kodi/play_image` 接口上传的图片文件。