Баланс не должен уменьшаться побочным UPDATE рядом с возвратом денег. Найдите исходную операцию начисления и создайте для возвращённых строк компенсирующую проводку. Баланс тогда остаётся суммой ledger, а история отвечает на вопрос, почему число изменилось. Это особенно важно при частичном возврате: нельзя вычитать все баллы заказа, если покупатель вернул один товар.

Триггером служит подтверждённое бизнес-событие, а не открытие формы возврата. У объекта refund могут быть отдельные платёжные транзакции и их статусы, поэтому политика должна явно сказать, когда сторнировать награду: при принятии товара, при проведении документа или после успешной выплаты. Главное — одно правило для всех каналов и возможность увидеть его в журнале.

Баланс восстанавливается из проводок

reward +120  source=sale:1042/line:7
spend   -80  source=order:1188
reversal -60 source=refund:81/line:7 reverses=reward:501

balance = sum(posted ledger entries)

Не удаляйте reward:501 и не переписывайте его значение. Отрицательная запись reversal сохраняет дату, причину и связь с возвратом. При отмене ошибочного возврата создаётся ещё одна компенсирующая проводка, а не ручное редактирование прошлого. Такой след можно пересчитать и объяснить службе поддержки.

Частичный возврат повторяет экономику исходной строки

СитуацияСколько сторнироватьЧто сохранить
Одна из двух одинаковых единицДолю начисления одной единицыquantity и правило округления
Товар с общей скидкойБаллы с учётом распределённой скидкиисходную eligible amount
Возврат доставкиПо правилам программы, часто нольтип возвращённой суммы
Промо с порогом заказаПо зафиксированной политике кампанииcampaign version и решение
Несколько возвратов одной строкиТолько ещё не сторнированный остатоксумму прошлых reversal

Не пересчитывайте старую покупку по сегодняшним правилам лояльности. Сохраните reward policy version, eligible amount и результат расчёта при продаже. Иначе после изменения кампании один и тот же возврат даст другой результат, а полное сторно нескольких частей не сойдётся с исходным начислением.

Повтор webhook упирается в уникальный ключ

Платёжный провайдер или очередь может прислать одно событие повторно. Stripe рекомендует ключи идемпотентности для безопасного повтора POST-запросов; внутри loyalty-сервиса нужен такой же принцип. Составьте source_event_id из стабильного refund ID и позиции, а в базе запретите вторую проводку того же типа для того же события.

  • Уникальное ограничение охватывает program_id, source_event_id и adjustment_type.
  • Проверка «сначала SELECT, потом INSERT» без ограничения не защищает от гонки.
  • Вся пачка line items и запись обработанного события живут в одной транзакции.
  • Retry после таймаута читает уже созданные проводки и возвращает тот же результат.
  • Неизвестная исходная продажа уходит в retry или ручную очередь, а не в молчаливый success.

PostgreSQL реализует unique constraints на уровне базы и тем самым закрывает одновременные обработчики, которые оба считают событие новым. Обработайте конфликт как ожидаемый повтор. В логах достаточно source ID, типа записи и результата; email, номер телефона и полный состав заказа там не нужны.

Потраченные баллы требуют продуктового решения

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

В интерфейсе покажите покупателю две строки: сумма возврата денег и изменение баллов, с понятной причиной. Оператору нужны исходное начисление, reversal, текущий баланс и версия правил. Ручное исправление оформляется отдельной adjustment entry с автором и комментарием, а не прямым UPDATE balance.

Тест покрывает не только счастливый путь

  1. Вернуть одну позицию заказа с несколькими товарами и общей скидкой.
  2. Доставить одно событие дважды параллельно и получить одну reversal entry.
  3. Сначала потратить баллы, затем вернуть товар и проверить выбранную политику долга.
  4. Отменить возврат и выполнить явную компенсацию сторно.
  5. Пересчитать баланс из ledger и сравнить его с быстрым агрегатом профиля.

Для диагностики подготовьте цепочку из исходной reward entry, возврата с line items, входного event ID, всех compensating entries и результата SUM. Такой набор сразу показывает, событие не дошло, не нашло основание, было пропущено из-за статуса или обработалось без уникальной защиты.

Проверенные источники