feat(admin): шкала загрузки источников, отладка и загрузка работ в корпус

Заливка корпуса была чёрным ящиком: у источника только last_status
(idle/running/done/error), без «сколько из скольки», без причины падения и без
способа остановить начатое. Теперь каждый запуск создаёт строку parse_runs,
куда воркер раз в ~2с пишет стадию, счётчики и журнал событий.

Админка:
- шкала загрузки у каждого источника (0→50% выборка, 50→100% индексация),
  раскрытая строка — журнал прогона по шагам с таймингами;
- «Запустить всё» / «Остановить всё» и остановка по одному источнику
  (кооперативная отмена: воркер останавливается сам, не рвя запись в базу);
- пакетное добавление источников (тип + список тем), тип pmc в форме;
- загрузка PDF/DOCX/TXT прямо в базу сравнения (index.ingest_upload);
- страница «Отладка»: воркеры Celery и их текущие таски, очереди RabbitMQ,
  покрытие корпуса эмбеддингами, зависшие и упавшие прогоны, конфиг бэкендов.

Защита от краш-лупа по consumer_timeout RabbitMQ (docs/DR-HA.md §6), без неё
массовый запуск 170+ источников гарантированно ронял воркер:
- PARSER_TIME_BUDGET_S (1500с) — прогон закругляется сам и помечается partial;
- worker_prefetch_multiplier=1 — таймаут считается от ДОСТАВКИ сообщения, и с
  дефолтным префетчем очередь долгих run_parser убивала канал на задачах,
  которые ещё не начинались.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

scripts/parsers/arxiv.py

@@ -12,7 +12,7 @@ import xml.etree.ElementTree as ET
 from typing import Any
 
 import httpx
-from base import BaseParser
+from base import BaseParser, ProgressCallback
 
 logger = logging.getLogger(__name__)
 
@@ -46,6 +46,7 @@ class ArxivParser(BaseParser):
         limit: int = 500,
         categories: list[str] | None = None,
         year_from: int | None = None,
+        progress_cb: ProgressCallback | None = None,
     ) -> list[dict[str, Any]]:
         """
         Получить препринты из arXiv.
@@ -55,6 +56,7 @@ class ArxivParser(BaseParser):
             limit: Максимальное количество документов
             categories: Список категорий arXiv (cs.AI, math.ST и т.д.)
             year_from: Год публикации от
+            progress_cb: см. base.ProgressCallback
 
         Returns:
             Список сырых словарей
@@ -94,6 +96,10 @@ class ArxivParser(BaseParser):
                 results.extend(entries)
                 start += len(entries)
 
+                if progress_cb and not progress_cb(min(len(results), limit)):
+                    logger.info(f"arXiv: выборка остановлена по запросу (получено {len(results)})")
+                    break
+
                 if len(entries) < max_results:
                     break
 

scripts/parsers/base.py

@@ -6,11 +6,19 @@
 import json
 import logging
 from abc import ABC, abstractmethod
+from collections.abc import Callable
 from pathlib import Path
 from typing import Any
 
 logger = logging.getLogger(__name__)
 
+# Колбэк прогресса выборки: вызывается после каждой страницы результатов с
+# накопленным количеством документов. Возврат False — просьба остановиться
+# (кооперативная отмена из админки или исчерпанный бюджет времени таска,
+# см. worker-indexer/app/progress.py). Парсер обязан вернуть уже собранное,
+# а не бросать исключение: частичная выборка — валидный результат.
+ProgressCallback = Callable[[int], bool]
+
 
 # Унифицированный формат документа
 UNIFIED_SCHEMA = {
@@ -45,7 +53,10 @@ class BaseParser(ABC):
         Получить сырые документы из источника.
 
         Args:
-            **kwargs: Специфичные для источника параметры (query, limit и т.д.)
+            **kwargs: Специфичные для источника параметры (query, limit и т.д.).
+                Все парсеры принимают ещё и `progress_cb` (ProgressCallback) —
+                отчёт о прогрессе после каждой страницы и точка кооперативной
+                остановки.
 
         Returns:
             Список сырых словарей из API источника

scripts/parsers/cyberleninka.py

@@ -16,7 +16,7 @@ import time
 from typing import Any
 
 import httpx
-from base import BaseParser
+from base import BaseParser, ProgressCallback
 
 logger = logging.getLogger(__name__)
 
@@ -47,6 +47,7 @@ class CyberLeninkaParser(BaseParser):
         query: str = "",
         limit: int = 500,
         subject: str | None = None,
+        progress_cb: ProgressCallback | None = None,
     ) -> list[dict[str, Any]]:
         """
         Получить статьи из КиберЛенинки.
