优化

- 优化 Sentry日志上报，仅上报**异常**，ERROR级别日志不上报
- 优化 main.py，重构结构、提取常量并新增文档注释
- 优化 window.py，重构结构、提取常量并新增文档注释
- 优化 tray.py，重构结构、提取常量并新增文档注释
- 优化 app/tools 目录，重构结构并提取常量
- 优化 button_draw_utils.py，新增函数文档注释
- 优化 config.py，新增通知与音量常量配置
- 优化 roll_call.py，提取重复代码至**UI工具类**
- 优化 lottery.py，提取重复代码至**UI工具类**
- 新增 app/common/ui/ui_utils.py，创建通用**UI工具类**
- 新增 RollCallController，封装点名**业务逻辑**
- 新增 LotteryController，封装抽奖**业务逻辑**
- 新增 RollCallUIInterface，预留**自定义界面接口**
- 新增 LotteryUIInterface，预留**自定义界面接口**
- 优化 VoiceCacheManager，移除**内存缓存**，只保留磁盘缓存
- 优化 TTSHandler，整合**系统音量控制**逻辑
- 优化 edge_tts_worker.py，移除冗余注释，简化**代码结构**
- 优化 font_manager.py，重构字体加载逻辑，提取**常量映射**
- 优化 personalised.py，简化图标与主题函数，移除**重复代码**

Author: lzy98276

CHANGELOG/v2.2.1/CHANGELOG.md

@@ -8,6 +8,25 @@ v2.0 - Koharu（小鸟游星野） release 4
 ## 💡 功能优化
 
 - 优化 Sentry错误上报，过滤**第三方库**无效错误
+- 优化 Sentry日志上报，仅上报**异常**，ERROR级别日志不上报
+- 优化 main.py，重构结构、提取常量并新增文档注释
+- 优化 window.py，重构结构、提取常量并新增文档注释
+- 优化 tray.py，重构结构、提取常量并新增文档注释
+- 优化 app/tools 目录，重构结构并提取常量
+- 优化 button_draw_utils.py，新增函数文档注释
+- 优化 config.py，新增通知与音量常量配置
+- 优化 roll_call.py，提取重复代码至**UI工具类**
+- 优化 lottery.py，提取重复代码至**UI工具类**
+- 新增 app/common/ui/ui_utils.py，创建通用**UI工具类**
+- 新增 RollCallController，封装点名**业务逻辑**
+- 新增 LotteryController，封装抽奖**业务逻辑**
+- 新增 RollCallUIInterface，预留**自定义界面接口**
+- 新增 LotteryUIInterface，预留**自定义界面接口**
+- 优化 VoiceCacheManager，移除**内存缓存**，只保留磁盘缓存
+- 优化 TTSHandler，整合**系统音量控制**逻辑
+- 优化 edge_tts_worker.py，移除冗余注释，简化**代码结构**
+- 优化 font_manager.py，重构字体加载逻辑，提取**常量映射**
+- 优化 personalised.py，简化图标与主题函数，移除**重复代码**
 
 ## 🐛 修复问题
 

app/common/lottery/__init__.py

@@ -0,0 +1,6 @@
+# ==================================================
+# 抽奖模块
+# ==================================================
+from .lottery_utils import LotteryUtils, LotteryController, LotteryUIInterface
+
+__all__ = ["LotteryUtils", "LotteryController", "LotteryUIInterface"]

app/common/lottery/lottery_utils.py

@@ -1,5 +1,5 @@
 # ==================================================
-# 点名工具类
+# 抽奖工具类
 # ==================================================
 import json
 from random import SystemRandom
@@ -21,7 +21,6 @@
 )
 from app.tools.path_utils import get_data_path, open_file
 from app.tools.settings_access import readme_settings_async, get_safe_font_size
-
 from app.Language.obtain_language import get_any_position_value
 
 system_random = SystemRandom()
@@ -630,3 +629,238 @@ def update_start_button_state(button, total_count):
             button.setEnabled(False)
         else:
             button.setEnabled(True)
