Настройка карточки клиента¶
Конфигуратор «Настройка профиля клиента» определяет, как выглядит карточка клиента: какие поля (атрибуты) есть у клиента, как они подписаны, в каких блоках левой колонки стоят, какие разделы и вкладки с таблицами данных показываются справа. Экран открывается пунктом Администрирование → «Профиль клиента» (в автономном режиме пункт называется «Настройка профиля клиента»).
Настройка версионируется целиком: правки готовятся в черновике и попадают в карточку у всех операторов только после активации версии.
Версии настройки¶
Раздел открывается списком версий настройки. Подзаголовок экрана: «Активная может быть только одна версия. Изменения применяются ко всем данным на стенде».
| Колонка | Содержимое |
|---|---|
| Название | Название версии |
| Статус | «Активна» — по ней собирается карточка клиента; «Черновик» — остальные версии |
| Изменил | Кто правил версию последним |
| Изменена | Дата и время последней правки |
Активная версия всегда первая, ниже — черновики по дате изменения. Один клик выбирает строку (можно несколько), двойной — открывает версию, правый — меню «Открыть», «Создать копию», «Активировать», «Удалить». Недоступное действие остаётся на месте с подсказкой, почему оно недоступно.
| Кнопка | Что делает |
|---|---|
| Активировать | Делает выбранный черновик активной версией (см. Активация). Доступна при выборе одной версии |
| Создать копию | Копирует любую версию, в том числе активную, в новый черновик «Копия: {название}» и сразу открывает его; тост «Создан черновик — правьте и делайте активным» |
| Удалить | В интерфейсе пока неактивна («Скоро»); активную версию удалить нельзя в любом случае |
Типичный порядок работы: снять копию с активной версии, отредактировать черновик, проверить предпросмотр и активировать.
Активация¶
Окно «Сделать настройку активной?» предупреждает: «Карточка клиента изменится для всех на стенде. Текущая активная настройка станет черновиком — её можно активировать снова.» Ниже — перечень отличий от активной версии, который считает сервер: «Отличий от активной настройки: N», сгруппированный по виду изменения — «Добавлено», «Убрано», «Переименовано», «Порядок», «Свойства»; у каждой строки — вид сущности: «Атрибут», «Расположение», «Раздел», «Столбец». Если отличий нет, окно сообщает «Отличий от активной настройки нет — карточка клиента не изменится», и активировать всё равно можно. Подтверждение — «Да, сделать активной».
Переключение атомарно: прежняя активная версия становится черновиком в той же операции.
Заполненные значения не теряются молча
Версию, в которой нет атрибута, заполненного у клиентов и присутствующего в активной версии,
активировать нельзя: «Активировать нельзя: в этой версии нет атрибута, который заполнен у
клиентов и показывается сейчас…» (409 configuration_field_has_values с перечнем ключей). Верните
атрибут в версию. Сами значения при этом не удаляются.
Активация — отдельное право LOYALTY_CLIENT_PROFILE_ACTIVATE: права на правку для неё недостаточно,
и наоборот.
Удаление версий¶
Удалить черновик можно через API: DELETE /v1/admin/client-profile/configurations/{id} или пакетом
POST /v1/admin/client-profile/configurations/bulk-delete с телом {ids} — выбор удаляется целиком
или не удаляется вовсе. Активная версия не удаляется (409 configuration_active_undeletable).
Значения атрибутов у клиентов при удалении версии не трогаются. Нужна роль
LOYALTY_CLIENT_PROFILE_DELETE; других прав на удаление нет.
Экран версии¶
Версия открывается экраном «Настройка профиля клиента» с двумя вкладками — «Структура профиля клиента» и «Атрибуты» (по умолчанию открывается «Атрибуты»). В шапке — название версии, её статус и кнопка переименования (переименовать можно и активную версию); ссылка «Все настройки» возвращает к списку версий.
Активная версия — только просмотр
Активную версию не правят: экран показывает плашку «Активная настройка открыта только для просмотра. Чтобы её изменить, создайте копию, отредактируйте и сделайте активной.» с кнопкой «Создать копию».
Правки черновика сохраняются двумя способами:
| Что | Когда применяется |
|---|---|
| Порядок карточек, разделов, таблиц, атрибутов и столбцов; переименование карточек, разделов, таблиц и подписей столбцов; перенос таблицы в другой раздел; переключатели «Видимость» и «В каталоге» | Копятся на экране и уходят по общей кнопке «Сохранить» — одной на обе вкладки |
| Создание и правка атрибута в форме; создание и удаление карточек, разделов, таблиц; архивация, возврат из архива и удаление атрибутов | Сразу, после своего подтверждения |
Пока есть несохранённые правки, в шапке видна надпись «Есть несохранённые изменения» и кнопка «Отменить изменения» (с подтверждением «Вы уверены, что хотите отменить все несохранённые изменения?»). Переключение вкладок правки не теряет, уход со страницы — через подтверждение. Кнопка «Предпросмотр» показывает карточку с текущими настройками, см. Предпросмотр.
Если версию параллельно изменил другой администратор, сохранение отклоняется: «Настройку изменил другой администратор, пока вы работали. Она перечитана — повторите правку».
Вкладка «Структура профиля клиент໶
Вкладка задаёт скелет карточки клиента. У каждой из двух частей есть ссылка «Где это на карточке» — схема карточки с подсвеченной областью.
Карточки¶
«Карточки» — блоки левой колонки карточки клиента: поля с одним значением на клиента. Колонки: название и «Атрибутов: N». Кнопка «Добавить карточку» открывает форму «Новая карточка»:
| Поле | Правило |
|---|---|
| Название | Обязательно, например «Контактные данные» |
| Схема, Таблица | Необязательно: схема и таблица базы, откуда берутся значения полей карточки. Без источника поля карточки заполняются вручную |
- Название правится по месту двойным кликом, порядок — перетаскиванием.
- Иконка настройки строки открывает атрибуты карточки на вкладке «Атрибуты».
- Карточки, поставляемые с продуктом («Клиент», «Баллы и уровень»), удалить нельзя. Карточку с атрибутами тоже нельзя удалить — сначала перенесите атрибуты в другую карточку.
Таблицы данных по клиенту¶
«Таблицы данных по клиенту» — вкладки правой части карточки, сгруппированные по разделам. Здесь живут данные, которых у клиента много: операции, покупки, коммуникации.
- «Добавить раздел» — форма «Новый раздел» с полем «Название раздела». Раздел с таблицами удалить нельзя — сначала перенесите их в другой раздел.
- «Добавить таблицу» в строке раздела — форма «Новая таблица»: «Название», «Раздел», «Схема» и «Таблица» — все обязательны. Если своего названия нет, оно подставляется из описания выбранной таблицы-источника.
- Двойной клик по таблице открывает форму «Изменить таблицу»: можно переименовать таблицу и перенести её в другой раздел; источник после создания не меняется.
- Под названием таблицы — «Источник: {схема}.{таблица}», рядом — «Столбцов: N из M» (сколько столбцов источника показывается).
- Порядок разделов и таблиц внутри раздела — перетаскиванием.
Строки таблицы-источника связываются с клиентом по колонке external_id — она должна быть у
таблицы и иметь строковый тип (иначе 422 source_link_not_found).
Вкладки продукта¶
В каждой версии есть восемь вкладок, которые поставляются с продуктом, в трёх разделах продукта:
| Раздел | Вкладки |
|---|---|
| Баллы и уровень | «Счета и балансы», «Бонусные операции», «Сроки сгорания», «История уровней» |
| Клиент | «Статус клиента», «Достижения», «Рефералы» |
| Активность и коммуникации | «Участие в акциях» |
Содержимое таких вкладок задаёт продукт: источника и столбцов у них нет (подпись источника под названием вкладки продукта пока выводится без значения — «Источник: null.null»). Вкладку продукта нельзя удалить; переставить и перенести в другой раздел можно. Раздел продукта можно переименовать и переставить, но не удалить.
Не переименовывайте вкладки продукта
Карточка клиента пока опознаёт вкладку продукта по её названию. Переименованная вкладка продукта в карточке покажется дважды: под прежним названием — с данными продукта, под новым — как таблица, данные которой не загружаются.
Признак «показывать в карточке» пока не действует
У вкладки продукта есть признак showInCard (по умолчанию true): его принимает только API —
PUT /v1/admin/client-profile/groups/{id} как обычную правку черновика; копия версии его
переносит, а окно активации показывает его смену свойством («показ в карточке: да → нет»). Выключить признак можно только
у вкладки продукта — у карточки и таблицы администратора false отклоняется
400 validation_failed. Интерфейс конфигуратора и карточки клиента признак пока не учитывает:
вкладка со showInCard: false в карточке всё равно показывается. Это не право доступа — данные
вкладки по-прежнему доступны через API.
Источники данных¶
Схемы, из которых можно брать таблицы и колонки, задаёт белый список
loyalty.client-profile.source-schemas (переменная LOYALTY_CLIENT_PROFILE_SOURCE_SCHEMAS, по
умолчанию пуст). В списках видны только таблицы и колонки, на которые у приложения есть права в базе;
человекочитаемые названия берутся из комментариев таблиц и колонок. Пока список пуст, экран
сообщает «Источники не настроены: список схем пуст…»: таблицу данных завести не на чем, а карточки
работают — их поля заполняются вручную.
Вкладка «Атрибуты»¶
Вкладка показывает содержимое одного расположения за раз — карточки или таблицы, выбранной в переключателе «Расположение». Над таблицей — заголовок расположения со счётчиком «Атрибутов: N» или «Столбцов: N» и ссылкой на его настройку в структуре.
| Элемент | Назначение |
|---|---|
| «Расположение» | Выбор карточки или таблицы данных: сначала карточки, затем таблицы с подписью «Раздел — Таблица» |
| Поиск «Поиск по названию, описанию и источнику» | Подстрока по строкам выбранного расположения |
| «Показывать архивные» | Показать архивные атрибуты отдельным блоком «Архивные» под действующими |
| «Добавить атрибут» | Форма нового атрибута; расположение подставляется из переключателя |
Колонки таблицы:
| Колонка | Содержимое |
|---|---|
| Описание | Подпись поля в карточке клиента |
| Название | Технический ключ атрибута или колонки источника |
| Тип | «Строка», «Число», «Дата», «Дата со временем», «Логический» |
| Способ ввода | «Вручную», «Выпадающий список», «Из системы»; у множественного списка — пометка «Несколько» |
| Источник | Колонка таблицы-источника, из которой берётся значение; прочерк — значение вводит оператор |
| Видимость | Показывать ли поле в карточке клиента |
| В каталоге | Признак «показывать колонкой в каталоге клиентов»; у столбцов таблиц неприменимо |
| Статус | «Активен» или «В архиве» |
| Изменил | Кто правил атрибут последним |
Порядок строк — это порядок полей в карточке; меняется перетаскиванием, в том числе группой выделенных строк (при активном поиске перетаскивание выключено). Сортировки по колонкам нет.
Признак «В каталоге»
Признак сохраняется в настройке, но каталог клиентов его пока не учитывает: состав колонок каталога задан продуктом, см. Каталог клиентов.
Действия со строкой атрибута: двойной клик — форма правки, правый клик — меню «Редактировать», «Архивировать» (у архивного — «Разархивировать»), «Удалить». При выделении строк появляется панель «Выбрано: N» с кнопками «Снять выделение» и «Удалить».
У столбцов таблицы данных своей формы нет: состав и тип задаёт источник. Здесь можно только переименовать подпись по месту (пустая подпись возвращает описание колонки из источника), включить или выключить «Видимость» и поменять порядок.
Форма атрибута¶
Форма «Новый атрибут» («Редактировать атрибут» при правке):
| Поле | Правило |
|---|---|
| Описание | Обязательно. Так поле будет подписано в карточке клиента |
| Название | Обязательно. Строчные латинские буквы, цифры и «_», не с цифры, до 64 символов. После создания не меняется — по нему хранятся значения |
| Тип данных | Обязательно: «Строка», «Число», «Дата», «Дата со временем», «Логический». После создания не меняется |
| Способ ввода | «Вручную» или «Выпадающий список»; после создания не меняется. У атрибута с колонкой источника — «Из системы», не выбирается |
| Справочник | Для выпадающего списка — обязательно: справочник НСИ, из которого оператор выбирает значения |
| Колонка источника | Если у карточки есть источник: колонка таблицы, из которой читается значение (строка ищется по идентификатору клиента). Выбор подставляет название, описание и тип, делает способ ввода «Из системы», а поле — нередактируемым в карточке. После создания не меняется |
| Расположение | Обязательно: карточка, в которой стоит поле. Атрибут кладётся только в карточку, не в таблицу |
| Показывать в карточке | Включается выбором расположения |
| Показывать в каталоге клиентов | Признак колонки каталога |
| Множественный выбор | Только у выпадающего списка: оператор выбирает несколько значений, в карточке они показываются пилюлями |
| Чувствительные данные | Пометка чувствительного атрибута |
Заполненную форму нельзя закрыть молча — подтверждение «Закрыть без сохранения?». Занятое название подсвечивается под полем: «Атрибут с таким названием уже есть. Возможно, он в архиве — включите «Показывать архивные», чтобы найти его».
Чувствительные данные — пока пометка
Признак сохраняется у атрибута и показывается в предпросмотре, но в карточке клиента значения чувствительных атрибутов пока не скрываются от ролей без доступа к персональным данным.
Атрибуты, поставляемые с продуктом¶
Преднастроенные атрибуты — «ID клиента», «Телефон», «ФИО», «Email», «Дата рождения», «Баллы», «Уровень», «Сегменты», «Статус», «Дата регистрации» — нельзя удалить или архивировать. Чтобы убрать такой атрибут из карточки, выключите «Видимость». У них можно менять описание, расположение, порядок и признаки показа; ключ, тип и способ ввода задаёт продукт.
Архивация и удаление¶
- Архивация скрывает атрибут из карточки клиента и из настройки, значения у клиентов сохраняются; действие обратимо. Архивный атрибут не редактируется — сначала верните его из архива; вернувшийся атрибут встаёт в конец порядка. Архивный атрибут продолжает занимать своё название.
- Удаление доступно, только если атрибут не заполнен ни у одного клиента: «Удалить нельзя: у атрибута есть значения у клиентов. Перенесите его в архив — значения сохранятся».
- Атрибут, на котором построено условие акции, не удаляется: «Удалить нельзя: на атрибуте построено условие акции {название}. Сначала удалите его в «Настройке акции», потом атрибут».
- Удаление нескольких атрибутов подтверждается списком с возможностью снять отдельные строки («Будет удалено: N, пропущено: M»); каждый атрибут обрабатывается отдельно — при частичном успехе тост «Удалено {N} из {M}. Остальные удалить не удалось», не удалённые остаются выделенными.
Предпросмотр¶
Кнопка «Предпросмотр» открывает окно «Предпросмотр карточки клиента» — как будет выглядеть карточка с текущими настройками черновика, включая ещё не сохранённые правки. Значения показаны для примера по типу поля и не являются данными реального клиента. Переключатель «Показать, как видит роль без доступа к персональным данным» показывает, какие значения будут скрыты у чувствительных атрибутов.
Права¶
| Роль | Что открывает |
|---|---|
LOYALTY_DICTIONARY_READ |
Просмотр версий, структуры, атрибутов, источников и отличий |
LOYALTY_DICTIONARY_WRITE |
Правка черновиков: атрибуты, структура, столбцы, копия и переименование версии |
LOYALTY_CLIENT_PROFILE_ACTIVATE |
Активация версии |
LOYALTY_CLIENT_PROFILE_DELETE |
Удаление версий (через API) |
Без права правки экран открывается на просмотр: кнопки и переключатели заблокированы с подсказкой
«Недостаточно прав: нужна роль …». Оператору карточки клиента доступ к конфигуратору не нужен: поля и
раскладка активной версии читаются отдельными операциями под LOYALTY_CUSTOMER_READ (права на саму
карточку — см. Карточка клиента).
Выкладка ролей
Роли LOYALTY_CLIENT_PROFILE_ACTIVATE и LOYALTY_CLIENT_PROFILE_DELETE входят в группу
LOYALTY_ADMINS. На уже развёрнутом realm Keycloak они появляются после повторного импорта
ролей — без них активация и удаление версии отвечают 403.
API¶
Операции над содержимым версии (атрибуты, карточки, таблицы, разделы, столбцы) принимают
параметр configurationId; изменяющие — ещё и заголовок If-Match с ревизией версии (без него —
428 version_required). Свежая ревизия возвращается в ETag после успешной правки.
| Метод и путь | Назначение |
|---|---|
GET /v1/admin/client-profile/configurations |
Список версий |
GET, PATCH /v1/admin/client-profile/configurations/{id} |
Версия; переименование |
POST /v1/admin/client-profile/configurations/{id}/copy |
Копия версии |
POST /v1/admin/client-profile/configurations/{id}/activate |
Активация |
GET /v1/admin/client-profile/configurations/{id}/diff |
Отличия от активной версии |
DELETE /v1/admin/client-profile/configurations/{id}, POST …/configurations/bulk-delete |
Удаление версии или выбора версий |
/v1/admin/client-profile/fields |
Атрибуты: список (archived=true — вместе с архивными), создание, правка, удаление, bulk-delete, archive, unarchive, порядок order |
/v1/admin/client-profile/groups |
Карточки и таблицы: создание, правка (название, раздел, у вкладки продукта — showInCard), удаление, порядок, столбцы таблицы {id}/columns |
/v1/admin/client-profile/table-sections |
Разделы: создание, переименование, удаление пустого, порядок |
GET /v1/admin/client-profile/source-schemas, source-tables, source-columns |
Каталог источников из белого списка схем |
Коды ошибок:
| Код | HTTP | Когда |
|---|---|---|
configuration_active_immutable |
409 | Правка активной версии |
configuration_already_active |
409 | Активация версии, которая уже активна |
configuration_field_has_values |
409 | Активация версии без атрибута, заполненного у клиентов |
configuration_active_undeletable |
409 | Удаление активной версии |
configuration_not_found |
404 | Версии нет (удалена) |
version_conflict / version_required |
409 / 428 | Ревизия версии устарела / не передана |
field_key_exists |
409 | Название атрибута занято, в том числе архивным |
field_key_immutable |
422 | Попытка сменить название атрибута |
field_has_values |
409 | Удаление атрибута, заполненного у клиентов |
profile_field_used_in_criterion |
409 | Удаление атрибута, на котором построено условие акции; в теле — условия [{code, label}] |
system_field_immutable |
422 | Удаление или архивация преднастроенного атрибута |
system_group_immutable / system_section_immutable |
422 | Удаление карточки, вкладки или раздела продукта |
group_not_empty / section_not_empty |
409 | Удаление карточки с атрибутами / раздела с таблицами |
invalid_field_type / invalid_input_source |
422 | Недопустимый тип или способ ввода |
invalid_field_group |
422 | Расположения атрибута нет или это таблица, а не карточка |
source_schema_not_allowed / source_table_not_found / source_link_not_found |
422 | Схема вне белого списка / таблицы нет / у таблицы нет строковой колонки external_id |
validation_failed |
400 | Нарушение правил полей запроса (формат названия, пустые обязательные поля) |
bulk_size_exceeded |
400 | Пакет больше loyalty.client-profile.max-bulk-ids (по умолчанию 200) |