feat(topbar): «Что нового» button + 2026-05-12 state.md update

2026-05-12 17:05:24 +00:00
parent 58dd871808
commit a34c6d4c82
21 changed files with 1853 additions and 8 deletions
@@ -0,0 +1,101 @@
+# Работа с записями
+
+Запись — одна строка в справочнике (например, конкретный космический
+аппарат «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).