# ADR-0017. Баллы за действия

- Статус: принято; реализовано на этапе 6 — ✅ 6m-1 (модуль `activities`, Runtime API, Management API, вебхуки), ✅ 6m-2
  (раздел «Баллы за действия» в кабинете мерчанта, начисления в карточке и истории участника)
- Дата: 2026-10-12

## Контекст

Программа лояльности начисляет баллы не только за покупки: за отзыв, за пройденный опрос, за подписку на соцсети
(п. 6.7 roadmap, решение владельца продукта от 2026-10-06). О таком действии знает только сайт или приложение мерчанта:
оно и сообщает платформе, что участник его совершил. Нужно, чтобы одно событие не оплачивалось дважды (сайт повторяет
запрос, отзыв приходит снова), чтобы участник не получал баллы за действие чаще, чем задумал мерчант («за отзыв —
50 баллов, раз в месяц»), чтобы утечка ключа сайта не раздала баллы без меры и чтобы баллы можно было забрать, если отзыв
не прошёл модерацию. Кассе такие начисления не нужны: на кассе баллы дают покупки.

## Решение

### Действия — отдельный список программы

- Условия действий хранятся в модуле `activities` (таблица `activities` под RLS), а не в правилах программы (ADR-0007):
  действие меняется сразу, без публикации правил, второго фактора и блокировки программы, и не трогает расчёт чеков.
  Владелец продукта выбрал это 2026-10-12. Каждое начисление сохраняет условия, по которым дано: баллы — в строке
  начисления, срок их жизни — в партии баллов леджера.
- Действие — это код, который присылает сайт (`^[a-z0-9][a-z0-9_-]{0,63}$`), и тип баллов программы; оба навсегда, и код
  занят даже у архивного действия. Условия: название, баллы одного начисления (минимальные единицы, 1…10¹²), срок жизни
  баллов (`LifecycleRules`, как у бонусов: через N дней после доступности, в календарную дату или без покупок;
  задержка доступности), лимит участника — N раз (1…1000) за день, неделю с понедельника, месяц, год в часовом поясе
  программы или за всё время — и необязательный бюджет баллов (не меньше одного начисления). Баллы одного начисления
  фиксированы: сайт не выбирает сумму.
- Статусы: активно, приостановлено (сообщения получают 409 `activity_inactive`), архив — навсегда (условия не
  меняются, 409 `activity_state_conflict`); начисления архивного действия остаются, их можно отменить. Приостановить
  действие может и приостановленный мерчант: его сайт сообщает о действиях и тогда, а приостановка только защищает
  (`RequireMerchant::WRITES_WHILE_SUSPENDED`). У программы не больше 100 действий, архивные тоже; действия одной
  программы создаются по одному (advisory-блокировка программы).

### Начисление

- Сайт сообщает: `POST /api/v1/members/{member}/activities` с кодом действия и `event_id` — непрозрачным
  идентификатором события в своей системе (отзыва, ответа), 1–100 символов латиницы, цифр и `._:/-`: e-mail так не
  записать, а телефон и имя сайт не пишет туда по договору API.
- Начисление идёт в одной транзакции, которая держит участника (`Members::lockPresent`: обезличивание ждёт, и никакое
  начисление не переживает его данные) и строку действия (`FOR UPDATE`): начисления одного действия идут по одному,
  поэтому одновременные сообщения не обходят ни лимит участника, ни бюджет, а одно событие вознаграждается один раз.
  Строка действия считает баллы начислений, которые не забраны отменой (`rewarded_points`), всегда — бюджет, заданный
  позже, учитывает и прежние начисления. Проверки по порядку: программа активна (иначе 422 `program_unavailable`),
  участник этой программы, активный или замороженный (заблокированный и любой статус, которого ещё нет, — 409
  `member_blocked`, обезличенный — как не найденный), правила опубликованы; затем действие активно, событие ещё не
  вознаграждалось (409 `activity_already_reported`; `reward_id` — только своего начисления этого участника, по нему
  сайт выясняет судьбу запроса без ответа, чужое начисление не называется), лимит периода не исчерпан, бюджет
  позволяет.
