COMMON_INTEGRATION_GUIDE.md

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

## 📋 Обзор

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

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

### 1. **Централизованное управление исключениями**
```python
from common import AudioFileException, ValidationException

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

### 2. **Единые константы и настройки**
```python
from common import UIColors, Messages, AudioFormats

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

### 3. **Централизованное логирование**
```python
from common import configure_logging, get_logger

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

### 4. **Типизированные модели данных**
```python
from common import PipelineResult, PatientMetadata

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

### 5. **Валидация данных**
```python
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`

**Изменения:**
```python
# Заменить
import logging
logger = logging.getLogger(__name__)

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

**В точках входа (run_gui.py, app/main.py):**
```python
from common import configure_logging

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

### Этап 2: Исключения (Приоритет: Средний)
**Файлы для изменения:**
- `stt/audio_processor.py`
- `corrector/llm_corrector.py`
- `pipeline/medical_pipeline.py`

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

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

### Этап 3: Константы UI (Приоритет: Средний)
**Файлы для изменения:**
- `app/gui_app.py`

**Изменения:**
```python
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` (валидация путей)

**Изменения:**
```python
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`

**Изменения:**
```python
from common import PipelineResult, PatientMetadata

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

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

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

1. **Шаг 1**: Обновите `run_gui.py`:
```python
#!/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:
```python
# Было:
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](APP_ARCHITECTURE.md) - Архитектура приложения
- [common/__init__.py](common/__init__.py) - Экспорты модуля
- [FILES_REFACTORED.md](FILES_REFACTORED.md) - Документация по рефакторингу

---

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