# Quantum Backend

Бэкенд-сервис распределенной системы для расчета энергии основного состояния молекул с помощью квантовых алгоритмов (VQE).

## 📋 Описание

Quantum Backend — это центральный микросервис, отвечающий за:

- Управление командами и правами доступа пользователей
- Регистрацию и управление вычислительными системами
- Создание и управление экспериментами
- Распределение задач через брокер сообщений RabbitMQ
- Отслеживание статуса вычислительных систем через механизм heartbeat
- Отказоустойчивое восстановление вычислений

## 🏗 Архитектура

Сервис построен на следующих технологиях:

| Компонент | Технология |
|-----------|------------|
| Web-фреймворк | FastAPI |
| ORM | SQLAlchemy 2.0 (async) |
| База данных | PostgreSQL (asyncpg) |
| Кеширование | Redis + FastAPI Cache |
| Брокер сообщений | RabbitMQ (aio-pika) |
| Аутентификация | Keycloak (python-keycloak) |
| Хранилище файлов | MinIO |

## 🚀 Запуск

### Требования

- Docker & Docker Compose v2
- Python 3.11+ (для локальной разработки)

## ⚙️ Переменные окружения

| Переменная | Описание |
|------------|----------|
| `KEYCLOAK_URL` | URL сервера Keycloak |
| `KEYCLOAK_REALM` | Realm Keycloak |
| `KEYCLOAK_CLIENT_ID` | Client ID |
| `KEYCLOAK_CLIENT_SECRET` | Client Secret |
| `RABBITMQ_HOST` | Хост RabbitMQ |
| `RABBITMQ_USER` | Пользователь RabbitMQ |
| `RABBITMQ_PASSWORD` | Пароль RabbitMQ |

### Docker Compose

```bash
# Клонирование репозитория
git clone https://git.deowl.ru/vkrb/quantum_backend.git
cd quantum_backend

# Запуск всех сервисов
docker compose up -d
```

### Локальная разработка

```bash
# Создание виртуального окружения
python -m venv venv
source venv/bin/activate  # Linux/Mac
# или
venv\Scripts\activate  # Windows

# Запуск сервера
uvicorn src.app:app --reload --host 0.0.0.0 --port 8000
```

## 📁 Структура проекта

```
src/
├── api_endpoint/          # HTTP-эндпоинты
│   ├── experiment_api.py  # Работа с экспериментами
│   ├── machine_api.py     # Управление вычислительными системами
│   ├── teams_api.py       # Управление командами
│   ├── user_api.py        # Профили пользователей
│   └── health_api.py      # Health check
├── config/
│   ├── database_config.py      # Настройки подключения к PostgreSQL
│   ├── keycloak_config.py      # Конфигурация аутентификации Keycloak
│   ├── logging_config.py       # Настройки логирования
│   ├── minio_config.py         # Конфигурация MinIO (файловое хранилище)
│   ├── rabbitmq_config.py      # Менеджер подключения к RabbitMQ
│   └── seeding.py              # Начальные данные (permissions, статусы)
├── connections/           # Подключения к внешним сервисам
│   ├── db.py              # PostgreSQL
│   ├── rabbitmq.py        # RabbitMQ (heartbeat, задачи, прогресс)
│   ├── keycloak.py        # Аутентификация
│   └── minio.py           # Файловое хранилище
├── crud/                  # Операции с БД
│   ├── experiment_crud.py
│   ├── machine_crud.py
│   ├── team_crud.py
│   └── user_crud.py
├── sql_models/            # SQLAlchemy модели
│   └── models.py
├── rest_models/           # Pydantic схемы
└── app.py                 # Точка входа
```

## 🔌 API Endpoints

Сервис предоставляет следующие группы эндпоинтов:

| Префикс | Описание |
|---------|----------|
| `/health` | Проверка работоспособности |
| `/user` | Управление профилем пользователя |
| `/team` | Управление командами и участниками |
| `/machine` | Управление вычислительными системами |
| `/experiment` | Управление экспериментами и задачами |

Подробная документация API доступна после запуска по адресу:  
`http://localhost:8000/docs`


## 🔄 RabbitMQ Интеграция

Сервис использует RabbitMQ для трех основных задач:

### 1. Heartbeat мониторинг (fanout exchange `heartbeat`)
- Вычислительные системы каждые 5 секунд отправляют статус
- Сервер отслеживает активность через Redis sorted set
- При timeout > 30 секунд система помечается как OFFLINE

### 2. Распределение задач (topic exchange `team_{id}`)
- При запуске эксперимента задачи публикуются в очереди по кол-ву кубит
- Routing key: `qubits.{N}`
- Вычислительные системы подписываются на соответствующие очереди

### 3. Отчеты о прогрессе (direct exchange `progress_report`)
- Вычислительные системы отправляют промежуточные результаты
- Headers: `task_id`, `status`, `system_id`
- Обновление статуса задачи в БД

## 🗄 База данных

Основные сущности:

| Таблица | Описание |
|---------|----------|
| `users` | Пользователи (keycloak_id) |
| `teams` | Команды исследователей |
| `team_members` | Участники команд с правами |
| `permissions` | Доступные права |
| `computational_systems` | Вычислительные системы |
| `team_systems` | Доступ ВС к командам |
| `experiments` | Эксперименты |
| `experiment_types` | Типы экспериментов (модульные) |
| `instances` | Задачи (молекулы) |
| `simulation_results` | Результаты вычислений |
| `simulation_statuses` | Статусы задач |

## 🔐 Аутентификация

Сервис использует Keycloak для аутентификации:

- JWT токены, передаваемые в заголовке `Authorization: Bearer <token>`
- Автоматическое создание пользователя в локальной БД при первом входе
- Проверка прав через механизм `check_team_permission`