Схема справочника

Схемы справочников определяют структуру данных для хранения каталожной информации в системе SOBERIS. Конструктор схем справочников предоставляет специализированный интерфейс для создания структур каталогов с ограниченным набором типов данных и фокусом на производительности поиска.
Доступ к конструктору схем справочников

Конструктор схем справочников доступен по адресу /create/directory-scheme для создания новых схем или /update/directory-scheme/:versionId для редактирования существующих.
🔗 Навигация к конструктору
  • Со страницы схем: кнопка "Создать схему справочника"
  • Из редактирования: кнопка "Редактировать" для выбранной схемы справочника
  • Прямой доступ по URL с указанием versionId для редактирования
Отличия от схем документов
Схемы документов
  • Полный набор типов данных
  • Поддержка Foreign Key связей
  • Комплексные вложенные структуры
  • Все типы индексов MongoDB
  • Гибкая валидация данных
Схемы справочников
  • Ограниченный набор базовых типов
  • Только плоские структуры
  • Оптимизация для быстрого поиска
  • Упрощенная индексация (автоматическая установка Wildcard)
  • Фокус на читаемость и производительность
Интерфейс конструктора

Заголовок и панель инструментов

В верхней части конструктора расположены те же элементы управления, что и для схем документов:
Основная рабочая область

Интерфейс схем справочников использует ту же компоновку, но с ограниченной функциональностью:
Конструктор схемы (левая панель)
  • Плоская структура без вложенности
  • Простые поля только корневого уровня
  • Ограниченный набор типов данных
  • Кнопки добавления и удаления свойств
  • Индикаторы обязательных полей
Панель деталей (правая панель)
  • Упрощенные настройки свойств
  • Базовые ограничения валидации
  • Описание и примеры
  • Простая индексация (Wildcard-индекс)
  • Предварительный просмотр схемы
Типы данных для справочников

Поддерживаемые типы

Схемы справочников поддерживают только базовые типы данных для обеспечения производительности:
⚠️ Ограничения типов для справочников
  • НЕ поддерживается: object, array - для поддержания плоской структуры
  • НЕ поддерживается: document FK, directory FK - избегание циклических зависимостей
  • Конфигурируется: список доступных типов через VITE_DIRECTORY_SCHEMA_TYPES
  • По умолчанию: string, number, integer, boolean
Конфигурация типов данных

Доступные типы данных настраиваются через переменные окружения:
# Frontend конфигурация
VITE_DIRECTORY_SCHEMA_TYPES=string,number,integer,boolean

# Backend конфигурация  
app.schema-validator.types.directory-allowed-types=string,number,integer,boolean

# Валидация включена по умолчанию
VITE_DIRECTORY_SCHEMA_ENABLE_VALIDATION=true
Работа с конструктором справочников

Создание базовой структуры
1. Задайте название схемы справочника в корневом элементе
2. Добавьте описание схемы в текстовом поле
3. Нажмите "+" для добавления нового свойства на корневом уровне
4. Выберите один из доступных базовых типов данных
5. Настройте ограничения в правой панели
🚫 Ограничения структуры справочников
  • Только плоская структура - нельзя создавать вложенные объекты
  • Нет массивов - для простоты и производительности
  • Нет Foreign Key - избегание зависимостей между справочниками
  • Максимум один уровень - все свойства только на корневом уровне
Добавление свойств справочника

Все свойства справочника добавляются только на корневом уровне:
  • Корневой уровень - единственное место для создания свойств
  • Простые типы - только базовые типы данных
  • Прямое именование - имена свойств напрямую используются в запросах

Настройка ограничений для справочников

В правой панели доступны упрощенные ограничения:
Индексация в справочниках

Справочники поддерживают упрощенную систему индексации:
Wildcard Index
Индекс устанавливается автоматически на все поля справочника.
Валидация и ограничения справочников

Специфичные проверки

Для схем справочников действуют дополнительные ограничения:
🚫 Блокирующие ошибки для справочников
  • Неподдерживаемые типы - использование object, array или FK типов
  • Вложенные структуры - попытка создания properties в объектах
  • Пустые имена - все свойства должны иметь непустые имена
  • Дублирующиеся имена - имена свойств должны быть уникальными
  • Некорректные символы - только латинские символы в именах
Backend валидация

Backend дополнительно проверяет соответствие схемы требованиям справочников:
app.schema-validator.types.directory-allowed-types=string,number,integer,boolean

Проверки на сервере:
• Соответствие типов данных списку разрешенных
• Отсутствие вложенных объектов и массивов  
• Отсутствие FK связей
• Валидность индекса
Примеры схем справочников

