feat: add RF4DB and RF4-STAT research parsers

2026-09-03 18:37:09 +07:00
parent 17c9c40241
commit 16d64606f8
11 changed files with 477 additions and 7 deletions
@@ -0,0 +1,70 @@
+# Пилот парсинга RF4DB и RF4-STAT
+
+Дата контрольного запуска: **3 сентября 2026 года**. Владелец RF4 Spotter подтвердил наличие разрешений на получение данных из обоих сервисов. Пилот использует только публичный HTML, не обращается к закрытым API, не обходит авторизацию/Premium и не скачивает изображения.
+
+## RF4DB
+
+Проверенная страница: `https://download.rf4db.com/ru/catches`.
+
+HTML формируется Next.js, но готовые карточки присутствуют в серверном ответе. Из карточки извлекаются:
+
+- UUID улова и каноническая detail-ссылка;
+- русское название и внешний slug рыбы;
+- русское название и внешний ID водоёма;
+- координаты;
+- игровое время;
+- приманка и её внешний ID;
+- оснастка;
+- погода и температура воды.
+
+На контрольной странице найдено 24 элемента `catch-card`: 23 являлись уловами с detail-ссылкой, один — неполным/служебным элементом и безопасно пропущен. У всех 23 уловов были координаты. Вес, игрок и абсолютное время публикации отсутствовали и не подменяются догадками.
+
+Detail-страница дополнительно содержит ветер, клипсу, выпуск лески, направление заброса и полный список снастей, но по-прежнему не содержит вес. Добавлен отдельный `RF4DBCatchDetail`: контрольная живая страница вернула ветер, три числовых параметра заброса и 11 элементов снасти. Detail-запросы не выполняются автоматически для всей выдачи, чтобы не умножать нагрузку на источник.
+
+`robots.txt` на download-домене запрещает автоматический обход для `User-Agent: *` и `/api/`. Наличие отдельного разрешения нужно сохранить в документации проекта. Публичный API не исследовался и не использовался; для пилота взят только серверный HTML одной страницы.
+
+## RF4-STAT
+
+Проверенные страницы:
+
+- `https://rf4-stat.ru/fishing/`;
+- `https://rf4-stat.ru/posts/`;
+- `https://rf4-stat.ru/active-spots/`.
+
+Запросы выполнялись последовательно с `Crawl-delay: 5`, указанным в `robots.txt`.
+
+Из таблицы `/fishing/` извлекаются ID, ссылка, рыба и slug, вес, водоём, приманка, игрок, время публикации, клипса, стиль ловли и ссылка на изображение. Контрольный результат: **100 из 100 строк**. Вес присутствовал во всех 100 строках; координаты в публичном представлении были замаскированы и не извлекались.
+
+Из `/posts/` один пост разворачивается в одно или несколько наблюдений по числу рыб. Извлекаются ID `post:fish_index`, время публикации Unix, рыба, вес, водоём, приманки, игрок, клипса, стиль и URL миниатюр-доказательств. Контрольный результат: **16 наблюдений из 10 постов**, у всех 16 были вес и доказательства. Координаты и погода, помеченные `position-locked`/`locked weather`, намеренно не извлекались.
+
+`/active-spots/` содержит десять агрегированных карточек, но публично видимые координаты и интерактивная статистика заблокированы, а стабильного ID наблюдения и рыбы нет. Эти карточки не преобразуются в уловы. Значения из скрытых `data-position` не используются.
+
+## Общий контракт
+
+Парсеры возвращают `ExternalCatch` и никогда не записывают данные непосредственно в БД. Поля `weight_g`, координаты, игрок и время nullable, потому что источники дополняют друг друга, но не должны склеиваться только из-за похожих значений.
+
+Текущие пространства идентификаторов разделены:
+
+- `rf4db` + UUID;
+- `rf4stat-fishing` + числовой ID;
+- `rf4stat-post` + `post_id:fish_index`.
+
+Следующий слой импорта должен хранить `source_system` отдельно от внешнего ID. Автоматическое объединение RF4DB и RF4-STAT пока запрещено: одна и та же публикация может присутствовать в обоих агрегаторах, но надёжного общего первичного ключа нет.
+
+## Реализовано
+
+- `rf4_research/community_sources.py` — три fail-closed HTML-парсера;
+- `parse_rf4db_detail` — отдельное обогащение одного RF4DB-улова;
+- `python -m rf4_research.community_cli` — read-only CLI одного ограниченного снимка;
+- обезличенные минимальные фикстуры для каждого контракта;
+- тесты всех извлекаемых полей, locked-координат и отказа на постороннем HTML;
+- живой контрольный прогон без сохранения персональных данных и изображений в репозиторий.
+
+## Перед продуктивным импортом
+
+1. Сохранить подтверждение разрешения и согласованные лимиты запросов.
+2. Добавить миграцию `data_source`/`source_system` и nullable-модель внешнего наблюдения либо обоснованно сделать вес nullable.
+3. Ввести алиасы рыб и водоёмов по внешним slug, а не только по названию.
+4. Назначить разные начальные уровни доверия для RF4DB и двух каналов RF4-STAT.
+5. Добавить идемпотентную staging-загрузку и ручную модерацию перед влиянием на индекс.
+6. Не хранить и не проксировать изображения без отдельного условия разрешения; на первом этапе достаточно исходной ссылки.