# API 接口文档

本文档描述了 TV Show 控制系统的后端接口。

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

---

## 1. 认证与基础页面

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

### 登出
- **接口地址**: `/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
  }
  ```

### 停止灯效
- **接口地址**: `/api/led/stop`
- **请求方式**: `POST`
- **说明**: 停止当前正在运行的灯效。

---

## 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 的整数，不填则不改变音量 (-1)
  }
  ```

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

### 获取全局音量
- **接口地址**: `/api/kodi/get_volume`
- **请求方式**: `GET`
- **响应示例**:
  ```json
  {
      "success": true,
      "data": {
          "volume": 60
      }
  }
  ```

### 闲时自动播放控制
- **控制启停**: `/api/kodi/free_time/control` (POST)
  - 参数: `{"action": "start"}` (开启自动播放功能) | `{"action": "stop"}` (停止自动播放功能)
  - 说明：
    - **自动逻辑**: 功能开启且在 07:30-18:00 时间段内，自动循环播放视频 ID 0。
    - **手动干预**: 无论当前时间是否在时间段内，手动发送 `start` 均会立即强制开启播放；发送 `stop` 会立即强制停止播放。
- **获取状态**: `/api/kodi/free_time/status` (GET)
  - 响应包含: `is_running` (功能开关状态), `enabled` (同 is_running), `is_thread_alive` (底层线程存活状态)

### 播放图片
- **接口地址**: `/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`
  - 息屏: `/api/mitv/turn_off`
- **请求方式**: `POST`
- **请求头**: `Content-Type: application/json`
- **请求参数**:
  ```json
  {
      "kodi_id": 1  // (必填) 对应 Kodi 客户端的 ID/索引
  }
  ```

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

---

## 5. HA 设备控制 (灯光与开关)

> **注意**: 以下接口均为异步执行，API 会立即返回成功消息。

### 设备控制接口列表
所有接口均为 `POST` 请求，无必填参数 (URL 区分动作)。

| 设备名称 | 打开接口 (turn_on) | 关闭接口 (turn_off) |
| :--- | :--- | :--- |
| **一楼大门玄关顶灯** | `/api/ha/entrance_lights/turn_on` | `/api/ha/entrance_lights/turn_off` |
| **一楼大门玄关射灯** | `/api/ha/exhibition_spotlight/turn_on` | `/api/ha/exhibition_spotlight/turn_off` |
| **一楼展厅顶灯 (等级)** | `/api/ha/exhibition_ceiling_lights/set_level` | (使用等级0关闭) |
| **展厅桌面灯座总开关** | `/api/ha/exhibition_desktop_switch/turn_on` | `/api/ha/exhibition_desktop_switch/turn_off` |
| **展厅桌面3D风扇投影** | `/api/ha/exhibition_3d_fan/turn_on` | `/api/ha/exhibition_3d_fan/turn_off` |
| **展台桌子灯带** | `/api/ha/exhibition_stand_light_strip/turn_on` | `/api/ha/exhibition_stand_light_strip/turn_off` |

### 展厅顶灯等级控制 (一楼)
- **接口地址**: `/api/ha/exhibition_ceiling_lights/set_level`
- **请求方式**: `POST`
- **请求头**: `Content-Type: application/json`
- **请求参数**:
  ```json
  {
      "level": 1  // (必填) 等级 0-3 (0:全关, 1:单灯, 2:双灯, 3:全开)
  }
  ```

### 全局控制
- **打开所有设备**: `/api/ha/turn_on_all` (POST)
- **关闭所有设备**: `/api/ha/turn_off_all` (POST)

---

## 6. 门禁控制

### 门禁模式设置
- **接口地址**: `/api/door/control`
- **请求方式**: `POST`
- **请求头**: `Content-Type: application/json`
- **请求参数**:
  ```json
  {
      "control_way": 0,    // (必填) 0:在线模式, 1:常开模式, 2:常闭模式
      "password": "..."    // (可选) 密码
  }
  ```
- **说明**: 异步执行。

### 远程开门
- **接口地址**: `/api/door/open`
- **请求方式**: `POST`
- **请求头**: `Content-Type: application/json`
- **请求参数**:
  ```json
  {
      "door_id": 1,        // (必填) 门ID，整数
      "password": "..."    // (可选) 密码
  }
  ```
- **说明**: 异步执行。

---

## 7. 其他

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