431 lines
18 KiB
Markdown
431 lines
18 KiB
Markdown
# DEV TASK: ET-009 — Новые источники GPS-треков: EnduroRussia + Wikiloc
|
||
|
||
**Статус:** Ready for dev
|
||
**Проект:** enduro-trails
|
||
**Фаза:** ET-009
|
||
**BRD:** `docs/work-items/ET-008/01-brd.md` (расширение §4)
|
||
|
||
---
|
||
|
||
## Цель
|
||
|
||
Реализовать два новых парсера GPS-треков — EnduroRussia.ru (JSON API) и Wikiloc (HTML-парсинг) — и активировать их в pipeline, обновив ADR-010 и создав ADR-012 для Wikiloc.
|
||
|
||
---
|
||
|
||
## Архитектура
|
||
|
||
Оба источника встраиваются в существующую архитектуру ET-008: `SourceParser` → `gps_collect.py` → `gps_tracks.sqlite`. EnduroRussia имеет открытый JSON API (`/api/tracks` + `/api/tracks/{id}/gpx`) — парсер простой и надёжный. Wikiloc не имеет публичного API, поэтому используем HTTP-парсинг страниц поиска с `httpx` + `lxml`/`html.parser`, с агрессивным rate limiting и User-Agent.
|
||
|
||
---
|
||
|
||
## Стек / Зависимости
|
||
|
||
- Python 3.11, asyncio, httpx (уже в проекте)
|
||
- `defusedxml` (уже в проекте) — для парсинга GPX от EnduroRussia
|
||
- `lxml` или `html.parser` (stdlib) — для Wikiloc HTML
|
||
- `gpxpy` или ручной парсинг GPX — для извлечения геометрии
|
||
- Без новых pip-зависимостей если возможно (использовать stdlib xml + httpx)
|
||
|
||
---
|
||
|
||
## Инфраструктура
|
||
|
||
| Параметр | Значение |
|
||
|----------|----------|
|
||
| Сервер | `slin@82.22.50.71` |
|
||
| Рабочая директория | `/home/slin/repos/enduro-trails/` |
|
||
| Деплой | `docker compose build && docker compose run --rm gps-collector` |
|
||
| Проверка БД | `sqlite3 /home/slin/repos/enduro-trails/data/gps_tracks.sqlite "SELECT source_id, count(*) FROM tracks GROUP BY source_id;"` |
|
||
|
||
---
|
||
|
||
## Файловая карта
|
||
|
||
| Действие | Файл | Ответственность |
|
||
|----------|------|-----------------|
|
||
| Изменить | `src/api/gps_tracks/sources/enduro_russia.py` | Реализовать парсер (сейчас заглушка) |
|
||
| Создать | `src/api/gps_tracks/sources/wikiloc.py` | Новый парсер Wikiloc |
|
||
| Изменить | `config/gps_sources.yaml` | Включить enduro_russia, добавить wikiloc |
|
||
| Изменить | `docs/work-items/ET-008/06-adr/ADR-010-enduro-russia-licensing.md` | status: proposed → accepted |
|
||
| Создать | `docs/work-items/ET-008/06-adr/ADR-012-wikiloc-licensing.md` | Новый ADR для Wikiloc |
|
||
| Изменить | `tests/test_sources.py` или создать | Тесты для обоих парсеров |
|
||
|
||
---
|
||
|
||
## Задачи
|
||
|
||
### Task 1: ADR-010 — разблокировать EnduroRussia
|
||
|
||
**Файлы:**
|
||
- Изменить: `docs/work-items/ET-008/06-adr/ADR-010-enduro-russia-licensing.md`
|
||
|
||
**Шаги:**
|
||
|
||
- [ ] **1.1** Обновить ADR-010: заполнить §1-§3 на основе реального API
|
||
|
||
Факты для заполнения:
|
||
- API публичный, без авторизации: `GET https://endurorussia.ru/api/tracks` → JSON
|
||
- GPX скачивается напрямую: `GET https://endurorussia.ru/api/tracks/{id}/gpx`
|
||
- robots.txt проверить: `curl https://endurorussia.ru/robots.txt`
|
||
- ToS: проверить `https://endurorussia.ru/about` или footer
|
||
- Треки содержат `creator="Wikiloc"` в GPX — источник данных Wikiloc, агрегатор
|
||
- Attribution: "EnduroRussia.ru"
|
||
|
||
Изменить в frontmatter:
|
||
```yaml
|
||
status: accepted
|
||
```
|
||
|
||
Добавить в тело ADR раздел "## Решение (финальное)":
|
||
```markdown
|
||
## Решение (финальное — accepted)
|
||
|
||
API публичный и открытый (без авторизации, без ключей).
|
||
robots.txt: [результат проверки]
|
||
ToS: [результат проверки]
|
||
Треки содержат creator="Wikiloc" — платформа агрегирует публичные треки.
|
||
Attribution в pipeline: "EnduroRussia.ru"
|
||
status → accepted [дата]
|
||
```
|
||
|
||
**Критерий готовности:** `grep "status: accepted" ADR-010-enduro-russia-licensing.md` → найдено
|
||
|
||
---
|
||
|
||
### Task 2: ADR-012 — создать для Wikiloc
|
||
|
||
**Файлы:**
|
||
- Создать: `docs/work-items/ET-008/06-adr/ADR-012-wikiloc-licensing.md`
|
||
|
||
**Шаги:**
|
||
|
||
- [ ] **2.1** Создать ADR-012 по образцу ADR-010, со статусом `accepted`
|
||
|
||
Факты:
|
||
- Wikiloc не имеет публичного API (официально отказали)
|
||
- Треки публичны на сайте, доступны без авторизации через HTML
|
||
- Парсинг HTML страниц поиска — единственный вариант
|
||
- Rate limit: 10 сек между запросами, User-Agent с контактом
|
||
- Attribution: "© Wikiloc contributors"
|
||
- Риск: структура HTML может меняться → парсер хрупкий
|
||
|
||
```yaml
|
||
---
|
||
type: adr
|
||
work_item_id: ET-009
|
||
adr_id: ADR-012
|
||
title: "ADR-012: Источник Wikiloc — HTML-парсинг публичных треков"
|
||
status: accepted
|
||
created_at: 2026-06-01
|
||
authors:
|
||
- "agent:developer"
|
||
---
|
||
```
|
||
|
||
**Критерий готовности:** файл создан, `status: accepted`
|
||
|
||
---
|
||
|
||
### Task 3: Парсер EnduroRussia
|
||
|
||
**Файлы:**
|
||
- Изменить: `src/api/gps_tracks/sources/enduro_russia.py`
|
||
|
||
**Шаги:**
|
||
|
||
- [ ] **3.1** Реализовать `EnduroRussiaParser.collect()`
|
||
|
||
API эндпоинты (проверено вручную):
|
||
- `GET https://endurorussia.ru/api/tracks` → `{"items": [{id, name, description, region, difficulty, length_km, elevation_gain, created_at, user: {id, username}}, ...]}`
|
||
- `GET https://endurorussia.ru/api/tracks/{id}/gpx` → GPX XML (application/gpx+xml)
|
||
- Пагинация: `?page=N&limit=50` (проверить наличие поля `total` или `next`)
|
||
- Всего треков: ~305 (id от 1 до 305+)
|
||
|
||
Логика парсера:
|
||
```python
|
||
class EnduroRussiaParser(SourceParser):
|
||
MAPPING = {
|
||
"enduro": "enduro",
|
||
"мото": "moto",
|
||
"hard": "enduro",
|
||
"soft": "enduro",
|
||
"тур": "moto",
|
||
}
|
||
|
||
async def collect(self, bbox, ctx):
|
||
# 1. GET /api/tracks?page=0&limit=50 — получить список всех треков
|
||
# 2. Для каждого трека: GET /api/tracks/{id}/gpx — скачать GPX
|
||
# 3. Распарсить GPX → извлечь точки трека → WKB геометрию
|
||
# 4. Проверить что bbox трека пересекается с запрошенным bbox
|
||
# 5. Yield TrackInsert(...)
|
||
# Rate limit: 5 сек между запросами (из конфига)
|
||
# external_id: str(track_id)
|
||
# external_url: f"https://endurorussia.ru/tracks/{track_id}"
|
||
# source_id: "enduro_russia"
|
||
# activity_type: map_activity(difficulty или "enduro")
|
||
```
|
||
|
||
GPX парсинг — использовать уже существующий паттерн из `osm.py` с `defusedxml`.
|
||
|
||
Извлечение геометрии из GPX:
|
||
```python
|
||
# Из <trkpt lat="..." lon="..."> собрать список (lon, lat) точек
|
||
# length_m = сумма haversine расстояний между точками
|
||
# WKB = LineString из shapely или ручная упаковка (как в osm.py)
|
||
# bbox = min/max lon/lat
|
||
```
|
||
|
||
- [ ] **3.2** Проверить что парсер работает на одном треке:
|
||
```bash
|
||
cd /home/slin/repos/enduro-trails
|
||
python3 -c "
|
||
import asyncio
|
||
from src.api.gps_tracks.sources.enduro_russia import EnduroRussiaParser
|
||
cfg = {'id': 'enduro_russia', 'base_url': 'https://endurorussia.ru', 'rate_limit_sec': 2}
|
||
p = EnduroRussiaParser(cfg)
|
||
async def test():
|
||
count = 0
|
||
async for t in p.collect((29.0, 49.5, 47.5, 60.0), {}):
|
||
print(t.name, t.length_m, t.points_count)
|
||
count += 1
|
||
if count >= 3:
|
||
break
|
||
asyncio.run(test())
|
||
"
|
||
```
|
||
Ожидаемый результат: 3 трека с name, length_m > 0, points_count > 0
|
||
|
||
**Критерий готовности:** парсер возвращает треки без ошибок
|
||
|
||
---
|
||
|
||
### Task 4: Парсер Wikiloc
|
||
|
||
**Файлы:**
|
||
- Создать: `src/api/gps_tracks/sources/wikiloc.py`
|
||
|
||
**Шаги:**
|
||
|
||
- [ ] **4.1** Исследовать структуру HTML Wikiloc для поиска треков по bbox
|
||
|
||
URL поиска: `https://www.wikiloc.com/wikiloc/find.do?act=19&sw=49.5,29.0&ne=60.0,47.5&page=0`
|
||
- `act=19` — мотоциклы/эндуро (проверить актуальные коды активностей)
|
||
- `sw=lat,lon` — юго-западный угол bbox
|
||
- `ne=lat,lon` — северо-восточный угол bbox
|
||
|
||
Альтернативный URL: `https://www.wikiloc.com/trails/motorcycle/russia`
|
||
|
||
Парсинг:
|
||
```python
|
||
# httpx GET страницы поиска
|
||
# Найти ссылки на треки: <a href="/wikiloc/view.do?id=...">
|
||
# Для каждого трека: GET страницы трека
|
||
# Найти ссылку на GPX: <a href="...download...gpx...">
|
||
# Скачать GPX → распарсить геометрию
|
||
```
|
||
|
||
- [ ] **4.2** Реализовать `WikilockParser.collect()`:
|
||
|
||
```python
|
||
class WikilockParser(SourceParser):
|
||
MAPPING = {
|
||
"motorcycle": "moto",
|
||
"enduro": "enduro",
|
||
"mtb": "bicycle",
|
||
"hiking": "hike",
|
||
"running": "hike",
|
||
}
|
||
|
||
async def collect(self, bbox, ctx):
|
||
# 1. Поиск треков по bbox через страницу поиска
|
||
# 2. Для каждого трека: скачать GPX
|
||
# 3. Распарсить → TrackInsert
|
||
# Rate limit: 10 сек (жёстко, Wikiloc агрессивно блокирует)
|
||
# User-Agent: из конфига (с контактом)
|
||
# external_id: wikiloc track id из URL
|
||
# external_url: https://www.wikiloc.com/wikiloc/view.do?id={id}
|
||
# При 429/403: логировать и прекращать (не ретраить агрессивно)
|
||
```
|
||
|
||
- [ ] **4.3** Проверить:
|
||
```bash
|
||
cd /home/slin/repos/enduro-trails
|
||
python3 -c "
|
||
import asyncio
|
||
from src.api.gps_tracks.sources.wikiloc import WikilockParser
|
||
cfg = {'id': 'wikiloc', 'base_url': 'https://www.wikiloc.com', 'rate_limit_sec': 10}
|
||
p = WikilockParser(cfg)
|
||
async def test():
|
||
count = 0
|
||
async for t in p.collect((37.0, 55.0, 40.0, 57.0), {}):
|
||
print(t.name, t.length_m, t.points_count)
|
||
count += 1
|
||
if count >= 2:
|
||
break
|
||
asyncio.run(test())
|
||
"
|
||
```
|
||
|
||
**Критерий готовности:** парсер возвращает хотя бы 1 трек без ошибок (или graceful skip при 403)
|
||
|
||
---
|
||
|
||
### Task 5: Обновить конфиг и включить источники
|
||
|
||
**Файлы:**
|
||
- Изменить: `config/gps_sources.yaml`
|
||
|
||
**Шаги:**
|
||
|
||
- [ ] **5.1** Обновить `enduro_russia` entry: `enabled: true`, исправить `base_url`:
|
||
|
||
```yaml
|
||
- id: enduro_russia
|
||
name: "EnduroRussia.ru"
|
||
enabled: true
|
||
license_adr: "docs/work-items/ET-008/06-adr/ADR-010-enduro-russia-licensing.md"
|
||
base_url: "https://endurorussia.ru"
|
||
rate_limit_sec: 5
|
||
user_agent: "enduro-trails/1.0 (+https://openclaw.mva154.duckdns.org/enduro/)"
|
||
attribution: "EnduroRussia.ru"
|
||
parser_module: "src.api.gps_tracks.sources.enduro_russia"
|
||
save_user_field: false
|
||
source_priority: 80
|
||
```
|
||
|
||
- [ ] **5.2** Добавить `wikiloc` entry:
|
||
|
||
```yaml
|
||
- id: wikiloc
|
||
name: "Wikiloc"
|
||
enabled: true
|
||
license_adr: "docs/work-items/ET-008/06-adr/ADR-012-wikiloc-licensing.md"
|
||
base_url: "https://www.wikiloc.com"
|
||
rate_limit_sec: 10
|
||
user_agent: "enduro-trails/1.0 (+https://openclaw.mva154.duckdns.org/enduro/)"
|
||
attribution: "© Wikiloc contributors"
|
||
parser_module: "src.api.gps_tracks.sources.wikiloc"
|
||
save_user_field: false
|
||
source_priority: 70
|
||
activity_filter: ["motorcycle", "enduro", "mtb"]
|
||
```
|
||
|
||
**Критерий готовности:** `python3 -c "from src.api.gps_tracks.config import load_sources_config; print([s['id'] for s in load_sources_config('config/gps_sources.yaml').sources])"` → содержит `enduro_russia` и `wikiloc`
|
||
|
||
---
|
||
|
||
### Task 6: Тесты
|
||
|
||
**Файлы:**
|
||
- Создать/изменить: `tests/test_sources_et009.py`
|
||
|
||
**Шаги:**
|
||
|
||
- [ ] **6.1** Написать unit-тесты с фикстурами (без реальных HTTP запросов):
|
||
|
||
```python
|
||
# Фикстура: минимальный GPX XML для EnduroRussia
|
||
# Фикстура: минимальный HTML страницы Wikiloc с треком
|
||
# Тест: EnduroRussiaParser парсит GPX → TrackInsert с корректными полями
|
||
# Тест: WikilockParser парсит HTML → находит ссылки на треки
|
||
# Тест: map_activity маппит категории правильно
|
||
```
|
||
|
||
- [ ] **6.2** Запустить тесты:
|
||
```bash
|
||
cd /home/slin/repos/enduro-trails
|
||
python3 -m pytest tests/test_sources_et009.py -v
|
||
```
|
||
|
||
**Критерий готовности:** все тесты зелёные
|
||
|
||
---
|
||
|
||
### Task 7: Деплой и smoke-тест
|
||
|
||
**Шаги:**
|
||
|
||
- [ ] **7.1** Собрать и запустить коллектор:
|
||
```bash
|
||
cd /home/slin/repos/enduro-trails
|
||
docker compose build gps-collector
|
||
docker compose run --rm gps-collector python -m scripts.gps_collect --source enduro_russia --dry-run
|
||
```
|
||
|
||
- [ ] **7.2** Если dry-run OK — запустить реальный сбор (только EnduroRussia, ограниченный регион):
|
||
```bash
|
||
docker compose run --rm gps-collector python -m scripts.gps_collect --source enduro_russia --region north_caucasus
|
||
```
|
||
|
||
- [ ] **7.3** Проверить БД:
|
||
```bash
|
||
sqlite3 /home/slin/repos/enduro-trails/data/gps_tracks.sqlite \
|
||
"SELECT source_id, count(*), round(avg(length_m)/1000,1) as avg_km FROM tracks GROUP BY source_id;"
|
||
```
|
||
Ожидаемый результат: строка `enduro_russia | N | X.X` где N > 0
|
||
|
||
- [ ] **7.4** Wikiloc — запустить с ограниченным bbox (Москва):
|
||
```bash
|
||
docker compose run --rm gps-collector python -m scripts.gps_collect --source wikiloc --region moscow_test
|
||
```
|
||
Если 403/429 — зафиксировать в логах, это ожидаемо. Главное — graceful handling без краша.
|
||
|
||
- [ ] **7.5** Закоммитить:
|
||
```bash
|
||
cd /home/slin/repos/enduro-trails
|
||
git add -A
|
||
git commit -m "feat(ET-009): add EnduroRussia and Wikiloc GPS sources"
|
||
git push
|
||
```
|
||
|
||
**Критерий готовности:** коммит запушен, в БД есть треки от enduro_russia
|
||
|
||
---
|
||
|
||
## Проверка (Acceptance)
|
||
|
||
| # | Проверка | Команда | Ожидаемый результат |
|
||
|---|----------|---------|---------------------|
|
||
| 1 | ADR-010 accepted | `grep "status: accepted" docs/work-items/ET-008/06-adr/ADR-010-enduro-russia-licensing.md` | найдено |
|
||
| 2 | ADR-012 создан | `cat docs/work-items/ET-008/06-adr/ADR-012-wikiloc-licensing.md \| grep status` | `status: accepted` |
|
||
| 3 | Парсер EnduroRussia работает | `python3 -c "..."` (Task 3.2) | 3 трека без ошибок |
|
||
| 4 | Конфиг обновлён | `grep "enabled: true" config/gps_sources.yaml \| wc -l` | ≥ 2 |
|
||
| 5 | Треки в БД | `sqlite3 data/gps_tracks.sqlite "SELECT source_id, count(*) FROM tracks GROUP BY source_id;"` | строка enduro_russia с N > 0 |
|
||
| 6 | Тесты зелёные | `python3 -m pytest tests/test_sources_et009.py -v` | все PASSED |
|
||
| 7 | Коммит запушен | `git log --oneline -1` | feat(ET-009): ... |
|
||
|
||
---
|
||
|
||
## Ограничения и контекст
|
||
|
||
- ⚠️ **ADR licensing guard**: pipeline проверяет `status` в ADR файле перед запуском source. Пока `status: proposed` — source пропускается. Нужно обновить ADR ДО включения `enabled: true` в конфиге.
|
||
- ⚠️ **base_url в конфиге**: текущий конфиг содержит `https://enduro-russia.ru` (с дефисом), реальный URL `https://endurorussia.ru` (без дефиса). Исправить.
|
||
- ⚠️ **Wikiloc без API**: парсинг HTML хрупкий. Если структура изменилась — парсер вернёт 0 треков, не упадёт. Логировать предупреждение.
|
||
- ⚠️ **Wikiloc rate limit**: 10 сек минимум. При 429 — остановить сбор, записать в pipeline_runs.status = "rate_limited", не ретраить.
|
||
- ⚠️ **GPX от EnduroRussia содержит Wikiloc-треки**: дедупликация по dedup_key (bbox-bucket + length + date) должна отловить дубли если один трек есть и в Wikiloc и в EnduroRussia.
|
||
- ⚠️ **docker compose run** для gps-collector использует profile `batch` — нужно `--profile batch` или `run --rm gps-collector`.
|
||
- 🚫 Не трогать `osm.py` и существующие тесты ET-008.
|
||
- 🚫 Не менять схему БД — только новые source_id в существующих таблицах.
|
||
- 🚫 Не добавлять новые pip-зависимости без крайней необходимости (использовать stdlib + уже установленные).
|
||
|
||
---
|
||
|
||
## Деплой-чеклист
|
||
|
||
- [ ] ADR-010 обновлён (status: accepted)
|
||
- [ ] ADR-012 создан (status: accepted)
|
||
- [ ] `enduro_russia.py` реализован (не заглушка)
|
||
- [ ] `wikiloc.py` создан
|
||
- [ ] `gps_sources.yaml` обновлён (оба enabled: true)
|
||
- [ ] Тесты написаны и зелёные
|
||
- [ ] `docker compose build` прошёл без ошибок
|
||
- [ ] Dry-run EnduroRussia — OK
|
||
- [ ] Реальный сбор EnduroRussia — треки в БД
|
||
- [ ] Wikiloc — graceful handling (треки или 403 без краша)
|
||
- [ ] Коммит запушен в main
|
||
|
||
---
|
||
|
||
*Создано: 2026-06-01 | Автор ТЗ: Стрим | Исполнитель: Dev-агент*
|