Кабинет возврата не должен быть красивой копией CRM. Покупателю нужен один достоверный ответ: где сейчас товар, требуется ли действие и когда изменится денежный результат. Для этого возврат хранится отдельной сущностью, связанной со строками исходного заказа, а не одним полем `order.return_status`.

Безопасный первый шаг — собрать список событий от склада, перевозчика и платёжного провайдера. Если статус нельзя подтвердить событием, временем и источником, его нельзя обещать в интерфейсе. В частности, «товар получен» и «возврат денег выполнен» относятся к разным процессам.

Один заказ может породить несколько возвратов

СущностьЧто хранитПочему отдельно
Orderснимок покупки и покупателяне меняется из-за каждой посылки назад
Returnзаявку, решение, публичный статусу заказа возможны частичные возвраты
Return itemстроку заказа, количество, причинунельзя вернуть больше купленного остатка
Reverse shipmentтрек, перевозчика, приёмкудоставка живёт по своей шкале
Refundсумму, валюту, provider ID и результатденьги могут прийти после проверки товара
Eventкто, что и когда изменилистория объясняет текущее состояние

Такую модель можно увидеть и в Shopify Admin GraphQL: Return связан с Order, содержит return line items, refunds и собственный status. Это не готовая схема для копирования, а полезная проверка границ: намерение вернуть товар, физическая обработка и финансовый возврат не являются одним полем.

Публичная шкала короче внутреннего процесса

requested -> approved -> in_transit -> received -> inspecting -> completed
          \-> declined
approved  \-> cancelled
received  \-> partial_refund -> completed

Внутри склада могут быть десятки кодов, но покупателю достаточно устойчивых этапов. Переход разрешает backend после события: сотрудник одобрил заявку, перевозчик принял отправление, склад зарегистрировал приёмку, платёжный провайдер подтвердил refund. Нельзя переходить в `completed` только потому, что задача на возврат денег поставлена в очередь.

  • Рядом со статусом показывайте время последнего подтверждённого события и ожидаемое следующее действие.
  • Для declined храните публичную причину отдельно от внутренней заметки сотрудника.
  • Для частичного возврата перечисляйте принятые и отклонённые позиции, а не усредняйте результат.
  • Не меняйте прошлые события задним числом; корректировку добавляйте новым событием.
  • Сроки показывайте только там, где магазин действительно измеряет SLA.

Повторный клик не создаёт вторую посылку

POST /api/returns
Idempotency-Key: 9a4d...

{
  "order_id": "ord_public_83K",
  "items": [{"line_id": "line_2", "quantity": 1}],
  "reason": "size"
}

Idempotency key связывают с пользователем, операцией и хэшем тела запроса. Повтор с тем же ключом и тем же телом возвращает созданный Return; тот же ключ с другим телом отклоняется как конфликт. Дополнительно база запрещает вернуть суммарно больше доступного количества. Эти две проверки закрывают двойной клик, повтор после timeout и параллельные вкладки.

Знание номера возврата не даёт доступ

Проверка владельца выполняется на сервере при каждом чтении документа, трека или статуса. OWASP относит доступ к объекту только по изменяемому ID к IDOR: непрозрачный UUID уменьшает угадывание, но не заменяет authorization. Запрос строится от текущего пользователя к его заказам и только затем к возврату.

ЗапросОбязательная проверкаБезопасный ответ
GET returnorder.customer_id = session.user_id404 либо разрешённый объект
скачать labelвозврат принадлежит пользователю и label активенкороткоживущая ссылка
изменить заявкустатус ещё разрешает редактирование409 при позднем этапе
отменитьнет принятой перевозчиком посылкиновое событие cancelled
support viewроль и tenant совпадаютаудируемый служебный доступ

Интеграции записывают события через inbox и outbox

Webhook перевозчика или платёжной системы сначала сохраняется как входящее событие с уникальным provider event ID, а затем обрабатывается. Если обработчик упал после записи, повтор не создаст второе движение статуса. Исходящее уведомление покупателю помещается в outbox той же транзакции, что и смена состояния: письмо не должно уйти раньше commit или потеряться после него.

События могут прийти не по порядку. `received` от склада не отменяют поздним дублем `in_transit`; обработчик сравнивает версию агрегата и допустимость перехода. Неизвестный event сохраняют в карантин для разбора, а не переводят возврат в универсальный `error`.

Кабинет тестируют как цепочку, а не пять экранов

  1. Создать частичный возврат и дважды отправить одинаковый запрос с одним idempotency key.
  2. Открыть URL возврата под другим тестовым пользователем и убедиться, что данных нет.
  3. Повторить webhook перевозчика и проверить единственное событие в хронологии.
  4. Доставить события не по порядку: `received`, затем старое `in_transit`.
  5. Одобрить одну позицию и отклонить другую, сверить суммы и подписи в интерфейсе.
  6. Сымитировать timeout платёжного API и повтор job без второго refund.
  7. Проверить письмо, push и кабинет: они должны ссылаться на одну версию статуса.

Для проектирования подготовьте схему заказа, правила допустимого количества, статусы склада, примеры webhook без персональных данных и варианты refund. Готовый кабинет считается надёжным, когда повтор любого запроса не меняет итог, чужой пользователь не видит объект, а каждая фраза на таймлайне подтверждается сохранённым событием.

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