1. Проблема: двойная запись

Нужно одновременно сохранить задачу в базу данных и доставить сообщение в очередь обработки. Это две разные системы, и атомарность между ними отсутствует: процесс может упасть между записью в БД и публикацией сообщения. Результат — задача сохранена, но никогда не будет обработана (или наоборот: сообщение «улетело», а записи нет).

Transactional Outbox устраняет разрыв: сообщение о событии записывается в обычную таблицу outbox в той же базе и в той же транзакции, что и бизнес-данные. Атомарность гарантирует сама СУБД. Отдельный фоновый процесс (relay) вычитывает неопубликованные сообщения и доставляет их обработчику.

2. Интерактивная карта потока

UML sequence-диаграмма полного жизненного цикла задачи в этом сервисе. Кликните шаг на диаграмме — под ней появится описание и фрагмент кода из репозитория. Или управляйте шагами кнопками.

3. UML: диаграмма состояний задачи

Жизненный цикл задачи от создания до результата. Кликните состояние, чтобы узнать, что оно означает и какой код переводит задачу в него.

4. UML: архитектура решения

Пять проектов решения и их зависимости (стрелка = «ссылается на»). Кликните проект, чтобы увидеть его ответственность и ключевые типы.

5. Inbox: почему повторная доставка не страшна

Relay помечает сообщение опубликованным после отправки в канал. Если процесс упадёт между этими действиями, при перезапуске сообщение уйдёт в обработку ещё раз — это и есть семантика at-least-once. Чтобы дубли не приводили к повторному выполнению работы, у обработчика есть inbox: таблица с уникальным индексом по MessageId. Первая доставка вставляет запись, повторная — получает отказ от СУБД, и обработка молча прекращается.

Сообщение, которое циркулирует в системе, — JSON-конверт:

{
  "messageId": "8f3c2a41-…",      // ключ дедупликации в inbox
  "taskId": "a1b2c3d4-…",         // какая задача обрабатывается
  "envelopeType": "ProcessTask",
  "payloadJson": "{\"taskId\":\"a1b2c3d4-…\",\"payload\":\"…\"}"
}

6. Повторы с экспоненциальной задержкой и dead letter

Если ITaskExecutor бросил исключение, задача не теряется: она возвращается в очередь с LastError и NextAttemptAt = сейчас + 2с · 2ⁿ, а в outbox создаётся новое сообщение. После исчерпания попыток (MaxAttempts = 5) задача попадает в dead letter с причиной и числом попыток — её можно вернуть в очередь кнопкой Replay (POST /api/dead-letters/{id}/replay).

Для проверки политики в payload можно передать failUntilAttempt — количество попыток, завершающихся ошибкой, прежде чем задача выполнится успешно:

curl -X POST http://localhost:8080/api/tasks \
  -H "Content-Type: application/json" \
  -d '{
        "payload": "{\"note\":\"демо ретраев\",\"failUntilAttempt\":3}",
        "runAt": "2026-10-11T12:00:00Z",
        "idempotencyKey": "order-42"
      }'

# первые две попытки упадут, третья выполнится успешно;
# наблюдать статусы: GET /api/tasks и страница «Задачи»

7. Где что в коде