Возьмите одну тестовую заявку и проследите поле reason от браузера до повторного чтения из базы. На каждом шаге сравните стабильный код, свободную заметку и идентификатор позиции возврата. Если в POST код есть, а в доменной команде уже null, исправлять форму или отчёт бессмысленно: потеря произошла в mapping или в списке разрешённых полей.
Храните не подпись из выпадающего списка, а машинный reason code или ID справочника. Подпись может переводиться и меняться; исторический возврат должен сохранить исходный смысл. Для варианта OTHER нужна отдельная заметка, но она не заменяет категорию и не должна перезаписывать её пустой строкой.
Пять снимков показывают точное место потери
| Точка | Что сравнить | Типичный дефект |
|---|---|---|
| Форма перед отправкой | reason_code, reason_note, line_item_id | Поле отключено и не попало в payload |
| HTTP request | JSON и Content-Type | Клиент отправляет reasonCode, API ждёт reason_code |
| Доменная команда | Нормализованное значение | Allowlist выбросил новое поле |
| Запрос к БД | Параметр и затронутые строки | UPDATE не включает колонку или сработал старый upsert |
| Read model/экспорт | Значение после нового SELECT | Запись есть, но serializer или JOIN её скрывает |
Логируйте эти снимки под одним request ID, но не пишите туда персональные данные из комментария клиента. Для диагностики достаточно названия поля, обезличенного кода, длины заметки, return ID и результата операции. Отдельно проверьте массовый импорт и административную форму: они нередко используют другой DTO.
Код причины и текст для человека решают разные задачи
Shopify в актуальной модели возвратов разделяет стандартизированную причину и дополнительную заметку. У определения есть стабильный handle, пригодный для программной логики, а отображаемое имя локализуется. Это полезный ориентир и для собственной системы: аналитика группирует по коду, интерфейс показывает локализованную подпись, оператор видит заметку отдельно.
return_item = {
"id": "ri_demo_42",
"reason_code": "WRONG_ITEM",
"reason_note": "Получена другая модель",
"reason_catalog_version": 7,
"changed_by": "user_demo"
}В платёжном API набор причин может быть уже, чем в товарном возврате. Например, Stripe описывает ограниченный enum для Refund. Не пытайтесь бездумно передать внутренние двадцать категорий в одно внешнее поле: сделайте явное отображение, а исходную товарную причину сохраните у себя.
Сохранение заявки и причины делают одной операцией
Если заявка создаётся, а reason записывается вторым запросом, сбой между ними оставляет допустимую с точки зрения базы, но неполную запись. Оберните создание return, его line items, причину и audit event в одну транзакцию. PostgreSQL описывает транзакцию как all-or-nothing блок: при ошибке промежуточные изменения не становятся видны другим сессиям.
- Сервер отклоняет неизвестный reason code и не подменяет его на UNKNOWN молча.
- Для OTHER проверяется непустая заметка; для остальных категорий заметка остаётся необязательной.
- UPDATE содержит версию записи или условие состояния, чтобы поздний ответ не затёр новое решение.
- Количество изменённых строк проверяется до COMMIT, а ноль считается конфликтом.
- Audit event хранит прежний и новый код, автора, время и источник команды.
Повтор запроса не должен очищать уже записанное
Особенно опасен retry с неполным payload. Клиент повторяет старую команду без reason_note, serializer превращает отсутствие поля в null, а универсальный UPDATE очищает колонку. Различайте «поле не передано» и «пользователь явно очистил значение». Для идемпотентного create используйте стабильный operation ID и возвращайте созданный объект вместо второго изменения.
Проверьте и фоновые синхронизации. Внешняя система может прислать статус возврата без причины, после чего upsert перезапишет локальные данные. Настройте ownership полей: статус обновляется провайдером, внутренняя классификация — вашей системой, а конфликт фиксируется в журнале.
История переживает изменение справочника
Категорию можно переименовать или убрать из новых форм, но старые возвраты должны оставаться объяснимыми. Не удаляйте использованный код физически: пометьте его неактивным и запретите для новых заявок. Shopify аналогично указывает, что удалённые определения причин не следует показывать новым клиентам, хотя они могут оставаться в существующих возвратах.
В отчёте считайте по стабильному ID/handle и присоединяйте текущую подпись только для отображения. Если бизнесу важна формулировка на момент решения, храните snapshot label или версию справочника. Так изменение перевода не переписывает смысл уже закрытого периода.
Контрольный тест проходит весь круг чтения
- Создать возврат с обычной причиной и с OTHER плюс заметка.
- Повторить тот же request с тем же operation ID и убедиться, что дубль не возник.
- Прочитать запись через API менеджера, экспорт и аналитический запрос.
- Изменить только статус и проверить, что причина осталась прежней.
- Отключить код в справочнике и убедиться, что старый возврат всё ещё отображается.
Для разбора подготовьте обезличенный payload, схему DTO, SQL или ORM diff, сохранённую строку и audit events одного return ID. Комментарий клиента замените тестовой фразой. По этой цепочке видно, поле не записалось, было очищено повтором или потерялось только в представлении.