DIRECTORY

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

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

Схемы справочников определяют структуру данных для хранения каталожной информации в системе 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