tv_show_v1/API_DOCUMENTATION.md

API 接口文档

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

基础信息

• 默认端口: 5050
• 认证方式: 基于 Session 的登录认证 (装饰器 @login_required)
  • 未登录访问 API 接口返回 HTTP 401 及 {"success": False, "message": "未登录"}
  • 未登录访问页面会重定向到 /login
• 数据格式: 请求和响应主要使用 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

• 请求参数:

  {
    "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

• 请求参数:

  {
    "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

• 参数:

  {
    "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

• 请求参数:

  {
    "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

• 请求参数:

  {
    "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 接口上传的图片文件。