@@ -55,6 +56,7 @@ class CyberLeninkaParser(BaseParser):
             query: Поисковый запрос
             limit: Максимальное количество статей
             subject: Предметная область (опционально)
+            progress_cb: см. base.ProgressCallback
 
         Returns:
             Список сырых словарей статей
@@ -85,6 +87,12 @@ class CyberLeninkaParser(BaseParser):
                 results.extend(items)
                 page += 1
 
+                if progress_cb and not progress_cb(min(len(results), limit)):
+                    logger.info(
+                        f"КиберЛенинка: выборка остановлена по запросу (получено {len(results)})"
+                    )
+                    break
+
                 if len(items) < 10:
                     break
 

scripts/parsers/openalex.py

@@ -15,7 +15,7 @@ from collections.abc import Generator
 from typing import Any
 
 import httpx
-from base import BaseParser
+from base import BaseParser, ProgressCallback
 
 logger = logging.getLogger(__name__)
 
@@ -45,6 +45,7 @@ class OpenAlexParser(BaseParser):
         year_to: int | None = None,
         type_filter: str = "article",
         open_access_only: bool = False,
+        progress_cb: ProgressCallback | None = None,
     ) -> list[dict[str, Any]]:
         """
         Получить документы из OpenAlex.
@@ -58,6 +59,7 @@ class OpenAlexParser(BaseParser):
             type_filter: Тип документа (journal-article, book, и т.д.)
             open_access_only: только open-access работы (is_oa:true) — резко
                 повышает долю статей с доступным PDF (для наполнения корпуса)
+            progress_cb: см. base.ProgressCallback
 
         Returns:
             Список сырых словарей из OpenAlex API
@@ -74,6 +76,9 @@ class OpenAlexParser(BaseParser):
             open_access_only=open_access_only,
         ):
             results.extend(page)
+            if progress_cb and not progress_cb(min(len(results), limit)):
+                logger.info("OpenAlex: выборка остановлена по запросу (получено %d)", len(results))
+                break
             if len(results) >= limit:
                 break
 

scripts/parsers/pmc.py

@@ -17,7 +17,7 @@ import xml.etree.ElementTree as ET
 from typing import Any
 
 import httpx
-from base import BaseParser
+from base import BaseParser, ProgressCallback
 
 logger = logging.getLogger(__name__)
 
@@ -52,6 +52,7 @@ class PMCParser(BaseParser):
         limit: int = 500,
         year_from: int | None = None,
         year_to: int | None = None,
+        progress_cb: ProgressCallback | None = None,
     ) -> list[dict[str, Any]]:
         """
         Получить статьи из PMC Open Access Subset.
@@ -61,6 +62,7 @@ class PMCParser(BaseParser):
             limit: Максимальное количество документов
             year_from: Год публикации от
             year_to: Год публикации до
+            progress_cb: см. base.ProgressCallback
 
         Returns:
             Список сырых словарей (уже с извлечёнными метаданными + full_text)
@@ -85,6 +87,9 @@ class PMCParser(BaseParser):
                 )
                 response.raise_for_status()
                 results.extend(self._parse_articles(response.text))
