# 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)。