Достижения и бейджи¶

Достижения — это нефинансовая геймификация программы: маркетолог заводит правило «условие → бейдж», и клиент получает бейдж автоматически, как только условие выполнено. Бейдж не создаёт проводку и не меняет баланс баллов — это только знак признания, показываемый клиенту и оператору.

Бейдж — не награда из каталога

Бейдж нельзя заказать и нельзя обменять на баллы — этим он принципиально отличается от наград программы вознаграждений. У него нет статуса выдачи, ваучера и согласования бюджета: правило настраивается один раз, а дальше бейджи выдаются сами.

Правило «условие → бейдж»¶

Правило заводит маркетолог на экране Администрирование → Достижения. У правила есть условие (из закрытого перечня) и оформление бейджа.

Поле	Назначение
`code`	Технический код достижения — уникален, по нему бейдж узнаётся после переименования
`name`	Название бейджа
`description`	Необязательное описание — показывается клиенту под названием
`icon`	Значок бейджа — из закрытого набора (см. ниже)
`conditionType`	Тип условия — из закрытого перечня (см. ниже)
`threshold`	Порог для условий-величин (обязателен, если условие — величина)
`conditionValue`	Код уровня для условия «Достигнут уровень» (обязателен для этого условия)
`ordinal`	Порядок показа бейджа среди прочих
`active`	Признак «Выдаётся» — включает или выключает выдачу

Условия¶

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

Условие (API)	Подпись	Что сравнивается
`PURCHASE_COUNT`	Число покупок	Число покупок клиента за всё время ≥ порога
`PURCHASE_AMOUNT`	Сумма покупок	Сумма покупок клиента за всё время (в баллах/рублях) ≥ порога
`ACCRUED_POINTS`	Начислено баллов	Начислено баллов клиенту за всё время ≥ порога
`REDEEMED_POINTS`	Списано баллов	Списано баллов клиентом за всё время ≥ порога
`TIER_REACHED`	Достигнут уровень	Текущий уровень клиента равен выбранному в правиле

Условие-величина считается выполненным при значении не ниже порога (не «ровно»): клиент, перескочивший порог за одну операцию, всё равно получает бейдж.

Что не входит в показатели

Сгорание — и плановое по сроку, и ручное оператором — не считается тратой клиента, поэтому не увеличивает показатель «Списано баллов». Сторно — отмена начисления, в том числе при возврате покупки или отзыве промокода, — не попадает ни в один показатель: оно не считается тратой (бейдж «потратил N баллов» за отобранные баллы не выдаётся) и не уменьшает «Начислено баллов».

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

Значки¶

Значок выбирается из закрытого набора: Звезда, Кубок, Награда, Медаль, Знак отличия, Подтверждено, Бриллиант, Молния, Сердце, Праздник, Лояльность, Копилка. Незнакомое имя значка (например, из старой версии контракта) отображается звездой по умолчанию.

Выдача бейджа¶

Показатели клиента (число и сумма покупок, начислено, списано) копятся счётчиками и увеличиваются при каждой операции — не пересчитываются выборкой по журналу. Бейдж проверяется и выдаётся в той же транзакции, что и операция, которая его вызвала: если операция (например, покупка) откатится, бейдж не будет выдан.

Правило	Следствие
Бейдж выдаётся один раз	Повторная выдача одного и того же бейджа одному клиенту невозможна на уровне схемы данных
Выключение правила не отзывает выданное	У клиента остаётся уже полученный бейдж, даже если правило потом выключили (`active = false`)
Удаление правила уносит выданные бейджи	Бейджи, выданные по удалённому правилу, пропадают у всех клиентов — показывать нечего
Порядок показа — из каталога	Бейджи в карточке и кабинете идут в порядке поля `ordinal`, а не в порядке получения

Удаление необратимо

Форма удаления правила предупреждает: «Удалить достижение? Бейджи, выданные по нему, пропадут у всех клиентов». Чтобы прекратить выдачу, но сохранить уже выданное клиентам, используйте переключатель «Выдаётся», а не удаление.

