mostovik-backend/docs/adr/ADR-016: Background Job Tracking and Operational Recovery Model.md

ADR-016: Background Job Tracking and Operational Recovery Model

Status

Accepted

Context

Система использует фоновые задачи для:

• парсинга данных
• синхронизации источников
• обработки файлов

Возможны сценарии:

• задача упала
• задача зависла
• задача выполнилась частично
• задача была запущена повторно
• оператору нужно вручную перезапустить процесс

Без модели трекинга задач:

• невозможно понять состояние системы
• невозможно безопасно повторить операцию
• сложно диагностировать ошибки

Decision

Вводится явная модель отслеживания фоновых задач (BackgroundJob).

Основные свойства задачи

Каждая задача должна иметь:

• тип (parser / sync / file processing)
• источник данных
• период или файл
• статус
• время запуска
• время завершения
• результат (успех / ошибка / частично)
• контекст выполнения

Статусы задач

Минимальный набор:

• pending
• running
• completed
• failed
• partial

Правила выполнения

1. Каждая бизнес-операция должна быть трассируема через job.
2. Повторный запуск не должен создавать конфликтов (см. ADR-011).
3. Статус задачи должен отражать реальное состояние, а не "успешно/не успешно".
4. Частичный успех должен фиксироваться явно.

Recovery model

Система должна позволять:

• повторный запуск задачи за тот же период
• повторную обработку файла
• безопасный re-run без очистки БД
• диагностику причины ошибки через лог и статус

Manual operations

Администратор должен иметь возможность:

• увидеть список задач
• понять их состояние
• повторно запустить задачу
• увидеть ошибки

Integration with Celery

• Celery отвечает за выполнение
• BackgroundJob — за бизнес-трекинг
• ID задачи Celery связывается с доменной задачей

Consequences

Positive

• прозрачность фоновых процессов
• управляемость ETL
• возможность безопасного восстановления
• упрощение эксплуатации

Negative

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

Alternatives considered

1. Полагаться только на Celery task state

Отклонено — недостаточно для бизнес-анализа и recovery.

2. Отсутствие трекинга задач

Отклонено — делает систему неуправляемой.