Справочники (НСИ)¶

Раздел «Справочники» меню «Администрирование» — единое окно для работы с нормативно-справочной информацией (НСИ) модуля лояльности. Подзаголовок экрана — «Значения для настройки акций и операций». Справочники задают допустимые значения, на которые опираются акции, ручные операции и отчётность: группы акций, причины операций, каналы, регионы, механики, валюты, системные счета и др.

Модуль использует гибридную модель НСИ:

часть справочников ведётся внутри модуля и редактируется на этом экране;
часть доступна только для просмотра — их данные ведутся в своих разделах модуля (валюты, план счетов, единицы измерения);
у некоторых справочников есть собственный экран (теги клиентов, метки акций, сегменты клиентов) — реестр лишь открывает его;
справочники географии, мерчантов и каталога товаров (города, торговые точки, мерчанты, категории товаров, SKU) ведутся своим API, без экрана в интерфейсе: в реестре они видны, но не открываются.

Структура экрана¶

Область	Назначение
Реестр справочников (слева)	Список справочников, доступных пользователю. У справочников только для чтения — значок замка, у справочников со своим экраном — стрелка перехода. Строки справочников, у которых нет экрана в интерфейсе, неактивны.
Записи справочника (справа)	Название выбранного справочника, подсказка по его назначению, кнопки «История» и «Добавить запись», таблица записей.

При открытии раздела справа сразу показываются записи первого справочника из реестра (кроме справочников со своим экраном). Если у пользователя нет ни одного доступного справочника, вместо реестра выводится «Нет доступных справочников».

Для справочника только для чтения рядом с названием стоит метка «Только чтение», кнопок «История» и «Добавить запись» и колонки действий нет.

Доступность внешних справочников

Модуль умеет подключать справочники из внешней системы НСИ платформы; в текущей поставке таких справочников в реестре нет. Если подключённый внешний источник временно недоступен, справочник остаётся в реестре, но его записи не загружаются — над таблицей выводится предупреждение «Справочник временно недоступен. Попробуйте позже.». Локальные справочники от внешних сбоев не зависят.

Если не загрузился сам реестр или записи выбранного справочника, в соответствующей колонке показывается «Не удалось загрузить данные» с кнопкой «Повторить» — повторяется только упавший запрос.

Состав реестра¶

Справочник	Тип	Действия на экране
Группы акций	Локальный	Полное ведение. Используется в поле «Группа» карточки акции.
Типы событий	Локальный	Полное ведение. Используется как тип события акции.
Каналы	Локальный	Полное ведение. Значения условия акции «Канал продаж».
Причины операций	Локальный	Полное ведение. Значения — причины ручных начислений, корректировок и перевода уровня.
Механики (диаграммы RT Flow)	Локальный, типизированный	Создание, изменение, удаление; статусов жизненного цикла нет (см. ниже).
Регионы	Локальный	Полное ведение. Значения условия акции «Регион»; к региону относят города.
Типы баллов	Локальный	Полное ведение.
Валюты	Только чтение	Просмотр. Валюты ведутся в справочнике валют программы.
Системные счета	Только чтение	Просмотр плана системных счетов леджера.
Единицы измерения	Только чтение	Просмотр единиц для начисления по объёму, массе, штукам.
Категории товаров	Свой API, без экрана	Строка неактивна. Значения условия акции «Категории товаров»; ведутся администратором через API и CSV-импорт.
SKU / артикулы	Свой API, без экрана	Строка неактивна. Значения условия акции «Артикулы (SKU)»; ведутся через API и CSV-импорт.
Сегменты клиентов	Собственный экран	Переход на экран «Сегменты клиентов» — см. ниже.
Теги клиентов	Собственный экран	Переход на экран «Справочник тегов» — см. Теги клиента.
Метки акций	Собственный экран	Переход на экран «Справочник меток акций» — см. Метки акций.
Города	Свой API, без экрана	Строка неактивна. Значения условия акции «Город»; у города — регион и часовой пояс.
Торговые точки	Свой API, без экрана	Строка неактивна. Значения условия акции «Магазин»; у точки — город и адрес.
Мерчанты	Свой API, без экрана	Строка неактивна. Значения условия акции «Мерчант» — точки приёма партнёрских платежей (MID).