Пересчёт задним числом¶

Если правило завели, когда часть клиентов уже выполнила условие, они не получат бейдж автоматически — им нужна следующая операция с баллами. Чтобы не ждать, оператор с ролью LOYALTY_ACHIEVEMENT_WRITE запускает пересчёт на вкладке «Достижения» карточки клиента (кнопка «Пересчитать»). Пересчёт идемпотентен: повторный запуск не выдаёт уже полученные бейджи повторно.

Экран администратора¶

Администрирование → Достижения — таблица правил без пагинации (список приходит целиком).

Колонка	Содержание
Бейдж	Значок, название и код
Условие	Условие человеческой фразой, например «10 покупок» или «Уровень Золотой»
Порядок	Значение `ordinal`
Выдаётся	Переключатель `active` прямо в таблице
—	Кнопки «Изменить» и «Удалить» (с подтверждением)

Кнопка «Завести достижение» открывает форму. Второе поле условия зависит от выбранного типа: для условий-величин показывается числовой порог («Сколько раз» / «Сколько (в баллах или рублях)»), для «Достигнут уровень» — выбор уровня из каталога. Показывать оба поля сразу нельзя: сохраняется только то, что относится к выбранному условию.

Единицы ввода

Порог для условий в баллах или рублях вводится в мажорных единицах (баллы/рубли), как удобно маркетологу; на сервер он уходит в минорных.

Отображение клиенту¶

Карточка клиента (оператор)¶

Карточка клиента → категория «Клиент» → вкладка «Достижения». Бейджи показаны плиткой: значок, название, описание (если задано) и дата получения; при наведении на дату — значение показателя на момент выдачи («На момент выдачи — …»). Если бейджей нет, показывается пустое состояние — вкладка не скрывается, чтобы было видно, что фича есть. На вкладке доступна кнопка «Пересчитать» (LOYALTY_ACHIEVEMENT_WRITE). Ручной выдачи бейджа нет: он всегда выдаётся правилом.

Личный кабинет клиента (B2C)¶

На главном экране кабинета под балансом — раздел «Достижения» с бейджами клиента: значок и название (описание — во всплывающей подсказке). В отличие от карточки оператора, раздел не показывается вовсе, если у клиента нет ни одного бейджа — пустая полка достижений в кабинете не несёт смысла.

REST API¶

Метод и путь	Назначение	Права
`GET /v1/admin/achievements`	Каталог правил	`LOYALTY_ACHIEVEMENT_READ`
`GET /v1/admin/achievements/{id}`	Правило по id	`LOYALTY_ACHIEVEMENT_READ`
`POST /v1/admin/achievements`	Завести правило	`LOYALTY_ACHIEVEMENT_WRITE`
`PUT /v1/admin/achievements/{id}`	Изменить правило (замена целиком)	`LOYALTY_ACHIEVEMENT_WRITE`
`DELETE /v1/admin/achievements/{id}`	Удалить правило (уносит выданные бейджи)	`LOYALTY_ACHIEVEMENT_WRITE`
`GET /v1/customers/{externalId}/achievements`	Бейджи клиента (карточка оператора)	`LOYALTY_PROFILE_READ`
`POST /v1/customers/{externalId}/achievements/recheck`	Пересчитать достижения клиента	`LOYALTY_ACHIEVEMENT_WRITE`
`GET /v1/b2c/me/achievements`	Бейджи участника (кабинет)	Контур B2C, см. Личный кабинет клиента (B2C)

Коды ошибок¶

Код	HTTP	Когда
`achievement_not_found`	404	Правило с таким `id` не найдено
`achievement_code_taken`	409	Код правила уже занят другим достижением
`achievement_condition_invalid`	422	Нераспознанный тип условия, отсутствующий/неположительный порог для условия-величины, отсутствующий код уровня для «Достигнут уровень»

См. также¶

Реферальная программа
Уровни (тиры) — источник кода уровня для условия «Достигнут уровень»