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,118 @@
+# Создание справочника
+
+Справочник — это таблица однородных записей с фиксированной схемой полей.
+Прежде чем создавать его в системе, продумай: какие поля будут, какие
+обязательны, какие ссылаются на другие справочники.
+
+## Когда нужен новый справочник
+
+- Нужны однородные данные (>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` — описание читается оператором,
+      но валидацию по нему не построишь