Справочники со своим экраном¶

Теги клиентов, метки акций и сегменты клиентов ведутся не общим механизмом записей, а на отдельных экранах со своими возможностями (у тегов и меток — переименование с контролем версии, слияние синонимов, каскад на клиентов и акции, выгрузка и загрузка бандла; у сегментов — журнал заливок из внешней системы). Щелчок по такой строке реестра открывает экран справочника по адресу /loyalty/admin/dictionaries/tags, /loyalty/admin/dictionaries/promotion-labels или /loyalty/admin/dictionaries/segments; своего пункта меню у этих экранов нет, кнопка «Справочники» над заголовком возвращает в реестр.

Города, торговые точки, мерчанты, категории товаров и SKU тоже ведутся своим API, но экрана в интерфейсе у них нет: строка в реестре показывается неактивной и не открывается. Как ведутся эти справочники, описано в руководстве администратора — «Справочники и НСИ».

Строка такого справочника видна в реестре только при наличии права на этот справочник: LOYALTY_TAG_READ для тегов, LOYALTY_PROMOTION_LABEL_READ для меток, LOYALTY_SEGMENT_READ для сегментов, LOYALTY_CITY_READ, LOYALTY_STORE_READ, LOYALTY_MERCHANT_READ для географии и мерчантов, LOYALTY_PRODUCT_CATALOG_READ для категорий товаров и SKU. Общие роли LOYALTY_DICTIONARY_* эти справочники не открывают.
Записи таких справочников нельзя читать и менять через общие операции справочников: сервер отвечает 409 dictionary_own_screen.

Сегменты клиентов¶

Экран «Сегменты клиентов» доступен с ролью LOYALTY_SEGMENT_READ. Сегменты заводит и наполняет внешняя система кампаний: создать или переименовать сегмент в модуле нельзя. Если справочник пуст, экран сообщает «Сегментов пока нет» — сегменты появятся, когда внешняя система их зарегистрирует.

Вкладка

Что показывает

«Сегменты»

Таблица сегментов: «Название», «Код», «Клиентов», «Состав рассчитан», «Действующих акций». Поиск по названию или коду; переключатель «Показать архивные» добавляет архивные сегменты отдельным блоком.

«Заливки»

Журнал заливок из внешней системы: «Начата», «Сегмент», «Режим», «Статус», «Состав рассчитан», «Пачек», «Вошло», «Вышло» и другие колонки; поиск по сегменту или ID расчёта, фильтры, быстрый просмотр заливки по «Подробнее».

Контекстное меню строки сегмента:

Пункт	Кому доступен	Что делает
«Показать заливки»	Всем с доступом к экрану	Открывает вкладку «Заливки» с отбором по этому сегменту.
«Архивировать» / «Разархивировать»	С ролью `LOYALTY_SEGMENT_WRITE`	Архивный сегмент перестаёт предлагаться при выборе в акциях и партнёрских предложениях; там, где он уже выбран, он продолжает работать. Вернуть из архива можно в любой момент.
«Удалить»	С ролью `LOYALTY_SEGMENT_WRITE`	Удаляет сегмент вместе с составом. Недоступно, пока сегмент используется в действующих акциях: «Сегмент используется в действующих акциях — удалить нельзя. Архивируйте его или уберите из акций».

Последствия удаления сегмента

В черновиках и завершённых акциях условие с удалённым сегментом становится недействительным, а партнёрские предложения и ограничения списания по нему перестают срабатывать. Если внешняя система зарегистрирует сегмент снова, он появится заново.

Запись справочника¶

Поле	Описание
Код	Идентификатор записи. Обязателен; подсказка в поле — формат `UPPER_SNAKE`. Задаётся при создании и далее не меняется (при редактировании поле заблокировано).
Название	Человекочитаемое название записи. Обязательно.
Описание	Необязательное пояснение.
Порядок	Целое число не меньше `0` для упорядочивания записей в списках. По умолчанию `0`.
Статус	Текущая стадия жизненного цикла: «Черновик», «Активна», «Архив».

