Баланс не должен уменьшаться побочным 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.
Тест покрывает не только счастливый путь
- Вернуть одну позицию заказа с несколькими товарами и общей скидкой.
- Доставить одно событие дважды параллельно и получить одну reversal entry.
- Сначала потратить баллы, затем вернуть товар и проверить выбранную политику долга.
- Отменить возврат и выполнить явную компенсацию сторно.
- Пересчитать баланс из ledger и сравнить его с быстрым агрегатом профиля.
Для диагностики подготовьте цепочку из исходной reward entry, возврата с line items, входного event ID, всех compensating entries и результата SUM. Такой набор сразу показывает, событие не дошло, не нашло основание, было пропущено из-за статуса или обработалось без уникальной защиты.