Aleksandr Meshchriakov
25176f31b4
Some checks failed
CI/CD Pipeline / Telegram Notify Success (push) Has been cancelled
CI/CD Pipeline / Run Tests (push) Has been cancelled
CI/CD Pipeline / Code Quality Checks (push) Has been cancelled
CI/CD Pipeline / Code Quality Checks (pull_request) Successful in 1m42s
CI/CD Pipeline / Run Tests (pull_request) Successful in 2m25s
CI/CD Pipeline / Telegram Notify Success (pull_request) Successful in 1m34s
119 lines
6.9 KiB
Markdown
119 lines
6.9 KiB
Markdown
# ADR-013: Parser Stability and Source Change Detection for External Sources
|
||
|
||
## Status
|
||
Accepted
|
||
|
||
## Context
|
||
|
||
Система зависит от внешних источников данных, которые находятся вне зоны контроля команды:
|
||
- государственные порталы
|
||
- HTML-страницы
|
||
- JS-heavy интерфейсы
|
||
- файловые выгрузки
|
||
- SOAP/API интеграции
|
||
- Excel/XML источники
|
||
|
||
Эти источники подвержены изменениям:
|
||
- меняется DOM-структура
|
||
- меняются URL и маршруты
|
||
- меняются названия полей
|
||
- меняется формат выгрузки
|
||
- появляются новые обязательные поля
|
||
- меняются ограничения доступа
|
||
- изменяется поведение клиентского JavaScript
|
||
|
||
Для системы такого типа изменение внешнего источника является не исключением, а ожидаемым операционным событием.
|
||
|
||
## Decision
|
||
|
||
Проект принимает стратегию parser instability as expected.
|
||
|
||
Это означает:
|
||
- каждый внешний источник считается потенциально нестабильным
|
||
- отказ парсера по причине изменения источника рассматривается как ожидаемый класс инцидента
|
||
- архитектура должна облегчать локализацию, диагностику и восстановление интеграции
|
||
|
||
### Архитектурные правила
|
||
|
||
1. Каждый источник должен быть изолирован в собственном parser/client/service слое.
|
||
2. Логика получения данных из источника не должна быть размазана по нескольким доменам без явной границы.
|
||
3. Изменение одного источника не должно ломать остальные интеграции.
|
||
4. Парсер должен быть максимально отделён от логики сохранения данных.
|
||
5. Нормализация и запись в БД не должны зависеть от деталей DOM/HTML/XML конкретного источника.
|
||
|
||
### Change detection policy
|
||
|
||
Система должна позволять определить, что проблема вызвана именно изменением внешнего источника, а не внутренней ошибкой приложения.
|
||
|
||
Минимально необходимы:
|
||
- явное логирование этапа сбоя
|
||
- логирование URL, периода, типа выгрузки или источника
|
||
- различение сетевых ошибок, ошибок структуры ответа и ошибок сохранения
|
||
- сохранение диагностического контекста для повторного анализа
|
||
|
||
### Playwright policy
|
||
|
||
Playwright допускается для источников, где:
|
||
- критическая логика формируется на клиенте
|
||
- прямой HTTP scraping недостаточен
|
||
- требуется JS rendering или пользовательская навигация
|
||
|
||
При этом Playwright считается более хрупкой интеграционной точкой по сравнению с HTTP/API клиентами.
|
||
|
||
Для Playwright-based интеграций принимаются дополнительные ограничения:
|
||
- сценарий навигации должен быть максимально коротким
|
||
- DOM-селекторы должны быть минимально хрупкими
|
||
- логика парсинга должна быть отделена от логики браузерной навигации
|
||
- fallback или быстрая диагностика деградации обязательны
|
||
|
||
### Resilience policy
|
||
|
||
При изменении внешнего источника система должна:
|
||
- завершать конкретную задачу контролируемой ошибкой
|
||
- не повреждать уже сохранённые данные
|
||
- не маскировать сбой как успешную синхронизацию
|
||
- сохранять возможность повторного запуска после исправления
|
||
|
||
### Ownership policy
|
||
|
||
Каждая интеграция с внешним источником должна иметь:
|
||
- понятную точку входа
|
||
- понятный набор задач
|
||
- понятный формат выходных данных
|
||
- наблюдаемый статус выполнения
|
||
|
||
## Consequences
|
||
|
||
### Positive
|
||
|
||
- уменьшается связность между интеграциями
|
||
- упрощается ремонт конкретного источника
|
||
- проще локализовать причину отказа
|
||
- снижается риск каскадного повреждения всей системы
|
||
- повышается операционная предсказуемость
|
||
|
||
### Negative
|
||
|
||
- возрастает количество прикладного кода и адаптеров
|
||
- приходится поддерживать отдельные контракты на источник
|
||
- растут требования к логированию и smoke-проверкам
|
||
- интеграции невозможно считать "написал один раз и забыл"
|
||
|
||
## Alternatives considered
|
||
|
||
### 1. Общий универсальный парсер для разных источников
|
||
Отклонено, так как источники сильно отличаются по протоколу, структуре и стабильности.
|
||
|
||
### 2. Встраивание логики источников прямо в задачи или view-слой
|
||
Отклонено, так как это увеличивает связность и ухудшает сопровождаемость.
|
||
|
||
### 3. Опора только на "ручное замечание", что парсер сломался
|
||
Отклонено, так как это не соответствует требованиям эксплуатационной зрелости.
|
||
|
||
## Notes
|
||
|
||
Следующим развитием данного решения должны быть:
|
||
- smoke checks для критичных источников
|
||
- классификация типов ошибок интеграции
|
||
- runbook для восстановления парсеров после изменения внешних порталов
|