新增README

README.md

@@ -1,2 +1,113 @@
-# tv_show_v1
+# TV Show Control System V1
 
+本项目是一个基于 Flask 的综合展控系统，用于控制展厅内的多媒体播放和硬件设备。
+
+## 功能特性
+
+系统主要包含以下控制模块：
+
+*   **Kodi 媒体控制**: 控制 Kodi 播放器进行视频播放、暂停、停止等操作，支持心跳检测和空闲时自动播放。
+*   **LED 灯效控制**: 集成 WLED 控制器，实现灯光效果的切换和管理。
+*   **Home Assistant (HA) 集成**: 接入 Home Assistant 平台，控制接入 HA 的各类智能家居设备。
+*   **门禁控制**: 控制门禁设备的开关状态。
+*   **小米电视 (MiTV) 控制**: 控制小米电视的开关机及状态查询。
+*   **Web 管理界面**: 提供直观的网页后台，方便管理和操作上述设备。
+
+## 环境配置
+
+本项目推荐使用 [uv](https://github.com/astral-sh/uv) 进行 Python 环境管理和依赖安装，以获得更快的安装速度。
+
+### 1. 安装 uv
+
+如果你还没有安装 `uv`，请参考官方文档进行安装。
+
+**Windows (PowerShell):**
+```powershell
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+**macOS / Linux:**
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### 2. 创建虚拟环境
+
+在项目根目录下运行以下命令创建虚拟环境：
+
+```bash
+uv venv
+```
+
+此命令会在项目目录下创建一个 `.venv` 文件夹。
+
+### 3. 激活虚拟环境
+
+**Windows:**
+```powershell
+.venv\Scripts\activate
+```
+
+**macOS / Linux:**
+```bash
+source .venv/bin/activate
+```
+
+### 4. 安装依赖
+
+使用 `uv` 安装项目所需依赖：
+
+```bash
+uv pip install -r requirements.txt
+```
+
+## 配置文件说明
+
+项目依赖以下配置文件，请根据实际部署环境修改（通常有 `_prod` 和 `_test` 两个版本，生产环境请使用 `_prod`）：
+
+*   `ha_config_prod.yaml`: Home Assistant 连接配置（地址、Token、实体ID等）。
+*   `kodi_config_prod.yaml`: Kodi 播放器连接配置（地址、端口、账号密码等）。
+*   `led_config.yaml`: LED 灯效配置。
+*   `door_config.yaml`: 门禁设备配置。
+*   `video_config_prod.yaml`: 视频播放列表及对应的灯效配置。
+
+## 运行项目
+
+### 启动 Flask API 服务
+
+确保虚拟环境已激活，然后运行：
+
+```bash
+python flask_api.py
+```
+
+或者使用便捷脚本：
+
+**Windows:**
+直接运行 `run_flask_api.bat`。
+
+**Ubuntu / Linux:**
+先赋予执行权限，然后运行：
+```bash
+chmod +x run_flask_api.sh
+./run_flask_api.sh
+```
+
+### 访问管理界面
+
+服务启动后，默认监听 `5050` 端口。请在浏览器中访问：
+
+http://localhost:5050
+
+## 目录结构
+
+*   `api/`: Flask Blueprint 路由接口定义。
+*   `application/`: 核心业务逻辑线程（Kodi 监控、LED 控制等）。
+*   `hardware/`: 底层硬件控制模块实现。
+*   `templates/`: Web 前端页面模板。
+*   `utils/`: 工具类（日志配置等）。
+*   `logs/`: 系统运行日志。
+
+## API 文档
+
+详细的 API 接口说明请参考 [README_API.md](README_API.md)。

run_flask_api.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+
+# 获取脚本所在目录并进入
+cd "$(dirname "$0")"
+
+echo "========================================"
+echo "启动 Flask API 服务器 (Ubuntu/Linux)"
+echo "========================================"
+
+# 尝试激活虚拟环境
+if [ -f "venv/bin/activate" ]; then
+    echo "正在激活虚拟环境: venv"
+    source venv/bin/activate
+elif [ -f ".venv/bin/activate" ]; then
+    echo "正在激活虚拟环境: .venv"
+    source .venv/bin/activate
+elif [ -f "env/bin/activate" ]; then
+    echo "正在激活虚拟环境: env"
+    source env/bin/activate
+else
+    echo "警告: 未找到虚拟环境，将使用系统 Python"
+    echo "提示: 如果存在虚拟环境，请将其命名为 venv、.venv 或 env"
+fi
+
+# 显示当前 Python 信息
+echo ""
+echo "当前 Python 版本:"
+python3 --version || python --version
+echo "Python 路径:"
+which python3 || which python
+
+echo ""
+echo "========================================"
+echo "启动 Flask API 服务器..."
+echo "========================================"
+
+# 运行 Flask API
+# 优先使用 python3，如果不存在则使用 python
+if command -v python3 &> /dev/null; then
+    python3 flask_api.py
+else
+    python flask_api.py
+fi
+
+echo ""
+echo "Flask API 服务器已停止"
+# read -p "按回车键退出..." # 保持窗口打开，类似Windows的pause
+