Первые шаги с SOBERIS

Данное руководство поможет вам пошагово настроить систему SOBERIS для работы с вашими данными. Мы последовательно создадим схему справочника, схему документа с внешними связями, настроим API-ключ и протестируем работу системы через OpenAPI Specification.
Backend (Spring Boot 3.5.3)
  • Java 21
  • MongoDB (Spring Data)
  • Redis для кэширования
  • Spring Security + OAuth2
  • JSON Schema Validator
  • Spring Boot Actuator
Frontend (React 18 + Vite)
  • TypeScript
  • React Router DOM 7.6.2
  • Keycloak для аутентификации
  • Bootstrap 5.3.6
  • Swagger UI React
Шаг 1. Создание схемы справочника

Начнем с создания схемы справочника, которая будет содержать каталожные данные для последующего использования в качестве внешних ключей в документах.
1.1. Переход к конструктору схем справочников
# Навигация:
URL: /create/directory-scheme

# Альтернативные пути:
• Главное меню → Схемы → Создать схему справочника
• Страница схем (/schemes) → кнопка "Создать схему справочника"
1.2. Настройка базовых параметров схемы
# Название схемы:
Пример: "Categories"
Требования: только латинские символы, от 3 до 100 символов

# Описание:
"Справочник категорий товаров"
1.3. Добавление полей справочника
# Справочники поддерживают ограниченный набор типов данных для оптимизации производительности:

# Доступные типы:
• string - текстовые данные
• number - числа с плавающей точкой
• integer - целые числа
• boolean - логические значения

# Пример полей:
• id: integer (обязательное) 
• name: string (обязательное) 
• code: string 
• active: boolean
1.4. Сохранение схемы справочника
# Действие:
Кнопка "Сохранить схему" → Подтверждение создания

# Результат:
• Схема сохранена в системе
• Присвоен уникальный versionId
• Доступна для использования в схемах документов
• Отображается в списке схем (/schemes)
Шаг 2: Создание схемы документа с внешними связями

Теперь создадим схему документа, которая будет содержать ссылки на созданный справочник и другие документы. Эта схема будет использоваться для валидации данных, поступающих через API.
2.1. Переход к конструктору схем документов
# Навигация:
URL: /create/document-scheme
2.2. Настройка базовых параметров документа
# Название схемы:
Пример: "Products"

# Описание:
"Схема документов товаров с внешними связями"
2.3. Добавление полей с внешними связями
# Документы поддерживают расширенный набор типов данных, включая внешние ключи:

# Базовые типы:
• string, number, integer, boolean
• object - вложенные объекты
• array - массивы данных

# Типы внешних ключей:
• document FK - ссылка на другой документ
• directory FK - ссылка на справочник

# Пример схемы с внешними связями:
• id: string (обязательное) 
• name: string (обязательное) 
• description: string 
• price: number 
• categoryId: directory FK → Categories 
• parentProductId: document FK → Products 
• specifications: object 
• tags: array 
• active: boolean
2.4. Настройка внешних ключей
# Для directory FK (categoryId):
1. Выбираем тип "directory FK" 
2. Указываем целевую схему справочника: "Categories" 
3. Устанавливаем обязательность поля при необходимости

# Для document FK (parentProductId):
1. Выбираем тип "document FK" 
2. Указываем целевую схему документа: "Products" 
3. Настраиваем как необязательное поле (для корневых товаров)
Шаг 3: Создание API-ключа

Для доступа к API системы SOBERIS необходимо создать API-ключ с настройкой разрешений для конкретных эндпоинтов.
3.1. Переход к управлению API-ключами
# Навигация:
URL: /monitoring/api-keys

# Альтернативные пути:
• Главное меню → Мониторинг → API Keys
• Боковая панель мониторинга → API Keys
3.2. Заполнение формы создания API-ключа
# Название ключа:
Пример: "ProductsAPI" 
Требования: 3-100 символов, только латинские символы