Записи в таблице упорядочены по полю «Порядок», затем по коду.

Создание и редактирование выполняются в модальном окне «Добавить запись» / «Изменить запись». При создании под формой показывается подсказка: «Новая запись создаётся в статусе «Черновик» — активируйте её, чтобы начать использовать.» Сохранение существующей записи меняет название, описание и порядок, но не статус — статус меняется только переходом (см. ниже).

Нормализация кода

Сервер обрезает пробелы в начале и в конце кода записи — одинаково при сохранении, смене статуса и удалении. Код GIFT_RETURN и GIFT_RETURN — одна и та же запись, как бы к ней ни обратились.

Ошибки при сохранении:

Код	Когда
`422 dictionary_code_blank`	Не указан код записи.
`422 dictionary_label_blank`	Не указано название записи.
`409 dictionary_entry_archived`	Попытка изменить запись в статусе «Архив».
`409 dictionary_read_only`	Справочник доступен только для чтения.

Жизненный цикл записи¶

Статус	Значение
DRAFT — «Черновик»	Запись подготовлена, но ещё не используется в работе.
ACTIVE — «Активна»	Действующая запись, применяется в работе модуля.
ARCHIVED — «Архив»	Запись выведена из обращения, но сохранена для истории.

flowchart LR
    DRAFT -->|Активировать| ACTIVE
    DRAFT -->|Архивировать| ARCHIVED
    ACTIVE -->|Архивировать| ARCHIVED
    ARCHIVED -->|Активировать| ACTIVE

Из статуса	Допустимые переходы
DRAFT	ACTIVE, ARCHIVED
ACTIVE	ARCHIVED
ARCHIVED	ACTIVE

Смена статуса выполняется через выпадающее меню «Статус» в строке записи — в нём только разрешённые из текущего статуса переходы: «Активировать» и «Архивировать». Повторная установка текущего статуса ничего не меняет. Недопустимый переход отклоняется с 409 dictionary_status_transition, неизвестное значение статуса — 422 dictionary_status_invalid.

Возврат в черновик невозможен

Перехода из ACTIVE обратно в DRAFT нет: действующую запись можно только отправить в архив. Из архива запись возвращается сразу в ACTIVE.

Архивную запись нельзя изменить¶

Запись в статусе «Архив» не редактируется: выведенное из обращения значение не должно менять смысл, оставаясь выведенным. Кнопка редактирования на архивной строке погашена, подсказка при наведении — «Запись в архиве — верните её в работу, чтобы изменить.» Попытка сохранить архивную запись в обход интерфейса отклоняется сервером: 409 dictionary_entry_archived.

Чтобы изменить архивную запись, сначала верните её в работу пунктом «Активировать» меню «Статус», затем отредактируйте.

Удаление записи¶

Удаление выполняется кнопкой с корзиной в строке записи и подтверждается вопросом «Удалить запись?».

Запись, на которую ссылаются акции, удалить нельзя. Решение об удалении принимает сервер и передаёт его вместе со списком записей: число ссылающихся акций и признак «можно удалить». Для такой записи кнопка удаления погашена заранее, подсказка при наведении — «Используется в N акциях — сначала отвяжите их.» Удаление в обход интерфейса отклоняется: 409 dictionary_entry_in_use.

Ссылки учитываются там, где они однозначно видны в настройках акции, — во всех акциях, включая завершённые:

Справочник	Что считается ссылкой
Группы акций	Поле «Группа» акции.
Типы событий	Тип события акции.
Регионы, Каналы	Значение в условии акции «Регион» или «Канал продаж» — и в зоне «Акция применяется, если», и в зоне «Не применяется, если».
Любой справочник этого экрана	Значение в добавленном условии акции со способом «Из справочника», построенном на этом справочнике (условия добавляются в разделе «Администрирование → Настройка акции»).
Механики	Акции, созданные на механике.

