Кабинет возврата не должен быть красивой копией 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 return | order.customer_id = session.user_id | 404 либо разрешённый объект |
| скачать label | возврат принадлежит пользователю и label активен | короткоживущая ссылка |
| изменить заявку | статус ещё разрешает редактирование | 409 при позднем этапе |
| отменить | нет принятой перевозчиком посылки | новое событие cancelled |
| support view | роль и tenant совпадают | аудируемый служебный доступ |
Интеграции записывают события через inbox и outbox
Webhook перевозчика или платёжной системы сначала сохраняется как входящее событие с уникальным provider event ID, а затем обрабатывается. Если обработчик упал после записи, повтор не создаст второе движение статуса. Исходящее уведомление покупателю помещается в outbox той же транзакции, что и смена состояния: письмо не должно уйти раньше commit или потеряться после него.
События могут прийти не по порядку. `received` от склада не отменяют поздним дублем `in_transit`; обработчик сравнивает версию агрегата и допустимость перехода. Неизвестный event сохраняют в карантин для разбора, а не переводят возврат в универсальный `error`.
Кабинет тестируют как цепочку, а не пять экранов
- Создать частичный возврат и дважды отправить одинаковый запрос с одним idempotency key.
- Открыть URL возврата под другим тестовым пользователем и убедиться, что данных нет.
- Повторить webhook перевозчика и проверить единственное событие в хронологии.
- Доставить события не по порядку: `received`, затем старое `in_transit`.
- Одобрить одну позицию и отклонить другую, сверить суммы и подписи в интерфейсе.
- Сымитировать timeout платёжного API и повтор job без второго refund.
- Проверить письмо, push и кабинет: они должны ссылаться на одну версию статуса.
Для проектирования подготовьте схему заказа, правила допустимого количества, статусы склада, примеры webhook без персональных данных и варианты refund. Готовый кабинет считается надёжным, когда повтор любого запроса не меняет итог, чужой пользователь не видит объект, а каждая фраза на таймлайне подтверждается сохранённым событием.