+
+
+class LotteryController:
+    """抽奖控制器类，封装抽奖业务逻辑"""
+
+    def __init__(self):
+        self.tts_handler = None
+        self.is_animating = False
+        self.final_selected_students = None
+        self.final_pool_name = None
+        self.final_selected_students_dict = None
+        self.final_group_filter = None
+        self.final_gender_filter = None
+        self.current_count = 1
+        self.ui_interface = None
+
+    def set_tts_handler(self, tts_handler):
+        """设置 TTS 处理器
+
+        Args:
+            tts_handler: TTS 处理器实例
+        """
+        self.tts_handler = tts_handler
+
+    def set_ui_interface(self, ui_interface):
+        """设置 UI 接口
+
+        Args:
+            ui_interface: UI 接口实例
+        """
+        self.ui_interface = ui_interface
+
+    def draw_random_prizes(self, pool_name: str, current_count: int):
+        """
+        按权重抽取奖品
+
+        Args:
+            pool_name: 奖池名称
+            current_count: 当前抽取数量
+
+        Returns:
+            dict: 包含抽取结果的字典
+        """
+        result = LotteryUtils.draw_random_prizes(pool_name, current_count)
+
+        self.final_selected_students = result.get("selected_prizes") or result.get(
+            "selected_students"
+        )
+        self.final_pool_name = result["pool_name"]
+        self.final_selected_students_dict = result.get(
+            "selected_prizes_dict"
+        ) or result.get("selected_students_dict")
+
+        return result
+
+    def draw_random_students(
+        self,
+        class_name,
+        group_index,
+        group_filter,
+        gender_index,
+        gender_filter,
+        current_count,
+        half_repeat,
+        pool_name=None,
+        prize_list=None,
+    ):
+        """
+        抽取随机学生
+
+        Args:
+            class_name: 班级名称
+            group_index: 小组索引
+            group_filter: 小组过滤器
+            gender_index: 性别索引
+            gender_filter: 性别过滤器
+            current_count: 当前抽取数量
+            half_repeat: 半重复设置
+            pool_name: 奖池名称（用于抽奖模式下应用内幕设置）
+            prize_list: 奖品列表（用于提高指定该奖品的学生的权重）
+
+        Returns:
+            dict: 包含抽取结果的字典
+        """
+        result = LotteryUtils.draw_random_students(
+            class_name,
+            group_index,
+            group_filter,
+            gender_index,
+            gender_filter,
+            current_count,
+            half_repeat,
+            pool_name,
+            prize_list,
+        )
+
+        return result
+
+    def get_prize_total_count(self, pool_name: str) -> int:
+        """
+        获取奖池奖品总数
+
+        Args:
+            pool_name: 奖池名称
+
+        Returns:
+            int: 奖品总数
+        """
+        return LotteryUtils.get_prize_total_count(pool_name)
+
+    def update_prize_many_count_label_text(self, pool_name: str, display_mode=None):
+        """
+        生成奖品总数/剩余显示文本
+
+        Args:
+            pool_name: 奖池名称
+            display_mode: 显示模式
+
+        Returns:
+            tuple: (总数, 剩余数, 格式化文本)
+        """
+        return LotteryUtils.update_prize_many_count_label_text(pool_name, display_mode)
+
+    def play_voice_result(self, pool_name, selected_students):
+        """
+        播放语音结果
+
+        Args:
+            pool_name: 奖池名称
+            selected_students: 选中的学生列表
+        """
+        if not self.tts_handler:
+            return
+
+        try:
+            from app.tools.settings_access import readme_settings_async
+
+            voice_settings = {
+                "voice_volume": readme_settings_async(
+                    "basic_voice_settings", "volume_size"
+                ),
+                "voice_speed": readme_settings_async(
+                    "basic_voice_settings", "speech_rate"
+                ),
+                "system_voice_name": readme_settings_async(
+                    "basic_voice_settings", "system_voice_name"
+                ),
+            }
+
+            prize_names = [prize[1] for prize in selected_students]
+
+            voice_engine = readme_settings_async("basic_voice_settings", "voice_engine")
+            engine_type = 1 if voice_engine == "Edge TTS" else 0
+
+            edge_tts_voice_name = readme_settings_async(
+                "basic_voice_settings", "edge_tts_voice_name"
+            )
+
+            self.tts_handler.voice_play(
+                config=voice_settings,
+                student_names=prize_names,
+                engine_type=engine_type,
+                voice_name=edge_tts_voice_name,
+                class_name=pool_name,
+            )
+        except Exception as e:
+            from loguru import logger
+
+            logger.exception(f"播放语音失败: {e}", exc_info=True)
+
+    def reset_drawn_prize_record(self, pool_name):
+        """
+        重置已抽取奖品记录
+
+        Args:
+            pool_name: 奖池名称
+        """
+        from app.tools.config import reset_drawn_prize_record
+
+        reset_drawn_prize_record(None, pool_name)
+
+    def update_start_button_state(self, button, total_count):
+        """
+        根据总奖数更新开始按钮的状态
+
+        Args:
+            button: 开始按钮对象
+            total_count: 总奖数
+        """
+        LotteryUtils.update_start_button_state(button, total_count)
+
+
+class LotteryUIInterface:
+    """抽奖界面接口，用于自定义界面实现
+
+    自定义界面需要继承此类并实现所有抽象方法
+    """
+
+    def on_draw_start(self):
+        """开始抽取时的回调"""
+        pass
+
+    def on_draw_stop(self):
+        """停止抽取时的回调"""
+        pass
+
+    def on_draw_result(self, selected_prizes, pool_name):
+        """抽取结果时的回调
+
+        Args:
+            selected_prizes: 选中的奖品列表
+            pool_name: 奖池名称
+        """
+        pass
+
+    def on_count_changed(self, total_count, remaining_count):
+        """奖数变化时的回调
+
+        Args:
+            total_count: 总奖数
+            remaining_count: 剩余奖数
+        """
+        pass
+
+    def on_reset(self):
+        """重置时的回调"""
+        pass
+
+    def on_error(self, error_message):
+        """错误发生时的回调
+
+        Args:
+            error_message: 错误信息
+        """
+        pass

app/common/roll_call/__init__.py

@@ -0,0 +1,6 @@
+# ==================================================
+# 点名模块
+# ==================================================
+from .roll_call_utils import RollCallUtils, RollCallController, RollCallUIInterface
+
+__all__ = ["RollCallUtils", "RollCallController", "RollCallUIInterface"]