Запись, на которую не ссылается ни одна акция, удаляется без ограничений. Удаление несуществующего кода отвечает 404 dictionary_entry_not_found.

Механики¶

Справочник «Механики (диаграммы RT Flow)» — типизированный: механика соответствует диаграмме RT Flow/SDE, которая её исполняет. Подсказка в форме: «Механика = диаграмма RT Flow. Интеграция с RT Flow идёт через этот справочник; ведётся вручную, без статусов ЖЦ.»

Поле	Описание
Код	Код механики. Обязателен.
Название механики	Обязательно.
Тип	«Начисление», «Списание» или «Смешанная». Обязателен.
Диаграмма RT Flow	Имя диаграммы RT Flow/SDE, исполняющей механику (например, `cashback_v1`). Обязательна.
Описание	Необязательно.

У механик нет статусов и меню «Статус»; попытка сменить статус отклоняется 409 mechanic_no_lifecycle.
Механику, на которую ссылаются акции, удалить нельзя: сервер передаёт решение вместе со списком, кнопка удаления погашена заранее с подсказкой о числе акций, удаление в обход интерфейса — 409 mechanic_in_use. Вместе с механикой удаляются определения её параметров.
Новая или изменённая механика сразу доступна в выпадающем списке механик карточки акции.

История изменений (аудит)¶

Кнопка «История» открывает боковую панель «История изменений» выбранного справочника. Записи идут от свежих к старым.

Колонка	Описание
Когда	Дата и время изменения.
Действие	«Создание», «Изменение», «Удаление» или «Смена статуса».
Код	Код затронутой записи.
Кто	Учётная запись пользователя, выполнившего изменение (при отсутствии пользовательского контекста — `system`).
Детали	Для создания — «создана в статусе DRAFT», для изменения — новое название, для смены статуса — переход вида `DRAFT → ACTIVE`.

Перенос справочников между контурами¶

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

flowchart LR
    A["Исходный контур:<br/>выгрузка набора (JSON)"] --> B["Целевой контур:<br/>предпросмотр (dryRun=true)"]
    B -->|итог устраивает| C["Целевой контур:<br/>применение"]

Что переносится. Только записи локальных справочников общего реестра, которые можно вести в админке (группы акций, типы событий, каналы, причины операций, регионы, типы баллов). Запись любого другого справочника в наборе попадает в ошибки — и в предпросмотре, и при загрузке:

Запись в наборе	Причина в ошибках
Справочник, которого нет в реестре	«Справочник не найден: …»
Справочник со своим экраном (теги клиентов, метки акций, сегменты клиентов, категории товаров, SKU, города, торговые точки, мерчанты) — они переносятся своими средствами	«Справочник '…' ведётся на своём экране и своим API»
Справочник только для просмотра (валюты, системные счета, единицы измерения)	«Справочник '…' только для просмотра: он ведётся в своём разделе»
Механики — у них свой перенос (см. Операционная конфигурация)	«Механики ведутся своим API и переносятся своим файлом»

Правила загрузки:

Правило	Поведение
Опознание	По паре «ключ справочника + код записи» (внутренние идентификаторы в контурах разные).
Отсутствующая запись	Создаётся.
Существующая запись	Пропускается и не перезаписывается.
Дубликат внутри файла	Вторая запись с тем же кодом попадает в «пропущено».
Ошибка одной записи	Не отменяет перенос остальных; попадает в список ошибок.
Статус записи	Переносится как есть (в отличие от акций, которые приезжают выключенными): запись справочника — это данные, а не расход бюджета.
Проверки записи	Те же, что при заведении в админке: код и название обязательны («Название записи обязательно»), название обрезается от краевых пробелов. Запись с пустым названием, заведённая старым переносом, при следующем переносе будет отвергнута — назовите её в админке.
Журнал	Созданная запись попадает в историю изменений справочника (действие «Создание») с автором загрузки.

Предпросмотр. Загрузка с параметром dryRun=true ничего не записывает, но возвращает итог, посчитанный по тем же правилам, что и настоящая загрузка: что будет создано, что пропущено как уже существующее, что не пройдёт. В ответе признак dryRun: true означает, что перечисленное в created ещё не создано. Предпросмотр требует тех же прав, что и загрузка.

