Статистика акций¶

Модуль ведёт сводную проекцию применения акций — счётчики акций по статусам, число применений и начисленные баллы. Эта проекция обслуживает дашборд «Мониторинг бонусов» и колонки «Применений» и «Начислено» каталога акций и доступна через REST API. Все операции раздела — только чтение, право LOYALTY_PROMOTION_READ.

Что измеряется¶

Статистика опирается на факт применения акции к покупке: каждое применение увеличивает счётчик применений соответствующей акции и сумму начисленных по ней баллов. Параллельно считаются акции каталога по статусам.

Счётчики ведутся по версии акции: новая версия и копия акции начинают с нуля. Сводные суммы (totalApplications, totalBonusMinor) складывают все версии.
Сторнированное начисление остаётся применением: счётчик применений назад не отматывается.

Баллы и деньги в минорных единицах

bonusMinor — начисленные баллы в минорных единицах (целое число: 15000 = 150,00 балла). budgetMinor — бюджет акции в деньгах (минорные единицы рубля): начисление пересчитывается в деньги по курсу баллов на момент начисления. При курсе балла, равном 1 ₽, значения численно совпадают.

Где видно в интерфейсе¶

На дашборде «Мониторинг бонусов»:

карточка «Количество активных акций» — счётчик статуса «Активна»;
таблица «Топ акций по начислениям» — до 10 акций с наибольшими начислениями; колонки «Акция», «Статус», «Применений», «Начислено», «Бюджет / расход» (бюджет и доля израсходованного).

В каталоге акций — колонки «Применений», «Начислено» и «Расход бюджета». Они скрыты по умолчанию и включаются в настройке таблицы (шестерёнка «Настроить таблицу»); сортировки по ним нет. Быстрый просмотр строки показывает «Бюджет акции» и «Израсходовано».

Точный расход бюджета конкретной акции показывает её карточка — строка «Израсходовано X из Y» (при исчерпании — «Бюджет исчерпан…»); он считается по журналу начислений за вычетом сторно и по всей линии версий акции. См. Ограничения и лимиты акции.

Показатели акций за выбранный период — применения, участники, покупки, выручка, начислено и израсходовано — собраны в разделе «Отчёты», вкладка «Акции».

Одно название — одно число

Колонки каталога и поля ответа по одной акции показывают одни и те же величины: «Применений» и «Начислено» — по версии акции, «Расход бюджета» — по линии версий, потому что бюджет задаётся линии; он же — «Израсходовано» в быстром просмотре и в карточке акции. «Начислено» — баллы, «Расход бюджета» — деньги. У акции без применений — нули, а не прочерк.

Эндпоинты¶

Метод и путь	Назначение	Право
`GET /v1/promotions/stats`	Сводная статистика по всем акциям	`LOYALTY_PROMOTION_READ`
`GET /v1/promotions/{id}/stats`	Статистика одной акции по её идентификатору	`LOYALTY_PROMOTION_READ`
`GET /v1/promotions`, `GET /v1/promotions/{id}`	Статистика в составе акции: строки каталога и ответ по одной акции	`LOYALTY_PROMOTION_READ`

Запросы без необходимой роли отклоняются; неизвестный идентификатор акции — 404 promotion_not_found.

Сводная статистика¶

GET /v1/promotions/stats возвращает агрегированную картину по всему каталогу акций.

Структура ответа:

Поле	Тип	Описание
`statusCounts`	объект	Количество акций по статусам (см. ниже)
`totalPromotions`	число	Общее число акций (всех версий) в каталоге
`totalApplications`	число	Суммарное число применений по всем акциям
`totalBonusMinor`	число	Суммарно начислено баллов (минорные единицы)
`top`	массив	До 10 акций с наибольшими начислениями (строки того же вида, что и у одной акции)

Разбивка по статусам (statusCounts):

Поле	Описание
`draft`	Черновики
`scheduled`	Запланированные
`active`	Активные
`paused`	На паузе
`completed`	Завершённые
`archived`	Акции с признаком архива

Архив пересекается со статусами

Архив — не статус, а отдельный признак (Жизненный цикл). Архивная акция на паузе учтена и в paused, и в archived. Сумма статусов равна общему числу акций; archived к ней не прибавляется.

{
  "statusCounts": {
    "draft": 3,
    "scheduled": 1,
    "active": 12,
    "paused": 2,
    "completed": 46,
    "archived": 40
  },
  "totalPromotions": 64,
  "totalApplications": 18204,
  "totalBonusMinor": 9120500,
  "top": [
    {
      "promotionId": 1042,
      "name": "Кешбэк 5% на топливо",
      "status": "ACTIVE",
      "applications": 8120,
      "bonusMinor": 4060000,
      "budgetMinor": 10000000
    }
  ]
}

Статистика одной акции¶

GET /v1/promotions/{id}/stats возвращает показатели конкретной версии акции.

Поле	Тип	Описание
`promotionId`	число	Идентификатор акции
`name`	строка	Наименование акции
`status`	строка	Текущий статус акции (`DRAFT`, `SCHEDULED`, `ACTIVE`, `PAUSED`, `COMPLETED`)
`applications`	число	Число применений акции
`bonusMinor`	число	Начислено баллов по акции (минорные единицы)
`budgetMinor`	число / `null`	Бюджет акции в деньгах (минорные единицы); `null`, если бюджет не задан

curl -H "Authorization: Bearer <JWT>" \
  https://<host>/v1/promotions/1042/stats

{
  "promotionId": 1042,
  "name": "Кешбэк 5% на топливо",
  "status": "ACTIVE",
  "applications": 8120,
  "bonusMinor": 4060000,
  "budgetMinor": 10000000
}

Бюджет — необязательное поле

Поле budgetMinor может быть пустым (null): акция может действовать без ограничения бюджета. В этом случае контроль расхода по данной акции не ведётся.

Статистика в составе акции¶

Строки каталога (GET /v1/promotions) и ответ по одной акции (GET /v1/promotions/{id}) несут три поля статистики. В каталоге они собираются для всей страницы сразу, а не запросом на каждую строку.

Поле	Тип	Описание
`applications`	число	Число применений этой версии акции
`bonusMinor`	число	Начислено баллов по этой версии (минорные единицы)
`budgetSpentMinor`	число	Израсходовано бюджета по всей линии версий — в деньгах (минорные единицы), начисления минус сторно, каждое по курсу на момент начисления