COMMON_INTEGRATION_GUIDE.md

Руководство по интеграции модуля Common

📋 Обзор

Модуль common/ содержит общие утилиты для улучшения кода проекта. Он уже создан и документирован, но пока не интегрирован в основной код.

🎯 Преимущества интеграции

1. Централизованное управление исключениями

from common import AudioFileException, ValidationException

try:
    # код обработки аудио
except AudioFileException as e:
    logger.error(f"Ошибка аудиофайла: {e}")

2. Единые константы и настройки

from common import UIColors, Messages, AudioFormats

# Использование в GUI
button.setStyleSheet(f"background-color: {UIColors.PRIMARY}")
error_message = Messages.AUDIO_FILE_ERROR

3. Централизованное логирование

from common import configure_logging, get_logger

# В main.py или run_gui.py
configure_logging()
logger = get_logger(__name__)

4. Типизированные модели данных

from common import PipelineResult, PatientMetadata

result = PipelineResult(
    status="success",
    transcription="...",
    metadata=PatientMetadata(
        patient_name="ФИО",
        patient_dob="дата"
    )
)

5. Валидация данных

from common import Validator, ValidationException

try:
    Validator.validate_audio_file(audio_path)
    Validator.validate_api_key(api_key)
except ValidationException as e:
    # обработка ошибки

🔄 План поэтапной интеграции

Этап 1: Логирование (Приоритет: Высокий)

Файлы для изменения:

• app/gui_app.py
• pipeline/medical_pipeline.py
• corrector/llm_corrector.py
• stt/whisper_transcriber.py

Изменения:

# Заменить
import logging
logger = logging.getLogger(__name__)

# На
from common import get_logger
logger = get_logger(__name__)

В точках входа (run_gui.py, app/main.py):

from common import configure_logging

if __name__ == "__main__":
    configure_logging()
    # остальной код

Этап 2: Исключения (Приоритет: Средний)

Файлы для изменения:

• stt/audio_processor.py
• corrector/llm_corrector.py
• pipeline/medical_pipeline.py

Изменения:

# Заменить общие исключения
raise ValueError("Некорректный аудиофайл")

# На специфичные
from common import AudioFileException
raise AudioFileException("Некорректный аудиофайл")

Этап 3: Константы UI (Приоритет: Средний)

Файлы для изменения:

• app/gui_app.py

Изменения:

from common import UIColors, UIDimensions, Messages

# Использовать в apply_styles()
style = f"""
    QPushButton {{
        background-color: {UIColors.PRIMARY};
        min-height: {UIDimensions.BUTTON_HEIGHT}px;
    }}
"""

Этап 4: Валидация (Приоритет: Низкий)

Файлы для изменения:

• app/gui_app.py (валидация пользовательского ввода)
• pipeline/medical_pipeline.py (валидация путей)

Изменения:

from common import Validator, ValidationException

try:
    Validator.validate_audio_file(audio_path)
    Validator.validate_patient_data(patient_data)
except ValidationException as e:
    # показать ошибку пользователю

Этап 5: Модели данных (Приоритет: Низкий)

Файлы для изменения:

• pipeline/medical_pipeline.py

Изменения:

from common import PipelineResult, PatientMetadata

def process(...) -> PipelineResult:
    # использовать типизированные модели
    return PipelineResult(...)

🚀 Быстрый старт (минимальная интеграция)

Для быстрого улучшения проекта начните с логирования:

1. Шаг 1: Обновите run_gui.py:

#!/usr/bin/env python3
import sys
from pathlib import Path

project_root = Path(__file__).parent
if str(project_root) not in sys.path:
    sys.path.insert(0, str(project_root))

# Добавить централизованное логирование
from common import configure_logging

if __name__ == "__main__":
    configure_logging()  # Настроить логирование
    from app.gui_app import main
    main()

2. Шаг 2: В app/gui_app.py замените стандартный logger:

# Было:
import logging
logger = logging.getLogger(__name__)

# Стало:
from common import get_logger
logger = get_logger(__name__)

3. Шаг 3: Повторите для остальных файлов

📝 Проверка интеграции

После интеграции проверьте:

1. Логирование работает:

   • Логи появляются в папке logs/
   • Формат логов единообразный
   • Уровни логирования корректны

2. Исключения корректны:

   • Специфичные исключения вместо общих
   • Правильная обработка ошибок

3. UI консистентен:

   • Единые цвета и размеры
   • Единообразные сообщения

⚠️ Важные замечания

1. Обратная совместимость: Интеграция не ломает существующий код
2. Постепенность: Можно интегрировать по одному модулю
3. Тестирование: После каждого этапа проверяйте работоспособность
4. Документация: Обновляйте комментарии при изменениях

🔗 Связанные файлы

• APP_ARCHITECTURE.md - Архитектура приложения
• common/init.py - Экспорты модуля
• FILES_REFACTORED.md - Документация по рефакторингу

---

Статус модуля: ✅ Готов к интеграции Рекомендация: Начните с логирования (Этап 1), затем постепенно добавляйте остальные модули