Возврат и уведомление — две разные операции. Если деньги уже подтверждены платёжным провайдером, не нажимайте «вернуть» повторно: найдите refund ID, затем отдельно проверьте outbox, задачу отправки и событие email-провайдера. Повторять можно письмо, но не финансовую команду.
Надёжная схема создаёт запись уведомления при переходе refund в финальный статус и присваивает ей собственный ключ, например `refund_succeeded:{refund_id}:{locale}`. Это позволяет безопасно перезапустить worker и увидеть, на каком участке исчезло сообщение.
Четыре статуса вместо одного флага sent
| Слой | Контрольный идентификатор | Что подтверждает |
|---|---|---|
| Платёжный провайдер | refund ID | Фактический status и сумма возврата |
| Transactional outbox | notification key | Событие зафиксировано вместе с локальным статусом |
| Email API | provider message ID | Провайдер принял запрос на отправку |
| Delivery event | message ID + recipient | Сервер получателя принял письмо либо вернул bounce |
| Клиентский интерфейс | refund ID | Пользователь видит актуальное состояние независимо от email |
Ответ `200` от email API обычно означает приём задачи, а не появление письма во входящих. Amazon SES, например, публикует отдельные delivery, bounce, complaint и delivery-delay events. Сохраните их рядом с message ID, чтобы оператор не угадывал результат по одному полю.
Outbox появляется в транзакции со статусом
BEGIN
UPDATE refunds SET status = confirmed WHERE id = :refund_id
INSERT INTO notification_outbox(
key, type, aggregate_id, state
) VALUES (
refund_succeeded:{refund_id}:ru, refund_succeeded, :refund_id, pending
) ON CONFLICT (key) DO NOTHING
COMMITWorker берёт pending-запись, загружает шаблон и контакт из актуального разрешённого источника, отправляет письмо и сохраняет provider message ID. Если процесс упал после запроса, повтор сначала проверяет сохранённый результат или использует стабильный idempotency key там, где API это поддерживает.
Причина находится по последней успешной точке
- Нет outbox — переход refund не вызвал доменное событие или транзакция откатилась.
- Outbox pending — worker остановлен, завис lease или исчерпаны попытки.
- Email API rejected — адрес, шаблон, sandbox или политика провайдера не прошли проверку.
- Provider accepted без delivery — ждите итоговый event и смотрите delivery delay.
- Delivery есть, клиент не видит письмо — проверьте spam, threading и неверный адрес в snapshot.
Не помещайте полный email и содержимое письма в общий технический лог. Для поиска достаточно hash/внутреннего contact ID, provider message ID, template version, locale и кода результата. Доступ к расшифровке адреса должен быть отдельным.
Повторная отправка не переписывает историю
Кнопка оператора создаёт новую delivery attempt для существующего notification key. Она не меняет время возврата и не маскирует первый bounce. В интерфейсе полезно показать «возврат подтверждён» и отдельно «письмо: ошибка адреса / доставлено / ожидает».
Если адрес исправили, сохраните новый recipient snapshot только для новой попытки и запишите, кто её запустил. Старое сообщение остаётся в аудите без повторного включения персональных данных в текст события.
Приёмка включает недоставляемый адрес
В тесте проведите успешный refund, повтор того же webhook, временную ошибку email API и hard bounce. Должен существовать один возврат, одно логическое уведомление и несколько нумерованных попыток доставки. Личный кабинет показывает финансовый результат даже при постоянной ошибке почты.
Для разбора подготовьте обезличенные refund status transitions, outbox key, message ID, коды delivery events и версию шаблона. API-ключи, подписи webhook и реальный адрес клиента передавать не нужно.