# Работа с записями

Запись — одна строка в справочнике (например, конкретный космический
аппарат «ISS» в справочнике `spacecraft`).

## Добавить запись

1. Открой справочник в каталоге
2. Кнопка **«Создать запись»** в правом верхнем
3. Заполни поля по схеме — обязательные помечены звёздочкой
4. **Период действия** — `valid_from` / `valid_to`:
   - `valid_from` — с какой даты запись актуальна (по умолчанию: сейчас)
   - `valid_to` — до какой даты (по умолчанию: открыто)
5. **«Сохранить»** — запись появляется в списке

### Бизнес-ключ

Если у справочника `x-id-source: "code"`, бизнес-ключ берётся из поля
`code`. Иначе — задаётся отдельно при создании. Бизнес-ключ должен быть
уникален: попытка создать запись с уже существующим ключом → ошибка 409.

### Локализованные поля

Поля с `x-localized: true` имеют отдельные значения для каждого языка:

```
Название [ru]: Международная космическая станция
Название [en]: International Space Station
```

Если оператор ввёл только одну локаль — остальные пусты, при чтении в
другой локали покажется fallback на язык по умолчанию словаря (обычно
`ru` для ЦУОД).

### FK-поля (ссылки)

Поля с `x-references` отображаются как выпадающий список. Например, у
`spacecraft` поле `type` ссылается на `satellite_type.code` — оператор
выбирает значение из готового списка типов. Если нужный тип отсутствует —
сначала добавь его в справочник `satellite_type`, потом возвращайся.

## Редактировать запись

1. Клик по записи в списке → открывается боковая панель (drawer)
2. Меняешь нужные поля, **«Сохранить»**
3. Новая версия записи создаётся; **предыдущая остаётся в истории**
   (см. [bitemporal модель](../integration/api/bitemporal.md))

История версий доступна:
- В drawer'е — кнопка **«История версий»**
- В timeline-режиме (`TimeTravel`) — слайдер по датам

### Что нельзя редактировать

- **Бизнес-ключ** — фиксирован с момента создания. Если ошибся — нужно
  закрыть запись (см. [Закрытие записи](close-record.md)) и создать новую.
- **Схему** — общая для всех записей справочника, меняется только через
  [schema draft](../reviewer/schema-drafts.md).

## Поиск и фильтрация

В каталоге справочника — toolbar поиска и фильтров:

- **Поиск по тексту** — ищет по бизнес-ключу и локализованным полям
- **Только заполненные** — toggle, скрывает записи где конкретное поле пустое
- **Период** — фильтр по `valid_from` / `valid_to`
- **Scope** — фильтр по уровню доступа (для администраторов)

### Глобальный поиск

В шапке (TopBar) — `⌘K` / `Ctrl+K` — поиск через все справочники по
бизнес-ключу или фрагменту названия.

## Bulk-операции

Сейчас bulk import / export — **только через API** ([интеграционный гайд](../integration/api/index.md)).
В UI массовых операций пока нет — добавятся в будущих версиях по запросам
от операторов.

## Что произойдёт при сохранении

- В БД добавляется новая версия записи
- В Kafka-топик публикуется событие `RecordCreated` или `RecordUpdated`
  (потребители — Альтум, геопортал, BI — узнают об изменении в течение
  секунд)
- В audit log пишется кто изменил, когда, что было до и после
- Если справочник имеет включённую Redis-проекцию — кэш обновляется
  автоматически

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

См. [Разбор ошибок](errors.md). Самые частые:

- **«Бизнес-ключ уже существует»** (409) — попробуй другой `code` или
  проверь, не закрыта ли существующая запись (фильтр истории)
- **«Поле X обязательно»** (422) — посмотри `required` в схеме
- **«FK не найден»** (422) — значение `x-references` указывает на запись,
  которой нет; добавь в referenced справочник
- **«Период действия пересекается»** (409) — для bitemporal: нельзя
  иметь две активные версии одной записи в один момент. См.
  [Закрытие записи](close-record.md).