# Владелец ключа:
Пример: "Development Team" 
Требования: 3-100 символов, только латинские символы
3.3. Выбор разрешений для эндпоинтов
# Доступные эндпоинты для API-ключа:

# Транзакционные операции:
• start-transaction - начало транзакции
• finish-transaction - завершение транзакции

# CRUD операции:
• insert-one - добавление записи
• update-one - обновление записи
• delete-one - удаление записи
• search - поиск записей

# Рекомендуемый набор для тестирования:
✓ start-transaction 
✓ finish-transaction 
✓ insert-one
✓ update-one 
✓ search
3.4. Создание и сохранение API-ключа
# Создание ключа:
Кнопка "Создать ключ" → Генерация уникального API-ключа

# Важно:
⚠️ Сохраните сгенерированный API-ключ в безопасном месте. После закрытия окна его нельзя будет повторно просмотреть.

# Формат ключа:
Пример: sbrs_api_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p
Шаг 4: Тестирование запросов через Specification

Завершающий этап - тестирование созданных схем и API-ключа через интерфейс OpenAPI Specification.
4.1. Переход к странице спецификации
# Навигация:
URL: /specification/

# Выбор схемы:
Products
4.2. Настройка аутентификации
# Авторизация в Swagger UI:
1. Нажать кнопку "Authorize" в интерфейсе Swagger 
2. В поле "Value" ввести созданный API-ключ 
3. Нажать "Authorize" для подтверждения

# Заголовок аутентификации:
SBRS-API-Key: sbrs_api_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p
4.3. Тестирование создания записи в справочнике
# Эндпоинт:
POST /sbrs-data/insert-one

# Пример тела запроса: {
    "id": 1,
    "name": "Electronics",
    "code": "ELEC",
    "active": true
}

# Ожидаемый ответ:
HTTP 201 Created
{
    "success": true,
    "insertedId": "Categories_1",
    "message": "Record inserted successfully"
}
4.4. Тестирование создания документа с внешними ключами
# Эндпоинт:
POST /sbrs-data/insert-one

# Пример тела запроса: {
    "id": "prod-001",
    "name": "Smartphone X1",
    "description": "Latest smartphone model",
    "price": 599.99,
    "categoryId": 1,
    "specifications": {
        "memory": "128GB",
        "display": "6.1 inch"
    },
    "tags": [
        "mobile",
        "electronics",
        "new"
    ],
    "active": true
}

# Валидация внешних ключей:
• categoryId: 1 проверяется на существование в справочнике Categories
• parentProductId: опущен, так как это корневой товар
• Система автоматически проверит целостность ссылок
4.5. Тестирование поиска с фильтрацией
# Эндпоинт:
POST /sbrs-data/search

# Пример поискового запроса: {
    "filters": {
        "categoryId": 1,
        "active": true,
        "price": {
            "$gte": 500,
            "$lte": 1000
        }
    },
    "sort": {
        "price": 1
    },
    "limit": 10,
    "skip": 0
}

# Ожидаемый ответ: {
    "success": true,
    "data": [
        {
            "id": "prod-001",
            "name": "Smartphone X1",
            "price": 599.99,
            "categoryId": 1,
...
        }
    ],
    "totalCount": 1,
    "limit": 10,
    "skip": 0
}
4.6. Работа с транзакциями
# Начало транзакции:
POST /sbrs-data/Products/start-transaction

# Ответ:
{
"success": true,
"transactionId": "tx_1642781234567",
"message": "Transaction started"
}

# Выполнение операций в транзакции:
Все последующие операции: 
- insert-one, 
- update-one, 
- delete-one 
используют transactionId в заголовке: 
X-Transaction-Id: 8c2233c1-eb1a-4ff6-b7f8-f71e3cb5198c

# Завершение транзакции:
POST /sbrs-data/Products/finish-transaction
Headers: X-Transaction-Id: tx_1642781234567

{
"commit": true
}
Made on
Tilda