From 7abb876100164445401c9b65c70de5029c88708a Mon Sep 17 00:00:00 2001 From: chakcy <947105045@qq.com> Date: Sat, 13 Sep 2025 19:08:20 +0800 Subject: [PATCH] =?UTF-8?q?modify:=20=E8=AF=B4=E6=98=8E=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 299 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 281 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index f494cae..36a20f5 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,286 @@ +# PySide6 桌面应用实践项目 -```bat -python -m nuitka --onefile --windows-console-mode=disable --enable-plugin=pyside6 --lto=no --windows-icon-from-ico=.\resources\ico\logo.ico --output-dir=output --remove-output --jobs=4 main.py +这是一个基于 PySide6 和 QFluentWidgets 开发的桌面应用程序，重点展示了 `queue_sqlite` 在桌面应用中的实践应用，实现了高效的异步任务处理和消息队列机制。 + +## 项目特点 + +- 🖥️ **现代化界面**：采用 Fluent Design 设计风格 +- 🧩 **模块化架构**：功能模块清晰分离，便于扩展和维护 +- 🔄 **异步任务处理**：基于 queue_sqlite 的高效任务队列系统 +- 📡 **消息队列机制**：可靠的消息传递和处理框架 +- 🌐 **前后端通信**：通过队列系统实现前后端解耦 + +## 核心技术：queue_sqlite 的应用 + +### 队列调度器初始化 + +在 `app/scheduler_manager/__init__.py` 中初始化队列调度器： + +```python +from queue_sqlite.scheduler import QueueScheduler + +scheduler = QueueScheduler() ``` -```bat -python -m nuitka ^ ---onefile ^ ---windows-console-mode=disable ^ ---enable-plugin=pyside6 ^ ---lto=no ^ ---windows-icon-from-ico=.\resources\ico\logo.ico ^ ---output-dir=output ^ ---remove-output ^ ---jobs=4 ^ ---include-qt-plugins=mediaservice ^ ---include-data-dir=.venv/Lib/site-packages/PySide6/plugins=PySide6/plugins ^ -main.py +### 任务定义与挂载 + +在 `app/scheduler_manager/students/add_student.py` 中定义任务： + +```python +from queue_sqlite.mounter.task_mounter import TaskMounter +from queue_sqlite.model import MessageItem + +@TaskMounter.task(meta={"task_name": "add_student"}) +def add_student(message_item: MessageItem): + # 模拟耗时操作 + time.sleep(3) + print("点击了添加按钮") + return {"message": "学生添加成功"} ``` -```bat -ffmpeg -re -stream_loop -1 -i test.mp4 -vcodec libx264 -tune zerolatency -f mpegts tcp://127.0.0.1:5000?listen -``` \ No newline at end of file +### 监听器定义 + +在 `app/scheduler_manager/students/students_listen.py` 中定义监听器： + +```python +from queue_sqlite.mounter.listen_mounter import ListenMounter + +@ListenMounter.listener() +def students(str_students_list: str): + print("students signal received") + listen_signals.listening_students_signal.emit(json.loads(str_students_list)) +``` + +### 消息发送与处理 + +在 `app/view/students/student_interface.py` 中发送消息： + +```python +def add_student(self): + self.addButton.setEnabled(False) + scheduler.send_message( + MessageItem(content={}, destination="add_student"), + self.add_student_callback, + ) +``` + +### 前端与队列系统的交互 + +在 `app/view/web_view/entrance.py` 中通过 WebChannel 暴露队列操作给前端： + +```python +class WebViewQueueSqliteOperations(QObject): + @Slot(str, str, result=str) + def send_message(self, message: str, store_key: str): + def callback(result: MessageItem): + global_signals.update_queue_state.emit(result.to_dict(), store_key) + + scheduler.send_message(MessageItem.from_dict(json.loads(message)), callback) +``` + +### 项目结构 + +```text +项目根目录/ +├── main.py # 应用入口点，启动队列调度器 +├── app/ # 应用主要代码 +│ ├── config/ # 配置管理 +│ ├── scheduler_manager/ # 任务调度管理（queue_sqlite核心） +│ │ ├── __init__.py # 初始化队列调度器 +│ │ └── students/ # 学生相关任务和监听器 +│ ├── signal/ # 信号与事件处理 +│ ├── style/ # 样式定义 +│ └── view/ # 界面视图 +│ ├── camera/ # 摄像头界面 +│ ├── students/ # 学生管理界面（使用队列） +│ ├── video/ # 视频播放界面 +│ └── web_view/ # Web视图界面（与队列交互） +└── resources/ # 资源文件 + └── webview/ # Web前端资源 + ├── entrance/ # 主门户界面（调用队列接口） + └── new_plugin/ # 插件模板 +``` + +## queue_sqlite 实践详解 + +### 1. 任务调度器管理 + +在应用启动时初始化队列调度器，并在应用退出时正确关闭： + +```python +# main.py +def main(): + # 启动队列调度器 + scheduler.start_queue_scheduler() + + # ... 应用逻辑 ... + + # 停止队列调度器 + scheduler.stop_queue_scheduler() +``` + +### 2. 异步任务处理 + +通过队列系统处理耗时操作，保持UI响应： + +```python +# 发送消息到队列 +scheduler.send_message( + MessageItem(content={}, destination="add_student"), + self.add_student_callback, # 回调函数 +) + +# 处理回调 +def add_student_callback(self, message: MessageItem): + global_signals.show_add_dialog_signal.emit(message.to_dict()) +``` + +### 3. 前后端解耦 + +通过消息队列实现前后端解耦，前端发送消息，后端异步处理： + +```javascript +// 前端发送消息到队列 +queueSqlite.send_message( + JSON.stringify({ + "content": {"num": 1}, + "destination": "test" + }), + "taskStatus" +) +``` + +### 4. 状态管理 + +通过队列系统的回调机制更新前端状态： + +```python +def update_queue_state(self, result: dict, store_key: str): + json_str = json.dumps(result) + js_code = f""" + try {{ + if (typeof window.queueStore.updateQueueData === 'function') {{ + window.queueStore.updateQueueData('{store_key}', {json_str}); + }} + }} catch (error) {{ + console.error('Error in updateQueueData:', error); + }} + """ + self.page.runJavaScript(js_code) +``` + +### 5. 错误处理与重试 + +队列系统内置错误处理和重试机制，提高系统可靠性。 + +## 快速开始 + +### 环境要求 +- Python 3.8+ +- PySide6 +- queue-sqlite + +### 安装依赖 +```bash +# 初始化项目 +mkdir sqlite_queue_demo +cd sqlite_queue_demo +uv init +# 安装依赖 +uv add PySide6 qfluentwidgets opencv-python +# 克隆 queue_sqlite 项目 +mkdir lib +cd lib +git clone https://gitee.com/cai-xinpenge/pyside_queue_sqlite.git +或 +git clone http://124.71.68.6:3000/chakcy_code_repository/queue_sqlite.git +# 安装 queue_sqlite 依赖 +cd queue_sqlite +uv sync +# 激活环境 +.venv/Scripts/activate +# 构建 Rust 核心模块 +cd src/core +maturin develop --release +# 将会在 src/core/target/release 目录下生成 core.dll 或 core.so 文件。 将该文件复制到 queue_sqlite/core 目录下（dll文件需改名为pyd后缀）。 +mv target/release/core.dll ../queue_sqlite/core/core.pyd +deactivate +# 安装 queue_sqlite 项目 +cd ../../../../ +uv add lib/queue_sqlite +``` + +### 运行应用 +```bash +python main.py +``` + +## queue_sqlite 最佳实践 + +### 1. 任务定义 + +- 使用装饰器标记任务函数 +- 明确任务名称便于管理和调试 +- 合理设计任务参数和返回值 + +### 2. 消息设计 + +- 使用 MessageItem 封装消息内容 +- 明确消息目的地（destination） +- 包含必要的元数据 + +### 3. 回调处理 + +- 为每个消息指定回调函数 +- 在回调中更新UI状态 +- 处理可能的错误情况 + +### 4. 监听器使用 + +- 使用监听器响应数据变化 +- 通过信号机制通知UI更新 +- 保持监听器简洁高效 + +## 扩展开发 + +### 添加新任务 +1. 在 `scheduler_manager` 下创建新模块 +2. 使用 `@TaskMounter.task` 装饰器定义任务 +3. 在界面中发送消息到该任务 + +## 前端集成 + +1. 通过 WebChannel 暴露队列操作接口 +2. 在前端调用队列接口发送消息 +3. 通过回调更新前端状态 + +## 性能优化建议 + +1. **合理设置并发数**：根据任务类型调整队列并发数量 +2. **任务优先级**：为重要任务设置更高优先级 +3. **结果缓存**：对频繁请求的任务结果进行缓存 +4. **批量处理**：对相似任务进行批量处理提高效率 + +## 学习价值 + +本项目重点展示了： +- queue_sqlite 在桌面应用中的集成方式 +- 异步任务处理的最佳实践 +- 前后端通过消息队列解耦的方案 +- 基于回调的状态管理机制 +- 错误处理和重试策略 + +### 后续计划 + +- 增加队列监控界面 +- 实现任务优先级管理 +- 添加任务持久化存储 +- 优化队列性能指标 +- 增加分布式队列支持 + +## 贡献指南 + +欢迎提交 Issue 和 Pull Request 来帮助改进这个项目，特别是与 queue_sqlite 相关的优化和实践。 + +## 许可证 +MIT License \ No newline at end of file