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

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

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

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

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

## Шаги

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

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

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

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

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

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

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

```json
{
  "$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 в форме |

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

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

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

### 4. Опубликуй

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

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

При создании справочника:
- В БД появляется таблица записей с этой схемой
- В 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` — описание читается оператором,
      но валидацию по нему не построишь