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