APP_ARCHITECTURE.md

# Medical Transcriber - GUI Application

## 📋 Архитектура приложения

```
Medical Transcriber
│
├── 🎨 GUI Layer (PyQt6)
│   └── app/gui_app.py           - Главное окно, вкладки, диалоги
│
├── 🔄 Pipeline Integration
│   ├── pipeline/medical_pipeline.py    - Оркестрация STT + KB + LLM
│   ├── pipeline/pipeline_config.py     - Конфигурация
│   │
│   ├── stt/whisper_transcriber.py      - Транскрибирование аудио
│   ├── knowledge_base/                 - База медицинских терминов
│   ├── corrector/                      - LLM коррекция
│   └── corrector/report_generator.py   - DOCX отчётность
│
├── 🧩 Common Utilities (готово к интеграции)
│   ├── common/exceptions.py            - Кастомные исключения
│   ├── common/constants.py             - Константы приложения
│   ├── common/logger.py                - Централизованное логирование
│   ├── common/models.py                - Модели данных
│   └── common/validators.py            - Валидация данных
│
├── 🚀 Entry Points
│   ├── run_gui.py                      - Запуск GUI
│   ├── app/main.py                     - CLI для полного пайплайна (transmed)
│   ├── build_exe.py                    - Сборка Windows .exe
│   └── build_windows.spec              - PyInstaller конфигурация
│
└── 📚 Documentation
    ├── USER_GUIDE.md                   - Руководство пользователя
    ├── BUILD_EXE.md                    - Инструкции по сборке
    └── README.md                       - Общая информация
```

## 🎯 Основные компоненты GUI

### 1. **Главное окно (MedicalTranscriptionApp)**
   - Приложение на PyQt6
   - Две основные вкладки
   - Кроссплатформенное (Windows, Linux, macOS)

### 2. **Вкладка "Транскрибирование"**
   - Выбор аудиофайла
   - Ввод данных пациента (диалог)
   - Опции обработки (чекбоксы)
   - Прогресс-бар
   - Вывод результатов

### 3. **Вкладка "Настройки"**
   - Параметры Whisper (модель, устройство, тип данных)
   - OpenRouter API ключ
   - Путь к базе медицинских терминов

### 4. **Многопоточность (Worker/QThread)**
   - Длительные операции не блокируют UI
   - Сигналы для обновления прогресса
   - Обработка ошибок

## 🔌 Интеграция с пайплайном

### Поток обработки:

```
┌─────────────────────┐
│  Выбор аудиофайла   │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────────┐
│  Заполнение данных      │
│  пациента               │
└──────────┬──────────────┘
           │
           ▼
┌──────────────────────────────┐
│  TranscriptionWorker (QThread)│
│  ┌──────────────────────────┐ │
│  │ 1. STT (Whisper)         │ │
│  │ ▼                        │ │
│  │ 2. Knowledge Base Check  │ │
│  │ ▼                        │ │
│  │ 3. LLM Correction        │ │
│  │ ▼                        │ │
│  │ 4. Report Generation     │ │
│  └──────────────────────────┘ │
└──────────┬──────────────────┘
           │
           ▼
┌────────────────────────────┐
│  Результаты и сохранение   │
│  JSON + DOCX               │
└────────────────────────────┘
```

## 🔄 Использование TranscriptionWorker

```python
# Создание воркера
worker = TranscriptionWorker(
    audio_path="path/to/audio.wav",
    config=PipelineConfig(...),
    patient_data={
        "patient_name": "ФИО",
        "patient_dob": "дата",
        ...
    }
)

# Подключение сигналов
worker.signals.progress.connect(callback_progress)
worker.signals.finished.connect(callback_finished)
worker.signals.error.connect(callback_error)

# Запуск
worker.start()
```

## 📊 Структура результатов

### Возвращаемый словарь `process()`:

```python
{
    "timestamp": "2026-01-16T12:05:30",
    "audio_file": "path/to/audio.wav",
    "status": "success",
    "transcription_original": "...",
    "transcription_corrected": "...",
    "corrections": [...],
    "report_path": "path/to/report.docx",
    "pipeline_steps": [
        {
            "step": "stt",
            "status": "success",
            "output_length": 5000
        },
        ...
    ]
}
```

## 🛠 Сборка Windows .exe

### Требования:
- Python 3.9+
- PyInstaller
- Все зависимости (requirements.txt)