- Начисление — операция леджера `accrue` (ADR-0003) с ключом `activity:{reward}`, ссылкой `activity` на начисление,
  исполнителем-кассой ключа (сервер сайта) и точкой; срок жизни — по условиям действия в часовом поясе программы.
  Строка `activity_rewards` неизменна, кроме отмены; удалять строки рабочим ролям нельзя (лимит считает строки периода).
- Отмена: `POST /api/v1/activity-rewards/{reward}:cancel` — `reverseAccrual` по политике программы для потраченных баллов
  (как при возврате бонусов). Сколько баллов забрано, хранится в начислении (`reversed_points`) и столько же
  возвращается в бюджет. Отменённое начисление остаётся в лимите участника за период, а его событие не вознаграждается
  снова: при политике, которая оставляет потраченное участнику, круг «сообщение — трата — отмена» иначе платил бы без
  меры. Повторная отмена отвечает начислением как есть. Отмена берёт сначала строку действия, затем строку начисления,
  и счета участника в леджере — последними, как и начисление; участника она не держит, поэтому блокировки не ждут друг
  друга по кругу.
- `GET /api/v1/activities` показывает сайту активные действия программы — чтобы он написал «50 баллов за отзыв»; действие,
  бюджет которого не вместит ещё одно начисление, или с архивным типом баллов не показывается.

### Кто может сообщать

- Новый скоуп ключа Runtime API `activities` получают только ключи касс вида `ecommerce`, `mobile_app` и `integration`
  (`ApiScope::SERVER_TERMINALS`, тот же список, что у `presentation_codes`), никогда — ключ кассы или веб-кассы: он
  раздавал бы баллы без покупки. Скоуп не входит в набор по умолчанию.

### Аудит и интеграции

- Начисления и отмены Runtime API — сами по себе след: операция леджера хранит исполнителя (кассу ключа), ссылку и
  время, строка начисления — событие сайта. Изменения действий через Management API пишутся в журнал аудита
  (`activities.*`, ADR-0010); в кабинете (6m-2) — тоже.
- События `activity.rewarded` и `activity.reversed` (только идентификаторы и сумма, ADR-0005) уходят в вебхуки.
- Management API: `GET|POST /programs/{program}/activities`, `GET|PUT /activities/{activity}`,
  `POST /activities/{activity}:activate|:pause|:archive` (скоуп `programs`).

### Кабинет мерчанта (6m-2)

- Раздел «Баллы за действия» в «Программе лояльности» (ADR-0014). Условия меняются без публикации правил, поэтому то,
  что запускает выплату баллов или меняет её, — создать действие, изменить условия, возобновить — требует права
  `campaigns.publish` со вторым фактором, как публикация акции, и недоступно через доступ поддержки. Отправить в архив —
  `campaigns.manage`; приостановить — отдельное право `activities.pause`. Оно только защищает, поэтому есть и у
  приостановленного мерчанта (ADR-0015), как `POST /activities/{activity}:pause` в Management API.
- Кабинет сохраняет условия только поверх тех, с которыми открылась форма (`Activities::update` с `basedOn`); Management
  API заменяет их целиком, как есть.
- В карточке участника — последние 20 начислений за действия; в истории баллов — название действия у начисления и
  отмены.

## Последствия

- Мерчант запускает действие за минуту и меняет его сразу; ошибка в условиях не требует новой версии правил.
- Начисления одного действия не идут параллельно. Для отзывов и опросов это незаметно; если действие станет массовым
  (тысячи сообщений в секунду), счётчик бюджета придётся вынести из строки действия.
- Сайт отвечает за `event_id`: одно событие — один идентификатор; повтор с тем же `Idempotency-Key` отвечает сохранённым
  ответом, повтор события с новым ключом — 409 с `reward_id`. Отзыв, отклонённый модерацией и затем одобренный, не
  получит баллы снова под тем же событием: отмену делают, когда решение окончательное.
- Все ключи сайта, приложения и интеграций программы равны: любой из них отменяет начисление программы. Ключ стороннего
  сервиса с этим скоупом получает то же доверие.
- Начисления за действия видны в «Сводке» как «бонусы и другое» (всё, что начислено не за чек).
