feat: expand platform APIs, sources, and test coverage

docs/adr/ADR-013: Parser Stability Strategy.md

@@ -0,0 +1,118 @@
+# 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 для восстановления парсеров после изменения внешних порталов