114 lines
13 KiB
Markdown
114 lines
13 KiB
Markdown
# Аудит источников и парсеров
|
||
|
||
Дата проверки: **3 сентября 2026 года**. Аудит охватывает код репозитория, один контрольный запрос к официальной таблице и публично описанные возможности потенциальных источников. Он не является разрешением на сбор чужих данных.
|
||
|
||
## Итог
|
||
|
||
Сейчас у проекта **два реально работающих канала данных**, но только **один автоматический внешний источник**:
|
||
|
||
| Канал | Статус | Что даёт | Координаты | Доверие |
|
||
|---|---|---|---|---|
|
||
| Официальная таблица `rf4game.de` | подключена, HTML-импорт | рекорд, рыба, вес, водоём, приманка, игрок, дата | нет | 100 |
|
||
| Собственная форма RF4 Spotter | подключена, после модерации | обычный улов, точка, снасть, игрок, скриншот | да | назначается приложением |
|
||
|
||
`manual_import` существует в модели и seed, но отдельного пользовательского CSV/JSON-импортера нет. Seed — демонстрационные данные, а не источник. MinIO хранит доказательство пользовательской записи и также не является самостоятельным источником.
|
||
|
||
## Текущие парсеры
|
||
|
||
В репозитории два HTML-парсера одной официальной таблицы:
|
||
|
||
1. `rf4_research.records.parse_records_html` — исследовательский адаптер и CLI;
|
||
2. `app.importer.parse_html` — продуктивный адаптер с HTTP-кэшем, повторами, журналом и сохранением.
|
||
|
||
Оба ожидают один DOM-контракт `div.records.flex_table`, одинаковый порядок шести колонок и одинаково нормализуют вес, дату и пустые поля. Добавлен общий контрактный тест: на одной фикстуре парсеры обязаны вернуть одинаковые кортежи полей и оба обязаны отклонить изменённую структуру колонок.
|
||
|
||
Контрольный HTML `https://rf4game.de/records/region/RU/` имел размер 1 147 837 байт. Оба парсера успешно прочитали **1260 записей**, результаты по восьми общим полям полностью совпали. Временный HTML в репозиторий не добавлен.
|
||
|
||
### Обнаруженные ограничения согласования
|
||
|
||
- Дублирование кода двух парсеров остаётся риском. Контрактный тест защищает результат, но при следующем рефакторинге общую чистую функцию разбора лучше вынести в пакет, доступный и исследовательскому CLI, и API-контейнеру.
|
||
- Источник настроен на немецкий домен. Регион `RU` фильтрует игроков, но названия рыб, водоёмов и приманок остаются немецкими. Они не совпадают с русскими названиями пользовательской формы и могут создать параллельные сущности.
|
||
- Русский URL `https://rf4game.ru/records/region/RU/` при контрольном запросе вернул небольшую JavaScript-защитную страницу без таблицы; текущий парсер корректно завершился ошибкой `records table not found`. Обход защиты не рассматривается.
|
||
- `source_external_id` надёжно убирает повтор одной и той же локализованной строки, но локализованные копии одной записи получат разные хеши. Нельзя считать разные языковые домены независимыми подтверждениями.
|
||
- Официальная запись не содержит координат и поэтому не участвует в индексе конкретной точки. Автоматически связывать её с точкой нельзя.
|
||
- Для новых агрегаторов одного enum `source_type` недостаточно: нужен стабильный `source_system`, внешний ID внутри этого источника, исходная ссылка и отдельное правило доверия.
|
||
|
||
## Где можно получить новые данные
|
||
|
||
### Приоритет A — тот же официальный источник
|
||
|
||
Официальная навигация публикует абсолютные и недельные таблицы, а также категории `records`, `ultralight`, `recordslight`, `bottomlight`, `sea` и `telestick`. Это расширение охвата существующего источника, а не независимые подтверждения. Текущий DOM-парсер, вероятно, можно переиспользовать, но каждую комбинацию нужно сначала проверить отдельной фикстурой. Регулярный обход нельзя включать без согласования допустимой частоты с владельцем сайта.
|
||
|
||
Рекомендуемый первый эксперимент — **недельные RU-рекорды одной категории**. Они полезнее абсолютных для свежести, не требуют новой схемы, но всё ещё не дают координат.
|
||
|
||
### Приоритет A — согласованные каналы сообщества
|
||
|
||
Telegram, Discord и VK могут давать свежие координаты, оснастку, игровое время и скриншоты. Подключать следует только конкретные каналы, администраторы которых письменно разрешили импорт. Для каждого сообщения нужны permalink/message ID, время публикации, имя канала, версия правил и возможность удалить запись по запросу.
|
||
|
||
Наиболее безопасная реализация — бот или форма, куда автор сам пересылает сообщение и подтверждает распознанные поля. Это лучше скрытого чтения групп и позволяет использовать существующую очередь модерации.
|
||
|
||
### Приоритет B — RF4DB по договорённости
|
||
|
||
`https://rf4db.com/ru` показывает актуальные пользовательские уловы, координаты, игровое время, погоду, снасть и изображения; публичная страница заявляет 19 водоёмов, 252 вида рыб и тысячи точек. Страница об источниках поясняет, что игровые справочники взяты из игры, а точки и комментарии собраны игроками в открытом доступе.
|
||
|
||
Технически HTML пригоден для адаптера, но это уже собранная база другого проекта. До письменного разрешения владельца нельзя делать парсер или копировать изображения. Лучший вариант — запросить документированный экспорт/API и условия атрибуции, удаления и частоты обновления.
|
||
|
||
### Приоритет B — RF4-STAT по договорённости
|
||
|
||
`https://rf4-stat.ru/help/` сообщает, что рекорды берутся с официального сайта, а точки и посты — из VK, Discord, Telegram и собственной формы. Сервис обновляет записи регулярно, часть доступа является Premium.
|
||
|
||
Парсинг страниц означал бы повторный сбор уже агрегированных материалов и мог бы обходить продуктовые ограничения. Использовать источник можно только через согласованный API/выгрузку; данные, пришедшие туда с официального сайта, нельзя считать вторым независимым подтверждением.
|
||
|
||
### Приоритет C — справочники
|
||
|
||
Списки рыб, водоёмов, снастей, трофейных весов и переводов полезны для канонизации, но не для оценки текущего клёва. Источниками-кандидатами являются официальные страницы/патчноуты и разрешённый справочный экспорт партнёра. Нужны версия игры, язык и устойчивый внутренний ключ; сопоставление только по отображаемому имени недостаточно.
|
||
|
||
## Что не использовать
|
||
|
||
- перехват трафика клиента, внедрение в игру и закрытые протоколы;
|
||
- боты автоматической рыбалки и данные, полученные с нарушением правил игры;
|
||
- обход JavaScript-защиты, CAPTCHA, авторизации или Premium-доступа;
|
||
- массовое копирование чужих изображений и пользовательских постов без разрешения;
|
||
- разные локализации официальной записи как разные подтверждения.
|
||
|
||
## Схема согласования новых адаптеров
|
||
|
||
Каждый адаптер должен выдавать промежуточную запись со следующими группами полей:
|
||
|
||
```text
|
||
provenance: source_system, source_external_id, source_url, observed_at, fetched_at
|
||
identity: fish_external_id/name/language, waterbody_external_id/name/language
|
||
catch: weight_g, caught_at, game_time, bait, method, rig, retrieve
|
||
spot: x, y или null
|
||
actor: player_name или null
|
||
evidence: screenshot_url/key, raw_payload
|
||
quality: moderation_status, source_confidence
|
||
```
|
||
|
||
До записи в `catch_report` должны последовательно выполняться:
|
||
|
||
1. валидация контракта источника;
|
||
2. нормализация единиц, времени и пустых значений;
|
||
3. сопоставление рыб/водоёмов по таблице алиасов с языком и версией игры;
|
||
4. дедупликация внутри `source_system`;
|
||
5. выявление кросс-источниковых копий без автоматического объединения сомнительных записей;
|
||
6. назначение доверия и модерации по политике источника;
|
||
7. сохранение происхождения и минимально необходимого сырого фрагмента.
|
||
|
||
## Рекомендуемый порядок работ
|
||
|
||
1. Добавить сущности `data_source` и `entity_alias`; включить источник в уникальный ключ внешней записи.
|
||
2. Вынести общий официальный DOM-парсер и оставить два тонких клиента вокруг него.
|
||
3. Добавить фикстуру недельной таблицы и проверить одну официальную категорию без расписания.
|
||
4. Согласовать экспорт/API с RF4DB и RF4-STAT; до ответа не писать их парсеры.
|
||
5. Выбрать один добровольный Telegram/Discord/VK-канал для пилота и зафиксировать согласие/правила удаления.
|
||
6. Только затем добавлять адаптер, контрактные тесты и калибровку `source_confidence`.
|
||
|
||
## Проверенные ссылки
|
||
|
||
- официальный абсолютный рейтинг: <https://rf4game.de/records/region/RU/>
|
||
- официальный недельный рейтинг: <https://rf4game.de/records/weekly/region/RU/>
|
||
- RF4DB: <https://rf4db.com/ru> и <https://rf4db.com/ru/about/data>
|
||
- RF4-STAT: <https://rf4-stat.ru/help/>
|
||
- исследовательский проект: <https://github.com/hurfy/rf4-api>
|