mostovik-backend/docs/adr/ADR-012: Data Consistency Model.md

ADR-012: Data Consistency and Partial Load Model

Status

Accepted

Context

Система загружает данные из внешних государственных и смежных источников, которые могут:

• быть нестабильны
• отдавать большие объёмы данных
• завершаться по таймауту
• менять формат ответа
• содержать частично поврежденные записи
• быть доступны только частично на момент синхронизации

Загрузка может выполняться:

• по периоду
• по файлам
• по внешним реестрам
• в инкрементальном режиме

На практике возможно частичное успешное выполнение:

• часть записей уже сохранена, часть ещё нет
• файл обработан наполовину
• один источник за период обработался, второй — нет
• FZ-248 успешно загружен, а FZ-294 завершился ошибкой
• часть данных валидна, часть — нет

Без явной модели частичной загрузки система становится трудно восстанавливаемой и операционно непрозрачной.

Decision

Проект принимает модель controlled partial progress.

Это означает:

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

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

1. Единицей согласованности является не "вся система целиком", а отдельная операция загрузки:

   • период
   • файл
   • тип источника
   • подтип данных
   • конкретная синхронизационная задача

2. Частичная загрузка допустима только если:

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

3. Полный rollback всей загрузки не является обязательным требованием. Вместо этого используется повторяемая и безопасная модель дозагрузки/перезапуска.

Модель фиксации состояния

Для каждой операции загрузки система должна уметь определить:

• что именно загружалось
• за какой период или из какого файла
• когда началась обработка
• завершилась ли она успешно
• была ли частичная ошибка
• можно ли безопасно повторить запуск

Предпочтительная гранулярность статусов:

• pending
• running
• partial
• failed
• completed

Правила работы с частичными данными

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

Периодическая синхронизация

Для периодических источников (например, месячные загрузки):

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

Работа с файлами

Для file-based ingestion:

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

Consequences

Positive

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

Negative

• модель состояний усложняется
• требуется более аккуратный job tracking
• появляется необходимость различать "partial" и "failed"
• возрастает ответственность сервисного слоя за корректную фиксацию статусов

Alternatives considered

1. Полная транзакционность всей синхронизации

Отклонено, так как для больших и внешних ETL-процессов это дорого, хрупко и часто нереализуемо.

2. Игнорировать частичный прогресс и считать любую ошибку полным провалом

Отклонено, так как приводит к потере уже обработанного полезного результата и затрудняет recovery.

3. Append-only ingestion без статусов операции

Отклонено, так как делает систему непрозрачной и плохо сопровождаемой.

Notes

Это решение напрямую зависит от:

• ADR-011 Idempotency and Retry Strategy
• ADR-013 Parser Stability and Source Change Detection