feat: implement unified logging system for GUI components

Add centralized logging mechanism that simultaneously outputs to console
and GUI log components, improving code maintainability and consistency.

Changes:
- Add gui/log_config.py for centralized logging configuration
- Add gui/widgets/log_handler.py as bridge between logging and LogText
- Integrate unified logging into DataExtractionTab and MaterialValidationTab
- Initialize logging system in MainWindow on startup
- Improve error messages in material_status_validator for empty results
- Add documentation for logging mechanism and refactoring

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Misaka
2026-02-24 20:31:59 +08:00
parent 3c45ef58d1
commit 24053c6a3b
9 changed files with 821 additions and 24 deletions

View File

@@ -0,0 +1,141 @@
# 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] 校验过程中发生错误
```
## 使用方式
### 在新代码中使用
```python
from gui.log_config import get_logger
# 获取 logger
logger = get_logger(__name__)
# 输出日志
logger.info("信息日志")
logger.warning("警告日志")
logger.error("错误日志")
```
### 在现有代码中使用 `_update_log`
保持兼容,`_update_log` 方法自动桥接到 logging
```python
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)
```
## 测试验证
### 运行简单测试
```bash
python tests/test_logging_simple.py
```
### 运行完整 GUI 测试
```bash
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