### Команда:
```bash
python build_exe.py
```

### Результат:
```
dist/
└── MedicalTranscriber.exe  (~500 МБ - 1.5 ГБ)
```

## 🎨 Кастомизация UI

### Изменение стилей:

```python
# В методе apply_styles() в MedicalTranscriptionApp
style = """
    QMainWindow {
        background-color: #f5f5f5;
    }
    ...
"""
self.setStyleSheet(style)
```

### Добавление новых вкладок:

```python
# В методе init_ui()
new_tab = self.create_new_tab()
tabs.addTab(new_tab, "Новая вкладка")
```

## 📁 Файловая структура при использовании

```
Trans_for_doctors/
├── run_gui.py
├── medical_terms.txt
├── app_config.json              - Конфигурация приложения
├── whisper_model_config.json    - Конфигурация модели Whisper
├── model.safetensors
├── tokenizer_config.json
├── .env                         - API ключи (НЕ коммитится)
├── .env.example                 - Пример файла с ключами
│
├── results/
│   ├── result_20260116_120530.json
│   ├── result_20260116_120530_corrected.json
│   └── reports/
│       └── report_20260116_120530.docx
│
└── logs/
    └── transcription_20260116_120530.log
```

## 🧩 Модуль Common (интегрирован в код)

Проект включает модуль `common/` с утилитами, **теперь интегрированными во все модули**:

### Компоненты модуля:

1. **exceptions.py** - Кастомные исключения
   - `MedicalTranscriberException` - базовый класс
   - `AudioFileException`, `TranscriptionException`
   - `CorrectionException`, `ReportGenerationException`
   - `APIException`, `ValidationException`

2. **constants.py** - Централизованные константы
   - `UIColors`, `UIDimensions` - настройки интерфейса
   - `AudioFormats`, `ModelDefaults` - конфигурация
   - `Messages`, `Placeholders` - текстовые константы

3. **logger.py** - Логирование
   - `configure_logging()` - настройка логгера
   - `get_logger()` - получение логгера для модуля

4. **models.py** - Модели данных
   - `PipelineResult`, `PatientMetadata`
   - `TranscriptionResult`

5. **validators.py** - Валидация
   - Проверка аудиофайлов, API ключей
   - Валидация данных пациента

**Статус**: ✅ Модуль полностью интегрирован в app/gui_app.py, pipeline/medical_pipeline.py, corrector/llm_corrector.py, stt/whisper_transcriber.py

## 🔐 Сохранность данных

### Где сохраняются результаты:
1. **JSON файлы** - `results/` папка
   - Содержат текст транскрипции и коррекции
   - Сохраняются с временной меткой

2. **DOCX отчёты** - `results/reports/` папка  ✓ СОЗДАНА
   - Готовые к использованию документы
   - Названы по ФИО пациента или номеру исследования
   - Папка автоматически создаётся при инициализации

3. **Логи** - `logs/` папка
   - Полная информация о ходе обработки
   - Полезны для отладки ошибок

### Конфиденциальность:
- Все данные остаются на локальном компьютере
- API ключ передаётся через HTTPS (OpenRouter)
- Вы контролируете где сохраняются результаты

## 🚀 Запуск и отладка

### Запуск в консоли для отладки:
```bash
python run_gui.py
```
- Видны все логи в консоли
- Видны ошибки и предупреждения
- Легче найти проблемы

### Запуск скомпилированного .exe:
```bash
dist\MedicalTranscriber.exe
```
- Логи сохраняются в папку `logs/`
- Без консоли на экране

## 🔧 Возможные улучшения

1. **Пакетная обработка**
   - Обработка нескольких файлов за раз
   
2. **Шаблоны отчётов**
   - Кастомные DOCX шаблоны
   
3. **История операций**
   - Сохранение истории последних обработок
   
4. **Встроенный плеер**
   - Проигрывание аудио перед обработкой
   
5. **Темизирование**
   - Светлая/тёмная тема
   
6. **Синхронизация**
   - Облачное сохранение результатов

## 📞 Контакты и поддержка

Для вопросов или предложений:
- Проверьте логи в папке `logs/`
- Смотрите `USER_GUIDE.md` для типичных проблем
- Проверьте `BUILD_EXE.md` для проблем со сборкой

---

**Приложение готово к использованию!** ✨