DOC

Документация

Введение в SOBERIS

SOBERIS — это система управления базами данных с динамической валидацией по JSON-схемам, с автоматической генерацией REST спецификаций, с функционалом транзакций, с функционалом Foreign Key, с функционалом валидации по справочным значениям, с мониторингом в реальном времени и комплексным логированием. Система предназначена для бизнес-процессов, требующих строгой валидации документных структур данных, централизованного управления схемами валидации и детального аудита операций с данными с высокой надежностью, производительностью и масштабируемостью.

Назначение системы

Управление схемами данных - создание, валидация и версионирование JSON-схем для документов и справочников
OpenAPI/Swagger спецификации - автоматическая генерация спецификации CRUD-операций на основе JSON-схемы коллекции
Операции с документами - полный CRUD функционал с автоматической валидацией по схемам
Транзакционность - поддержка многодокументных транзакций MongoDB с управлением таймаутами
Мониторинг системы - отслеживание состояния здоровья, метрик транзакций и статуса кластера
Безопасность данных - аутентификация через Keycloak, ролевая модель доступа (RBAC)

Функциональные возможности

Backend возможности

Динамическое создание и управление JSON-схемами
CRUD операции с валидацией документов
Транзакционное управление MongoDB
Кэширование схем и транзакций в Redis
Автоматическое создание индексов БД
RESTful API с генерируемыми OpenAPI/Swagger спецификациями
Мониторинг и метрики системы
Логирование событий, сервисов и сервера
API ключи для внешних интеграций
Асинхронная обработка задач

Frontend возможности

Конструктор схем документов и справочников
Дашборд мониторинга в реальном времени
Просмотр и управление логами с TTL
Администрирование глобального и транзакционного кэша
Управление индексами базы данных
Интегрированная API документация (Swagger UI)
Управление API ключами
Статус кластера и здоровье системы
Импорт/экспорт схем
Ролевая защита маршрутов

Архитектура и компоненты

Общая архитектура

Backend архитектура

Контроллеры

DataController- операции с документами
SchemaController- управление схемами
CacheController- управление кэшем
IndexController- управление индексами
ApiKeyController- управление API ключами

Сервисы

DataService - бизнес-логика документов
TransactionService - управление транзакциями
SchemaService - обработка схем
MetricsService - сбор метрик
ApiTokenValidationService - валидация API токенов

Frontend архитектура

Компоненты

SchemeBuilder - конструктор схем
Header - навигация
MonitoringSidebar - боковая панель мониторинга
ProtectedRoute - защищенные маршруты
Модальные окна для уведомлений

Сервисы

DataService- бизнес-логика документов
TransactionService- управление транзакциями
SchemaService- обработка схем
MetricsService- сбор метрик
ApiTokenValidationService- валидация API токенов

Интеграции и взаимодействие

API Endpoints

Основные API группы

/sbrs-schema/* - управление схемами
/sbrs-data/* - операции с документами
/sbrs-cache/* - управление кэшем
/sbrs-index/* - управление индексами
/sbrs-log/* - работа с логами
/sbrs-keys/* - управление API ключами
/sbrs-metric/* - системные метрики

Стандартные заголовки

SBRS-Correlation-Id - идентификатор корреляции
SBRS-Originator - источник запроса
SBRS-Message-Id - ID сообщения
SBRS-Transaction-Id - ID транзакции
SBRS-Schema-Name - название схемы
Authorization- Bearer токен

Документация API

Система автоматически генерирует OpenAPI/Swagger документацию, доступную по следующим адресам:

Backend Swagger UI: http://localhost:8588/swagger-ui.html
OpenAPI Spec: http://localhost:8588/v3/api-docs
Frontend Specification: http://localhost:3001/specification

Безопасность

Аутентификация и авторизация

Механизмы аутентификации

Keycloak SSO - централизованная аутентификация
OAuth2/OpenID Connect - стандарт протокола
JWT токены - статeless аутентификация
API ключи - для внешних интеграций
Управление сессиями - автоматическое обновление токенов

Ролевая модель (RBAC)

upload_schema - загрузка схем
update_schema - обновление схем
read_metrics - чтение метрик
clear_cache - очистка кэша
api_keys_management - управление API ключами
update_log_ttl - управление TTL логов

Защита данных

Уровень приложения

Валидация и санитизация входных данных
Предотвращение SQL/NoSQL инъекций
XSS защита
CORS политики
Защита от CSRF атак

Уровень транспорта

SSL/TLS шифрование
Безопасные заголовки HTTP
Ограничение доступа по IP
Rate limiting
Аудит и логирование доступа

Управление и сопровождение

Мониторинг и метрики

Доступные метрики

Использование CPU и памяти
Статус подключений к БД
Производительность Redis кэша
Здоровье кластера MongoDB
Статистика HTTP запросов

Бизнес метрики

Количество и длительность транзакций
Статистика операций со схемами
Производительность API endpoints
Активность пользователей
Статистика ошибок и исключений

Логирование

Система логирования
Event Logs - Логи бизнес-событий и пользовательских действий
Service Logs - Логи внутренних сервисов и компонентов системы
Server Logs - Системные логи сервера и инфраструктуры
Возможности управления логами

Настройка TTL (время жизни) для каждого типа логов
Поиск и фильтрация по различным критериям
Экспорт логов в различных форматах
Уровни логирования: ERROR, WARN, INFO, DEBUG

Развертывание и масштабирование

Варианты развертывания
Docker Compose: docker-compose up --build -d docker-compose scale backend=3 -d docker-compose logs -f
Kubernetes: kubectl apply -f k8s/ kubectl get pods kubectl logs -f deployment/sbrs-backend