Справочник отделов
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "title": "Department",
  "description": "Справочник отделов компании",
  "properties": {
    "id": {
      "type": "string",
      "description": "Уникальный идентификатор отдела",
      "x-index": "single_field"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Название отдела",
      "x-index": "text"
    },
    "code": {
      "type": "string",
      "pattern": "^[A-Z]{2,10}$",
      "description": "Код отдела",
      "x-index": "single_field"
    },
    "active": {
      "type": "boolean",
      "description": "Активность отдела",
      "x-index": "single_field"
    },
    "order": {
      "type": "integer",
      "minimum": 0,
      "description": "Порядок сортировки"
    }
  },
  "required": ["id", "name", "code"],
  "additionalProperties": false
}
Справочник статусов

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "title": "Status",
  "description": "Справочник статусов документов",
  "properties": {
    "id": {
      "type": "string",
      "description": "Идентификатор статуса",
      "x-index": "single_field"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 50,
      "description": "Название статуса",
      "x-index": "text"
    },
    "category": {
      "type": "string",
      "enum": ["draft", "review", "approved", "archived"],
      "description": "Категория статуса",
      "x-index": "single_field"
    },
    "priority": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "Приоритет статуса"
    },
    "final": {
      "type": "boolean",
      "description": "Финальный статус",
      "x-index": "single_field"
    }
  },
  "required": ["id", "name", "category"],
  "additionalProperties": false
}
Справочник валют

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "title": "Currency",
  "description": "Справочник валют",
  "properties": {
    "code": {
      "type": "string",
      "pattern": "^[A-Z]{3}$",
      "description": "ISO код валюты",
      "x-index": "single_field"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Название валюты",
      "x-index": "text"
    },
    "symbol": {
      "type": "string",
      "maxLength": 5,
      "description": "Символ валюты"
    },
    "rate": {
      "type": "number",
      "minimum": 0,
      "description": "Курс к базовой валюте"
    },
    "precision": {
      "type": "integer",
      "minimum": 0,
      "maximum": 4,
      "description": "Количество знаков после запятой"
    },
    "active": {
      "type": "boolean",
      "description": "Активность валюты",
      "x-index": "single_field"
    }
  },
  "required": ["code", "name", "rate", "precision"],
  "additionalProperties": false
}
Использование справочников

Связи с документами

Справочники используются в схемах документов через Directory FK:
// В схеме документа Employee
"departmentId": {
  "type": "string",
  "x-directory-collection": "departments",
  "x-directory-param": "id",
  "description": "Ссылка на справочник отделов"
}

// Поиск по названию отдела
"departmentName": {
  "type": "string", 
  "x-directory-collection": "departments",
  "x-directory-param": "name",
  "description": "Поиск по названию отдела"
}
API для работы со справочниками

Специальные методы для получения свойств справочников:
POST /sbrs-schema/get-directory-property
Content-Type: application/json
SBRS-Correlation-Id: unique-id
SBRS-Originator: client-name  
SBRS-Message-Id: message-id

{
  "collectionName": "departments"
}

Response:
{
  "id": "string",
  "name": "string", 
  "code": "string"
}
Лучшие практики для справочников

Проектирование структуры
✅ Рекомендации
  • Простота структуры: используйте только необходимые поля
  • Уникальные идентификаторы: всегда включайте поле id или code
  • Читаемые имена: добавляйте поле name для отображения
Производительность
Оптимизация справочников:
1. Используйте enum для ограниченных наборов значений
2. Минимизируйте количество полей
3. Применяйте ограничения длины для строковых полей
Версионирование справочников
📋 Стратегия обновлений
  • Обратная совместимость: не удаляйте существующие поля
  • Новые поля: добавляйте как необязательные
  • Значения enum: добавляйте новые, не удаляйте старые
  • Тестирование: проверяйте влияние на связанные документы
  • Документация: описывайте изменения в поле description
Обработка ошибок справочников

Типичные ошибки

Специфичные ошибки при работе со схемами справочников:
Частые проблемы
  • Неподдерживаемый тип данных - использование object или array
  • Попытка создания вложенности - добавление object к объекту
  • Foreign Key в справочнике - использование x-document-collection
Интеграция с документами

Использование Directory FK

Справочники связываются с документами через специальные поля:
// В схеме документа Order
"status": {
  "type": "string",
  "x-directory-collection": "statuses",
  "x-directory-param": "id",
  "description": "ID статуса из справочника"
}

"statusName": {
  "type": "string", 
  "x-directory-collection": "statuses",
  "x-directory-param": "name",
  "description": "Название статуса для отображения"
}
Автодополнение в формах

API для получения данных справочников для автодополнения:
// Получение доступных параметров справочника
GET /sbrs-schema/get-directory-property
{
  "collectionName": "departments"
}

// Ответ содержит список доступных полей:
{
  "id": "string",
  "name": "string",
  "code": "string",
  "active": "boolean"
}
💡 Практические советы
  • Создавайте справочники перед схемами документов, которые на них ссылаются
  • Используйте говорящие имена коллекций: departments, statuses, currencies