{
  "created": ["operation-reason/GIFT_RETURN"],
  "skipped": ["promotion-group/SUMMER"],
  "errors": [{ "entry": "tag/vip", "message": "Справочник 'tag' ведётся на своём экране и своим API" }],
  "dryRun": true
}

Управление доступом¶

Роль	Возможности
`LOYALTY_DICTIONARY_READ`	Просмотр реестра, записей и истории изменений; выгрузка набора для переноса.
`LOYALTY_DICTIONARY_WRITE`	Создание, изменение, удаление записей и смена статуса (только локальные редактируемые справочники); загрузка и предпросмотр набора.
`LOYALTY_TAG_READ` / `LOYALTY_PROMOTION_LABEL_READ` / `LOYALTY_SEGMENT_READ`	Видимость строк «Теги клиентов» / «Метки акций» / «Сегменты клиентов» в реестре и доступ к их экранам. Сам реестр открывается только с `LOYALTY_DICTIONARY_READ`; без неё экран справочника доступен лишь по прямой ссылке.
`LOYALTY_SEGMENT_WRITE`	Архивация, возврат из архива и удаление сегмента на экране «Сегменты клиентов».
`LOYALTY_CITY_READ`, `LOYALTY_STORE_READ`, `LOYALTY_MERCHANT_READ`, `LOYALTY_PRODUCT_CATALOG_READ`	Видимость неактивных строк «Города», «Торговые точки», «Мерчанты», «Категории товаров» и «SKU / артикулы» в реестре.

Без роли LOYALTY_DICTIONARY_WRITE кнопки «Добавить запись», «Статус», редактирования и удаления недоступны, подсказка при наведении — «Недостаточно прав: нужна роль LOYALTY_DICTIONARY_WRITE».

Программный интерфейс¶

Все пути — с префиксом /v1.

Метод и путь	Назначение	Роль
`GET /admin/dictionaries`	Реестр справочников (признаки редактируемости, доступности и собственного экрана `ui`).	`LOYALTY_DICTIONARY_READ`
`GET /admin/dictionaries/{key}/entries`	Записи справочника; у записей — `usedByPromotions` и `deletable`.	`LOYALTY_DICTIONARY_READ`
`GET /admin/dictionaries/{key}/audit`	История изменений справочника.	`LOYALTY_DICTIONARY_READ`
`POST /admin/dictionaries/{key}/entries`	Создать или обновить запись.	`LOYALTY_DICTIONARY_WRITE`
`POST /admin/dictionaries/{key}/entries/{code}/status`	Сменить статус записи.	`LOYALTY_DICTIONARY_WRITE`
`DELETE /admin/dictionaries/{key}/entries/{code}`	Удалить запись.	`LOYALTY_DICTIONARY_WRITE`
`GET /admin/dictionaries/export?dictKeys=…`	Выгрузить записи локальных справочников (все или по ключам) в JSON.	`LOYALTY_DICTIONARY_READ`
`POST /admin/dictionaries/import?dryRun=…`	Загрузить набор; `dryRun=true` — предпросмотр без записи.	`LOYALTY_DICTIONARY_WRITE`

Признаки записи, по которым экран гасит кнопку удаления:

Поле	Значение
`usedByPromotions`	Сколько акций ссылается на запись; пусто — у справочников только для чтения (валюты, системные счета, единицы измерения).
`deletable`	Готовое решение сервера: `false` — удалить нельзя, `true` — можно, пусто — справочник решения не выносит.

Пример тела запроса на создание/обновление записи:

{
  "code": "GIFT_RETURN",
  "label": "Возврат подарка",
  "description": "Причина корректирующей операции",
  "sortOrder": 10
}

Скорость применения изменений

Валюты, план счетов, субсчета и переопределения операционной конфигурации модуль держит в памяти каждого экземпляра не дольше 30 секунд. На экземпляре, через который сделано изменение, оно действует сразу; остальные экземпляры увидят его не позже чем через этот срок.