+                if progress_cb and not progress_cb(min(len(results), limit)):
+                    logger.info(f"PMC: выборка остановлена по запросу (получено {len(results)})")
+                    break
                 time.sleep(RATE_LIMIT_DELAY)
             except httpx.HTTPStatusError as e:
                 logger.error(f"PMC efetch HTTP ошибка: {e.response.status_code}")

scripts/parsers/tests/test_progress_cb.py

@@ -0,0 +1,68 @@
+"""Контракт progress_cb у парсеров: отчёт по страницам и остановка по запросу.
+
+Сеть не трогаем — подменяем HTTP-клиент парсера заглушкой. Проверяем то, на что
+опирается заливка: воркер видит рост выборки и может остановить парсер, не
+дожидаясь конца (отмена из админки, исчерпанный бюджет времени таска).
+"""
+
+from typing import Any
+
+from cyberleninka import CyberLeninkaParser
+
+
+class FakeResponse:
+    def __init__(self, payload: dict[str, Any]) -> None:
+        self._payload = payload
+
+    def raise_for_status(self) -> None:
+        pass
+
+    def json(self) -> dict[str, Any]:
+        return self._payload
+
+
+class FakeClient:
+    """Отдаёт бесконечные полные страницы по 10 статей — как большая выдача."""
+
+    def __init__(self) -> None:
+        self.calls = 0
+
+    def post(self, url: str, json: dict[str, Any]) -> FakeResponse:
+        self.calls += 1
+        start = json["from"]
+        return FakeResponse({
+            "articles": [{"id": start + i, "name": f"статья {start + i}"} for i in range(10)]
+        })
+
+
+def _parser(monkeypatch) -> CyberLeninkaParser:
+    p = CyberLeninkaParser()
+    p.client = FakeClient()  # type: ignore[assignment]
+    monkeypatch.setattr("cyberleninka.RATE_LIMIT_DELAY", 0)
+    return p
+
+
+def test_progress_cb_reports_growing_count(monkeypatch):
+    p = _parser(monkeypatch)
+    seen: list[int] = []
+
+    docs = p.fetch(query="x", limit=30, progress_cb=lambda n: seen.append(n) or True)
+
+    assert len(docs) == 30
+    assert seen == [10, 20, 30]
+
+
+def test_progress_cb_false_stops_fetch_early(monkeypatch):
+    p = _parser(monkeypatch)
+
+    # Останавливаем после второй страницы — как отмена прогона из админки
+    docs = p.fetch(query="x", limit=1000, progress_cb=lambda n: n < 20)
+
+    assert len(docs) == 20
+    assert p.client.calls == 2  # type: ignore[attr-defined]
+
+
+def test_fetch_works_without_callback(monkeypatch):
+    """Скрипты заливки зовут парсеры без progress_cb — поведение прежнее."""
+    p = _parser(monkeypatch)
+    assert len(p.fetch(query="x", limit=20)) == 20

scripts/run_lint.sh

@@ -24,10 +24,10 @@ docker run --rm \
     echo '▶ ruff (services/ scripts/)'
     ruff check services/ scripts/
 
-    echo '▶ mypy (чистая логика L1/L2 + ГОСТ + скоринг + OAuth)'
-    ( cd services/worker-indexer && mypy --config-file /repo/mypy.ini app/algorithms/ app/fragments.py app/staging.py )
+    echo '▶ mypy (чистая логика L1/L2 + ГОСТ + скоринг + OAuth + прогресс заливки)'
+    ( cd services/worker-indexer && mypy --config-file /repo/mypy.ini app/algorithms/ app/fragments.py app/staging.py app/progress.py )
     ( cd services/worker-gost && mypy --config-file /repo/mypy.ini app/formatters/ app/bibliography.py )
     ( cd services/worker-gpu && mypy --config-file /repo/mypy.ini app/scoring.py )
-    ( cd services/api && mypy --config-file /repo/mypy.ini app/core/oauth.py )
+    ( cd services/api && mypy --config-file /repo/mypy.ini app/core/oauth.py app/core/progress.py )
   "
 echo "✅ Линт (ruff + mypy) пройден"