Создание справочника

Справочник — это таблица однородных записей с фиксированной схемой полей. Прежде чем создавать его в системе, продумай: какие поля будут, какие обязательны, какие ссылаются на другие справочники.

Когда нужен новый справочник

Нужны однородные данные (>5 записей со схожей структурой)
Записи будут переиспользоваться: на них будут ссылаться другие справочники или внешние системы
Структура данных стабильна (поля меняются редко)

Если просто нужна пара значений «для себя» — лучше добавь поле-перечисление (enum) в существующий справочник, чем заводи отдельный.

Шаги

1. Открой каталог

В админ-панели — раздел «Справочники». Кнопка «Создать справочник» в правом верхнем углу.

2. Заполни основные поля

Имя (name) — машинное имя, латиница в snake_case (spacecraft, ground_station). По этому имени справочник будет доступен в API и других справочниках через FK.
Отображаемое имя — человеческое, как видит оператор («Космические аппараты», «Наземные станции»).
Версия схемы — 1.0.0, повышается при изменении схемы (см. schema drafts).
Bundle — к какому набору справочников относится (cuod по умолчанию).
Scope — PUBLIC / INTERNAL / RESTRICTED. Кто сможет читать.

3. Опиши схему полей

Схема справочника — это JSON Schema (стандарт описания структуры JSON-объектов). В редакторе (Monaco) задаёшь свойства записи.

Минимальный пример:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "x-id-source": "code",
  "required": ["code"],
  "properties": {
    "code": {
      "type": "string",
      "x-unique": true,
      "description": "Уникальный код"
    },
    "name": {
      "type": "object",
      "x-localized": true
    }
  }
}

Полезные аннотации

Аннотация	Что делает
`x-id-source: "code"`	Бизнес-ключ записи берётся из поля `code` (а не задаётся отдельно)
`x-unique: true`	Значение уникально по справочнику (например, нет двух записей с одинаковым `code`)
`x-localized: true`	Поле локализованное — хранит значения для каждого языка (`{ru: "Земля", en: "Earth"}`)
`x-references: "dict.field"`	Внешний ключ — ссылка на запись другого справочника
`description: "..."`	Подсказка для оператора, показывается в UI рядом с полем
`enum: ["A", "B"]`	Список допустимых значений
`format: "date"` / `"date-time"`	Календарный picker в форме

Пример со ссылкой на другой справочник

{
  "type": "string",
  "x-references": "satellite_type.code",
  "description": "Тип спутника"
}

При вводе оператор увидит выпадающий список типов из справочника satellite_type.

4. Опубликуй

После нажатия «Создать» справочник появляется в каталоге, схема блокируется (запись валидируется по ней). Чтобы изменить схему позже — создай schema draft и пройди ревью.

Что произойдёт автоматически

При создании справочника:

В БД появляется таблица записей с этой схемой
В REST API endpoint становится доступен: /api/v1/dictionaries/<name>/records
Kafka-топик начинает получать события об изменениях записей
Audit log начинает писать историю операций

Чек-лист перед созданием

Машинное имя в snake_case
Все обязательные поля помечены в required
Бизнес-ключ задан (x-id-source или поле в required)
Локализованные поля имеют x-localized: true
FK-поля указывают на существующие справочники
Описания (description) даны для каждого поля — это твоя памятка и помощь следующему оператору

Что НЕ стоит делать

❌ Создавать справочник «на всякий случай» без планируемых записей
❌ Класть бизнес-логику в схему (валидации вида «если X то Y») — это приведёт к жёсткой связке, тяжело менять
❌ Зашивать константы в description — описание читается оператором, но валидацию по нему не построишь

6.0 KiB Raw Blame History Unescape Escape