合并

etl_billiards/gui/README.md

@@ -0,0 +1,141 @@
+# 飞球 ETL GUI 管理系统
+
+一个基于 PySide6 的图形化 ETL 管理工具。
+
+## 功能特性
+
+- **任务配置**: 选择和配置 ETL 任务，支持参数设置和 CLI 命令预览
+- **任务管理**: 任务队列管理、执行历史记录、自动执行
+- **环境配置**: 图形化编辑 `.env` 配置文件
+- **数据库查看**: 浏览表结构、执行 SQL 查询
+- **ETL 状态**: 实时查看 ODS/DWD 数据状态和执行记录
+- **日志查看**: 实时日志输出、过滤、导出
+
+## 快速开始
+
+### 1. 安装依赖
+
+```bash
+cd etl_billiards
+pip install -r requirements.txt
+```
+
+### 2. 运行 GUI
+
+**方法一：使用启动脚本**
+
+```bash
+# Windows 命令行
+run_gui.bat
+
+# 或 PowerShell
+.\run_gui.ps1
+```
+
+**方法二：直接运行 Python**
+
+```bash
+cd etl_billiards
+python -m gui.main
+```
+
+## 打包为 EXE
+
+### 安装打包工具
+
+```bash
+pip install pyinstaller
+```
+
+### 执行打包
+
+```bash
+# 目录模式（推荐，启动更快）
+python build_exe.py
+
+# 单文件模式
+python build_exe.py --onefile
+
+# 显示控制台（调试用）
+python build_exe.py --console
+
+# 清理并重新打包
+python build_exe.py --clean
+```
+
+打包完成后，EXE 文件位于 `dist/ETL管理系统/` 目录。
+
+## 目录结构
+
+```
+gui/
+├── main.py              # 应用入口
+├── main_window.py       # 主窗口
+├── widgets/             # UI 组件
+│   ├── task_panel.py    # 任务配置面板
+│   ├── task_manager.py  # 任务管理器
+│   ├── env_editor.py    # 环境变量编辑器
+│   ├── log_viewer.py    # 日志查看器
+│   ├── db_viewer.py     # 数据库查看器
+│   └── status_panel.py  # ETL 状态面板
+├── workers/             # 后台工作线程
+│   ├── task_worker.py   # 任务执行线程
+│   └── db_worker.py     # 数据库查询线程
+├── models/              # 数据模型
+│   └── task_model.py    # 任务数据模型
+├── utils/               # 工具模块
+│   ├── cli_builder.py   # CLI 命令构建器
+│   └── config_helper.py # 配置辅助
+└── resources/           # 资源文件
+    └── styles.qss       # 样式表
+```
+
+## 使用说明
+
+### 任务配置
+
+1. 在左侧选择任务分类
+2. 勾选要执行的任务
+3. 配置运行参数（Pipeline 模式、时间窗口等）
+4. 查看底部的 CLI 命令预览
+5. 点击「立即执行」或「添加到队列」
+
+### 环境配置
+
+1. 打开「环境配置」面板
+2. 编辑各项配置（数据库、API、路径等）
+3. 点击「保存」
+
+### 数据库查看
+
+1. 打开「数据库」面板
+2. 输入或使用 .env 中的 DSN
+3. 点击「连接」
+4. 浏览表结构或执行 SQL 查询
+
+## 常见问题
+
+### Q: 启动时提示缺少 PySide6
+
+```bash
+pip install PySide6
+```
+
+### Q: 连接数据库失败
+
+检查 `.env` 中的 `PG_DSN` 配置是否正确。
+
+### Q: 打包后运行闪退
+
+使用 `--console` 参数重新打包，查看错误信息：
+
+```bash
+python build_exe.py --console
+```
+
+## 技术栈
+
+- Python 3.10+
+- PySide6 (Qt for Python)
+- psycopg2 (PostgreSQL)
+- PyInstaller (打包)