mostovik-backend/docs/adr/ADR-011: Idempotency and Retry Strategy.md

# ADR-011: Idempotency and Retry Strategy for Background Tasks

## Status
Accepted

## Context

Система активно использует фоновые задачи Celery для:
- загрузки данных из внешних источников
- инкрементальной синхронизации
- обработки файлов
- периодических сканирований и парсинга

Внешние источники и фоновые очереди не гарантируют:
- exactly-once delivery
- стабильность сети
- неизменность ответа источника
- отсутствие повторных запусков задач
- отсутствие ручных перезапусков оператором

Также возможны следующие сценарии:
- worker завершился после частичной записи данных
- задача была запущена повторно по retry
- beat и ручной запуск вызвали одинаковую задачу почти одновременно
- внешняя система ответила ошибкой после того, как часть данных уже была получена
- оператор повторно инициировал синхронизацию за тот же период

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

## Decision

Все фоновые задачи, изменяющие данные или взаимодействующие с нестабильными внешними источниками, должны проектироваться как idempotent-first.

### Основные правила

1. Повторный запуск одной и той же задачи не должен приводить к неконтролируемому дублированию данных.
2. Результат повторного выполнения должен быть либо:
   - идентичен первому успешному выполнению,
   - либо безопасно приводить систему к тому же целевому состоянию.
3. Retry рассматривается как нормальный сценарий эксплуатации, а не как исключение.

### Идемпотентность обеспечивается за счет

- уникальных ограничений на уровне БД для естественных бизнес-ключей
- upsert/update-or-create подходов там, где это возможно
- явной привязки загружаемых данных к периоду, источнику, типу выгрузки или внешнему идентификатору
- дедупликации на уровне сервисного слоя перед записью
- разделения этапов extract / transform / load
- фиксации статуса фоновой задачи и контекста её выполнения
- запрета на "append-only" запись без проверки уникальности для синхронизируемых сущностей

### Retry policy

Retry допускается только для временных ошибок:
- сетевые сбои
- временная недоступность внешнего источника
- rate limiting
- временные ошибки брокера или инфраструктуры
- временные проблемы с файловой системой или внешним сервисом

Retry не должен безусловно выполняться для:
- ошибок валидации входных данных
- ошибок схемы/контракта источника
- систематических ошибок парсинга
- нарушений инвариантов модели
- ошибок конфигурации

Для retry необходимо:
- использовать ограниченное число повторов
- использовать backoff
- логировать причину повтора
- сохранять контекст периода/источника/операции

### Concurrency policy

Для задач, работающих по одному и тому же периоду или источнику, должна применяться логическая защита от параллельного конкурентного запуска.

Предпочтительный порядок контроля:
1. блокировка на уровне бизнес-контракта задачи
2. проверка существующего job-run статуса
3. защита уникальными ограничениями БД
4. безопасное повторное выполнение как fallback

### Operational policy

Задача считается корректной, если после:
- retry
- повторного ручного запуска
- запуска за уже обработанный период
- частичного падения и повторного восстановления

данные остаются консистентными и не требуют ручной чистки в обычном сценарии эксплуатации.

## Consequences

### Positive

- система устойчива к повторным запускам и временным отказам
- снижается риск дублирования данных
- упрощается эксплуатация и ручной re-run задач
- Celery retry становится безопасным штатным механизмом
- упрощается восстановление после сбоев worker-процессов

### Negative

- усложняется реализация сервисного слоя и моделей
- требуется дисциплина в проектировании бизнес-ключей
- часть задач становится медленнее из-за дополнительных проверок
- нужны дополнительные ограничения и индексы в БД
- необходимо явно проектировать поведение при partial success

## Alternatives considered

### 1. At-most-once execution
Отклонено, так как не соответствует реальной природе фоновой обработки и нестабильных внешних интеграций.

### 2. Полагаться только на Celery retry без идемпотентности на уровне домена
Отклонено, так как это приводит к дублированию данных и хрупкому поведению при сбоях.

### 3. Полная ручная очистка данных перед каждым повторным запуском
Отклонено, так как не масштабируется и опасно в эксплуатации.

## Notes

Следующими связанными решениями должны быть:
- политика дедупликации данных
- модель частичной загрузки и фиксации прогресса
- политика конкурентного запуска задач