added readme

2026-05-26 11:45:13 +03:00
parent 94bd0cda31
commit 5571448e57
1 changed files with 165 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,165 @@
+# 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`