Строка «изменение баланса: −20» не объясняет клиенту, что произошло. Найдите для неё исходное событие: покупку, использование награды, возврат, истечение срока или ручную корректировку. Если такой связи нет в данных, переименование строки интерфейса причину не восстановит. Начните с одной операции и пройдите от её эффекта к основанию.
Полезная история отвечает на три вопроса: сколько изменилось, почему и к чему относится изменение. Служебный идентификатор помогает поддержке найти запись, но не заменяет понятный текст. Не показывайте клиенту внутреннюю трассировку или комментарии сотрудника, которые не предназначены для публикации.
Что относится к факту, а что — к объяснению
| Данные операции | Для чего нужны | Что видит клиент |
|---|---|---|
| Тип и величина эффекта | Проверить движение баллов | Начислено, использовано или скорректировано |
| Основание и связь с заказом | Найти источник изменения | Ссылка на доступную ему покупку |
| Версия правила | Воспроизвести расчёт | Краткое основание по действовавшим условиям |
| Автор корректировки | Служебный аудит | Согласованная причина без внутренних заметок |
Square Loyalty ведёт журнал событий изменения баланса и описывает разные типы с соответствующими метаданными. В примере ручной корректировки есть поле reason. Это свойство конкретного API, а не готовая универсальная схема вашего магазина. Документация проверена 20 октября 2026 года; собственный контракт объяснения всё равно нужно определить отдельно.
Почему текст нельзя собирать из текущего правила
Предположим, раньше начислялся один процент, а после изменения программы — другой. Историческая покупка должна объясняться принятой тогда редакцией, даже если страница условий уже обновилась. Сохраняйте необходимые основания расчёта в разрешённом объёме и ссылку на редакцию. Не нужно копировать в историю весь заказ с персональными данными.
Условный контракт, не название готового API:
effect_id: устойчивый идентификатор
reason_code: PURCHASE_RETURN
reference: исходная операция / покупка
rule_revision: действовавшая редакция
delta: изменение в единицах программы
occurred_at: момент события
recorded_at: момент регистрацииРазные времена полезны для поздно пришедшего события: покупка совершена вчера, а импорт завершился сегодня. В интерфейсе назовите, по какому времени упорядочены строки. Для одинакового времени предусмотрите устойчивый дополнительный порядок, иначе пагинация может повторять или пропускать операции. Сумму до и после показывайте только при определённом порядке применения эффектов.
Неизвестная причина — отдельный исход
Для старых записей без связей честнее показать «корректировка, основание уточняется», если это соответствует данным, чем автоматически объявить их возвратами. Разделите записи с доказанным основанием, неоднозначные совпадения и записи без источника. Совпавшая сумма соседнего заказа сама по себе не подтверждает связь. Миграцию объяснений сначала проверяют на копии.
- Клик по покупке открывает только доступный клиенту заказ.
- Повтор одного события не создаёт вторую строку эффекта.
- Неизвестный код получает безопасное объяснение, а не пустую строку.
- Ручная операция имеет обязательную служебную причину.
- Возврат и исправление ошибки не смешиваются под одним названием.
Отдельно испытайте отмену корректировки: новая запись должна объяснять связь с предыдущей, сохраняя исходный факт. Если меняется только словарь отображения, он не должен менять величину баланса. У поддержки останется опорный набор: ID эффекта, тип основания, доступная ссылка и редакция правила. С него и стоит начать ремонт истории, прежде чем перерисовывать весь личный кабинет.