playwrite/docs/LOGGING_REFACTORING_SUMMARY.md

GUI 日志系统重构完成总结

实施概述

已成功完成 GUI 日志系统的统一重构，实现了以下目标：

1. 统一日志格式：控制台和 UI 日志使用一致的格式和配置
2. 标准化接口：使用 Python 标准 logging 模块
3. 代码简化：减少了重复的日志处理代码
4. 易扩展性：后续可轻松添加文件输出、远程日志等功能

新增文件

1. gui/log_config.py

统一日志配置模块，提供：

• LOG_FORMAT: 日志格式常量
• DATE_FORMAT: 日期格式常量
• setup_gui_logging(level=logging.INFO): 初始化日志系统
• get_logger(name): 获取指定名称的 logger

2. gui/widgets/log_handler.py

自定义 logging Handler，桥接 logging 模块和 GUI：

• GuiTextHandler 类：将日志输出到 LogText 组件
• 线程安全设计：使用 after() 确保 GUI 更新在主线程
• 自动级别映射：将 logging 级别映射到 LogText 级别

3. tests/test_logging_simple.py

简单的非 GUI 测试脚本，验证日志配置。

4. tests/test_logging_system.py

完整的 GUI 测试脚本，测试所有日志功能（包括 GUI 界面）。

修改文件

1. gui/main_window.py

• 导入 setup_gui_logging
• 在 __init__ 中调用 setup_gui_logging() 初始化全局日志

2. gui/material_validation_tab.py

• 导入 logging, get_logger, GuiTextHandler
• 在 __init__ 中初始化 self.logger
• 在 _create_log_panel 中创建并配置 GuiTextHandler
• 更新 _update_log 方法使用标准 logging

3. gui/data_extraction_tab.py

• 导入 logging, get_logger, GuiTextHandler
• 在 __init__ 中初始化 self.logger
• 在 _create_log_panel 中创建并配置 GuiTextHandler
• 更新 _update_log 方法使用标准 logging

4. gui/widgets/__init__.py

• 添加 GuiTextHandler 到导出列表

日志格式

统一格式：%(asctime)s [%(levelname)s] %(message)s

示例输出：

2026-02-13 21:36:07 [INFO] 物料校验标签页已就绪
2026-02-13 21:36:08 [WARNING] 未选择任何负责人
2026-02-13 21:36:09 [ERROR] 校验过程中发生错误

使用方式

在新代码中使用

from gui.log_config import get_logger

# 获取 logger
logger = get_logger(__name__)

# 输出日志
logger.info("信息日志")
logger.warning("警告日志")
logger.error("错误日志")

在现有代码中使用 _update_log

保持兼容，_update_log 方法自动桥接到 logging：

self._update_log("消息", "INFO")     # → logger.info()
self._update_log("消息", "WARNING")  # → logger.warning()
self._update_log("消息", "ERROR")    # → logger.error()
self._update_log("消息", "SUCCESS")  # → logger.info() (UI 显示为 SUCCESS)

测试验证

运行简单测试

python tests/test_logging_simple.py

运行完整 GUI 测试

python tests/test_logging_system.py

优势

1. 统一风格：控制台和 UI 使用相同格式，便于调试
2. 标准化：使用 Python 标准 logging 模块，符合最佳实践
3. 易扩展：后续可轻松添加文件输出、远程日志等
4. 代码简化：减少重复的 _update_log 方法实现
5. 线程安全：logging 模块内置线程安全支持，GuiTextHandler 额外处理了 GUI 线程安全

兼容性

• 保持向后兼容：_update_log 方法仍然可用
• SUCCESS 级别：映射到 INFO，但 UI 中仍显示为绿色 SUCCESS
• DEBUG 级别：默认不显示，可通过配置启用

后续改进建议

1. 文件输出：添加 FileHandler 将日志保存到文件
2. 日志轮转：使用 RotatingFileHandler 或 TimedRotatingFileHandler
3. 配置化：通过配置文件控制日志级别和输出目标
4. 远程日志：添加 SyslogHandler 或自定义网络 Handler
5. 性能监控：集成性能指标到日志系统

文件清单

新增文件

• gui/log_config.py - 日志配置模块
• gui/widgets/log_handler.py - GUI 日志处理器
• tests/test_logging_simple.py - 简单测试脚本
• tests/test_logging_system.py - 完整测试脚本
• docs/LOGGING_REFACTORING_SUMMARY.md - 本文档

修改文件

• gui/main_window.py - 初始化日志系统
• gui/material_validation_tab.py - 使用统一日志
• gui/data_extraction_tab.py - 使用统一日志
• gui/widgets/__init__.py - 导出 GuiTextHandler