feat: add gear provenance models and browser fetcher

2026-09-20 15:50:43 +07:00
parent b0edae98c6
commit 4e9895fbf4
19 changed files with 986 additions and 20 deletions
@@ -76,6 +76,37 @@ Fallback строится на собственных лёгких SVG: осмы

 Координат, проводки, времени поимки и устойчивого внешнего идентификатора записи в этой таблице нет. Локализация зависит от домена/языка страницы: проверенная `.de`-страница возвращает немецкие названия рыб, водоёмов и приманок даже для региона RU.

+## Ручное получение snapshots водоёмов
+
+Для ручного запуска используется [`scripts/fetch-waterbodies.py`](../scripts/fetch-waterbodies.py). Скрипт вызывает тот же guarded CLI, что и остальные исследовательские источники: общий `rf4db.com` cooldown резервируется до HTTP-запроса, поэтому повтор после `403` или сетевой ошибки не выполняется раньше разрешённого окна.
+
+Для страницы, которая требует обычного браузерного JavaScript, используется Chromium-launcher с отдельным persistent profile:
+
+```bash
+node scripts/fetch-waterbodies-chromium.mjs catalog
+node scripts/fetch-waterbodies-chromium.mjs detail \
+  --url https://download.rf4db.com/ru/maps/level_019_american_pond
+```
+
+Он сначала резервирует тот же cooldown, затем открывает Chromium, сохраняет DOM и передаёт его локальному parser-у. Первый запуск можно оставить headed и вручную завершить обычную проверку сайта; `--headless` предназначен только для страниц, которые уже открываются без пользовательского действия. CAPTCHA и защитные challenge не автоматизируются.
+
+```bash
+./scripts/fetch-waterbodies.py catalog
+./scripts/fetch-waterbodies.py detail \
+  --url https://download.rf4db.com/ru/maps/level_019_american_pond
+```
+
+Результат сохраняется атомарно в `.cache/waterbodies/` с timestamp-именем; `403`, неполный ответ и cooldown оставляют прежние snapshots нетронутыми. Если RF4DB показывает защитную страницу в разрешённой Chromium-сессии, сохраните полученный HTML и разберите его без повторного HTTP:
+
+```bash
+./scripts/fetch-waterbodies.py catalog --html /path/to/maps.html
+./scripts/fetch-waterbodies.py detail \
+  --url https://download.rf4db.com/ru/maps/level_019_american_pond \
+  --html /path/to/detail.html
+```
+
+`--html` не резервирует cooldown и не обходит защиту: challenge/неполный документ будет отклонён строгим parser-ом. Скрипт намеренно не импортирует данные в PostgreSQL автоматически. После ручной проверки snapshot импортируется отдельно через `python -m app.cli import-waterbody-catalog` или `import-waterbody-detail`; для запуска из Docker файл передаётся в контейнер через stdin.
+
 ## Рекомендуемый режим получения

 - Один понятный `User-Agent`, таймаут 20 секунд.