Строка «изменение баланса: −20» не объясняет клиенту, что произошло. Найдите для неё исходное событие: покупку, использование награды, возврат, истечение срока или ручную корректировку. Если такой связи нет в данных, переименование строки интерфейса причину не восстановит. Начните с одной операции и пройдите от её эффекта к основанию.

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

Что относится к факту, а что — к объяснению

Данные операцииДля чего нужныЧто видит клиент
Тип и величина эффектаПроверить движение балловНачислено, использовано или скорректировано
Основание и связь с заказомНайти источник измененияСсылка на доступную ему покупку
Версия правилаВоспроизвести расчётКраткое основание по действовавшим условиям
Автор корректировкиСлужебный аудитСогласованная причина без внутренних заметок

Square Loyalty ведёт журнал событий изменения баланса и описывает разные типы с соответствующими метаданными. В примере ручной корректировки есть поле reason. Это свойство конкретного API, а не готовая универсальная схема вашего магазина. Документация проверена 20 октября 2026 года; собственный контракт объяснения всё равно нужно определить отдельно.

Почему текст нельзя собирать из текущего правила

Предположим, раньше начислялся один процент, а после изменения программы — другой. Историческая покупка должна объясняться принятой тогда редакцией, даже если страница условий уже обновилась. Сохраняйте необходимые основания расчёта в разрешённом объёме и ссылку на редакцию. Не нужно копировать в историю весь заказ с персональными данными.

Условный контракт, не название готового API:
effect_id: устойчивый идентификатор
reason_code: PURCHASE_RETURN
reference: исходная операция / покупка
rule_revision: действовавшая редакция
delta: изменение в единицах программы
occurred_at: момент события
recorded_at: момент регистрации

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

Неизвестная причина — отдельный исход

Для старых записей без связей честнее показать «корректировка, основание уточняется», если это соответствует данным, чем автоматически объявить их возвратами. Разделите записи с доказанным основанием, неоднозначные совпадения и записи без источника. Совпавшая сумма соседнего заказа сама по себе не подтверждает связь. Миграцию объяснений сначала проверяют на копии.

  • Клик по покупке открывает только доступный клиенту заказ.
  • Повтор одного события не создаёт вторую строку эффекта.
  • Неизвестный код получает безопасное объяснение, а не пустую строку.
  • Ручная операция имеет обязательную служебную причину.
  • Возврат и исправление ошибки не смешиваются под одним названием.

Отдельно испытайте отмену корректировки: новая запись должна объяснять связь с предыдущей, сохраняя исходный факт. Если меняется только словарь отображения, он не должен менять величину баланса. У поддержки останется опорный набор: ID эффекта, тип основания, доступная ссылка и редакция правила. С него и стоит начать ремонт истории, прежде чем перерисовывать весь личный кабинет.

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