XML-пайплайн

XML-пайплайн — единый многоэтапный процесс загрузки данных из внешнего YML XML-фида поставщика (формат Яндекс.Маркет). Он заменил разрозненную обработку XML: фид скачивается один раз за прогон, сохраняется снепшот сырых данных, ведётся история запусков и доступны ручные переопределения картинок.

Код находится в пакете back/.../sync/pipeline/. Планировщик — XmlFeedPipelineOrchestrator.scheduledSync() (@Scheduled(fixedDelay = 5 мин), флаг xml_feed_pipeline_enabled).

---

Этапы

Перечень этапов задан в XmlFeedPipelineStage:

DOWNLOAD → PARSE → ATTRIBUTE_SYNC → CATEGORY_MAPPING → IMAGE_QUEUE

Этап	Что делает
DOWNLOAD	Скачивает XML по xml-feed.url, распаковывает gzip, срезает UTF-8 BOM, считает SHA-256. Если хеш не изменился — последующие этапы пропускаются
PARSE	Парсит XML и сохраняет снепшот: офферы (xml_feed_offer_raw) и категории (xml_feed_category_raw)
ATTRIBUTE_SYNC	Применяет правила атрибутов, пишет в xml_feed_staging и обновляет AUTO-атрибуты товаров
CATEGORY_MAPPING	Сопоставляет категории фида с категориями БД, активирует/скрывает товары, фиксирует привязку (category_locked_by_gbstore)
IMAGE_QUEUE	Ставит товары в очередь скрейпинга изображений (с учётом переопределений)

Запуск можно ограничить подмножеством этапов (например, только ATTRIBUTE_SYNC).

---

Запуск пайплайна

Запуск асинхронный — API сразу возвращает runId (HTTP 202 Accepted), а прогон выполняется в фоне.

POST /api/v1/admin/xml-pipeline/run
Body (опционально):
{
  "stages": ["DOWNLOAD", "PARSE", "ATTRIBUTE_SYNC"],   // по умолчанию — все
  "forceRefetch": true,                                 // игнорировать совпадение хеша
  "snapshotId": 42                                       // переиспользовать готовый снепшот
}
→ { "runId": 123 }

Прогресс по этапам транслируется в админку по WebSocket (/ws/xml-pipeline).

---

История запусков

Каждый прогон фиксируется в xml_feed_pipeline_run: триггер (SCHEDULED / MANUAL), запрошенные этапы, статус (RUNNING / COMPLETED / FAILED), время, ссылка на снепшот и сообщение об ошибке. Результат по каждому этапу — в xml_feed_stage_result (статус, сводка, ошибка).

GET /api/v1/admin/xml-pipeline/runs           # список (постранично, по убыванию даты)
GET /api/v1/admin/xml-pipeline/runs/{id}      # детали прогона со сводкой по этапам

---

Снепшоты

Снепшот (xml_feed_snapshot) — распарсенные данные одного прогона: офферы и категории. Каждый оффер хранит params_json и фрагмент исходного XML — это позволяет инспектировать данные без повторного скачивания фида.

GET /api/v1/admin/xml-pipeline/snapshots                  # список
GET /api/v1/admin/xml-pipeline/snapshots/latest           # последний
GET /api/v1/admin/xml-pipeline/snapshots/{id}/offers      # офферы (постранично, поиск)
GET /api/v1/admin/xml-pipeline/snapshots/{id}/categories  # категории

---

Переопределения картинок

Если изображения для товара спарсились неверно или отсутствуют, их можно задать вручную в xml_feed_image_override:

Режим	Поведение
REPLACE	Игнорировать спарсенные картинки, использовать только указанные
APPEND	Добавить указанные картинки после спарсенных

GET    /api/v1/admin/xml-pipeline/image-overrides
POST   /api/v1/admin/xml-pipeline/image-overrides
PUT    /api/v1/admin/xml-pipeline/image-overrides/{id}
DELETE /api/v1/admin/xml-pipeline/image-overrides/{id}

Переопределения применяются на этапе IMAGE_QUEUE.

---

Очистка

XmlFeedCleanupService ежедневно в 02:00 удаляет старые прогоны, снепшоты, офферы, категории и результаты этапов (с учётом срока хранения). Ручной запуск:

POST /api/v1/admin/xml-pipeline/cleanup
→ { "runs": N, "snapshots": N, "offers": N, "categories": N, "stageResults": N }

---

Старый эндпоинт синхронизации фида

Для совместимости сохранён прямой запуск без истории запусков:

POST /api/v1/admin/xml-feed/sync?resetCache=true     # синк атрибутов, resetCache сбрасывает хеш
POST /api/v1/admin/xml-feed/apply-category-mapping   # маппинг категорий GBStore
GET  /api/v1/admin/xml-feed/param-names              # имена параметров из staging с количеством
POST /api/v1/admin/xml-feed/diagnostic               # диагностика состояния фида

Эти эндпоинты используются страницей Диагностика XML (/admin/xml-diagnostic). Все требуют роль ADMIN/SUPER_ADMIN.

---

Админ-интерфейс

Страница /admin/xml-pipeline содержит вкладки: Дашборд (этапы текущего прогона), История запусков, Снепшоты (с просмотром сырого XML) и Переопределения картинок.