auto-sync: 2026-05-02 07:20:01

2026-05-02 07:20:04 +03:00
parent 7d34a79dbe
commit 5ca8234846
2 changed files with 411 additions and 0 deletions
--- a/tasks/enduro-trails/TECHNICAL_SPEC.md
+++ b/tasks/enduro-trails/TECHNICAL_SPEC.md
@@ -0,0 +1,265 @@
+# Техническое задание: Прототип Enduro Trails v0.1
+
+**Проект:** Enduro Trails 🏍️  
+**Документ:** TECHNICAL_SPEC.md  
+**Версия:** 0.1  
+**Дата:** 02.05.2026  
+**Автор:** Стрим 🌊  
+**Исполнитель:** Dev-агент  
+**Статус:** на согласовании
+
+---
+
+## 1. Цель
+
+Создать прототип на mva154, который визуализирует грунтовые дороги ЦФО+Чувашия на карте с «перевёрнутой логикой»: грунтовки яркие и заметные, асфальт — тусклый фон. Без роутинга — только данные + визуализация.
+
+---
+
+## 2. Область (Scope)
+
+### ✅ Включено в v0.1
+- Скачивание PBF дампа с Geofabrik (ЦФО)
+- Парсинг дорог (highway=track, highway=path) с тегами
+- Импорт в Spatialite (.sqlite файл)
+- Слой POI (водоёмы, видовые точки, заброчки)
+- Генерация Mapbox GL совместимых тайлов (z10–z16)
+- Кастомный стиль: грунтовки яркие, асфальт серый
+- Веб-карта (MapLibre GL JS) с контролами слоёв
+- Клик по дороге → popup с информацией
+
+### ❌ НЕ включено в v0.1
+- OSRM роутинг (фаза 2)
+- SRTM рельеф + уклоны (фаза 3)
+- PWA / оффлайн работа (фаза 5)
+- GPS трекинг
+- Мобильное приложение
+- «Красивый маршрут», «Горка», «Связка» и прочие алгоритмы
+
+---
+
+## 3. Технические требования
+
+### 3.1 Хост
+- **Сервер:** mva154 (localhost, Docker)
+- **Порт:** 5558 (или первый свободный 555X)
+- **Доступ:** Docker контейнеры + docker-compose
+- **Ресурсы:** без ограничений (это прототип)
+
+### 3.2 Источник данных
+
+| Параметр | Значение |
+|----------|----------|
+| **Формат** | OSM PBF |
+| **Источник** | `https://download.geofabrik.de/russia/centralfederal.ru-latest.osm.pbf` |
+| **Регион** | Центральный ФО |
+| **Чувашия** | Проверить Geofabrik — если отдельный дамп, объединить; если включена — ок |
+| **BBOX фильтрация** | Если Geofabrik не даёт отдельный ЦФО — фильтруем по bbox: west=30.0, east=45.0, south=51.0, north=59.0 |
+
+### 3.3 Парсинг
+
+**Инструмент:** Pyrosm (Python) + osmium
+
+**Фильтр дорог (выбираем):**
+```
+highway: track, path, bridleway, cycleway, footway (для связки)
+```
+
+**Теги для каждого сегмента:**
+| Тег | Описание |
+|-----|----------|
+| `surface` | paved, unpaved, gravel, sand, mud, earth, grass, asphalt, concrete |
+| `tracktype` | grade1–grade5 |
+| `mtb:scale` | 0–6 |
+| `trail_visibility` | yes, no, negative |
+| `smoothness` | excellent, good, intermediate, bad, very_bad, horrible |
+| `access` | private, no, permissive, destination |
+| `vehicle` | yes, no, agricultural, forestry |
+| `name` | название (если есть) |
+| `osm_id` | ID из OSM |
+| `geometry` | LINESTRING |
+| `length_m` | длина в метрах (рассчитать) |
+
+**POI точки:**
+```
+natural=water + name (озёра, реки — крупные)
+tourism=viewpoint (видовые точки)
+historic=ruins / abandoned=yes (заброшки)
+natural=peak (вершины)
+natural=cave_entrance (пещеры)
+ford=yes (броды)
+```
+
+### 3.4 Хранение — Spatialite
+
+**Файл:** `tasks/enduro-trails/data/centralfederal.sqlite`
+
+**Таблица `trails`:**
+```sql
+CREATE TABLE trails (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    osm_id INTEGER NOT NULL,
+    highway_type TEXT,
+    track_type TEXT,
+    surface TEXT,
+    name TEXT,
+    length_m REAL,
+    mtb_scale TEXT,
+    visibility TEXT,
+    smoothness TEXT,
+    access TEXT,
+    tags TEXT,                          -- JSON с остальными тегами
+    geom GEOMETRY                       -- LINESTRING, SRID 4326
+);
+CREATE INDEX idx_trails_geom ON trails USING GEOMETRY(geom, POLYGON);
+CREATE INDEX idx_trails_highway ON trails(highway_type);
+CREATE INDEX idx_trails_surface ON trails(surface);
+```
+
+**Таблица `poi`:**
+```sql
+CREATE TABLE poi (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    osm_id INTEGER NOT NULL,
+    poi_type TEXT,                      -- lake, viewpoint, ruins, peak, cave, ford
+    name TEXT,
+    geom GEOMETRY                       -- POINT, SRID 4326
+);
+CREATE INDEX idx_poi_geom ON poi USING GEOMETRY(geom, POLYGON);
+CREATE INDEX idx_poi_type ON poi(poi_type);
+```
+
+### 3.5 Генерация тайлов
+
+**Формат:** Mapbox GL совместимые векторные тайлы (PBF + JSON)  
+**Уровни:** z10, z11, z12, z13, z14, z15, z16
+
+**Варианты реализации:**
+1. **TileServer GL** — готовый сервер, принимает config.json с источником Spatialite
+2. **Martin** (Rust) — быстрый тайл-сервер для PostGIS/Spatialite
+3. **Python self-hosted** — FastAPI отдаёт тайлы на лету из Spatialite
+
+**Рекомендация:** TileServer GL или Martin через Docker — минимум кастомного кода
+
+**Слои тайлов:**
+| Слой | Источник | Описание |
+|------|----------|----------|
+| `trails` | trails table | Все грунтовые дороги |
+| `poi` | poi table | Точки интереса |
+
+### 3.6 Стиль карты (Mapbox GL Style JSON)
+
+**Принцип «перевёрнутой логики»:**
+
+| Элемент | Стиль |
+|---------|-------|
+| Грунтовки (grade3–5, unpaved) | Яркие оранжевые/жёлтые линии, толщина 3–4px |
+| Грунтовки (grade1–2, paved) | Средние оранжевые, толщина 2px |
+| Path/bridleway | Пунктирные жёлтые, толщина 1.5px |
+| Асфальт primary+ | Тонкие серые, 1px |
+| Асфальт secondary/tertiary | Серые, 1.5px |
+| Fon | Очень тёмный/приглушённый |
+| POI озёра | 💙 голубые точки |
+| POI viewpoints | 📷 фиолетовые |
+| POI ruins | 🏚️ коричневые |
+| POI peaks | 🔺 красные треугольники |
+
+### 3.7 Веб-карта (Frontend)
+
+**Технологии:**
+- HTML + CSS + JavaScript (Vanilla или React по выбору Dev-агента)
+- MapLibre GL JS (CDN, без сборки)
+
+**Структура:**
+```
+tasks/enduro-trails/prototype/
+├── app.py              # FastAPI сервер (раздаёт статику + API)
+├── static/
+│   ├── index.html
+│   ├── style.json      # MapLibre GL Style
+│   ├── app.js          # Логика карты
+│   └── app.css
+└── data/
+    └── centralfederal.sqlite
+```
+
+**Функции:**
+- [ ] Отображение карты с кастомным стилем
+- [ ] Контролы слоёв (вкл/выкл: грунтовки, POI)
+- [ ] Клик по дороге → popup (name, surface, tracktype, length)
+- [ ] Клик по POI → popup (name, type)
+- [ ] Поиск по bbox (кнопка «показать всё»)
+- [ ] Зум/пан — стандартные
+
+---
+
+## 4. Структура проекта
+
+```
+tasks/enduro-trails/
+├── PROJECT.md                  # Описание проекта (уже есть)
+├── CONCEPT.md                  # Концепция и архитектура (уже есть)
+├── TECHNICAL_SPEC.md           # ⬅️ ЭТОТ ФАЙЛ (новый)
+├── TASKS/
+│   └── active/
+│       └── prototype-setup/
+│           └── TASK.md         # Чеклист задачи (уже есть)
+├── prototype/                  # ⬅️ Новая папка (создаст Dev-агент)
+│   ├── app.py                  # FastAPI сервер
+│   ├── requirements.txt        # Зависимости
+│   ├── docker-compose.yml      # (опционально) Docker-сборка
+│   ├── static/
+│   │   ├── index.html
+│   │   ├── style.json
+│   │   ├── app.js
+│   │   └── app.css
+│   └── scripts/
+│       ├── parse.py            # Парсинг PBF → Spatialite
+│       └── generate_tiles.py   # Генерация тайлов (или конфиг для tileserver-gl)
+└── data/                       # ⬅️ Новая папка
+    └── centralfederal.sqlite   # Parsed OSM data
+```
+
+---
+
+## 5. Критерии приёмки (Acceptance Criteria)
+
+Прототип считается готовым когда:
+
+1. ✅ Скачан PBF дамп ЦФО с Geofabrik
+2. ✅ `parse.py` парсит PBF → `centralfederal.sqlite` (trails + POI)
+3. ✅ Тайлы генерируются (tileserver-gl или аналог)
+4. ✅ Веб-карта на `localhost:5558` (или другой порт) показывает:
+   - Грунтовки яркие (оранжевые/жёлтые)
+   - Асфальт тусклый (серый)
+   - POI отображаются иконками
+5. ✅ Клик по дороге → popup с name, surface, tracktype, length
+6. ✅ Базовые контролы слоёв (toggle trails, POI)
+7. ✅ `docker-compose up` или `python app.py` запускает всё одной командой
+
+---
+
+## 6. Ограничения и заметки
+
+- **Без роутинга** — OSRM ставится в фазе 2
+- **Без рельефа** — SRTM слой в фазе 3
+- **Без PWA** — только веб, вёрстка для десктопа
+- **Один регион** — ЦФО, масштабирование потом
+- **Данные статичные** — обновление PBF = перезапуск parase.py
+- **Без авторизации** — локальный хост, только для Славы пока
+- **Pyrosm** может потребовать GDAL — если сложно, использовать Osmium
+
+---
+
+## 7. Следующие шаги (после v0.1)
+
+| Фаза | Что | Приоритет |
+|------|-----|-----------|
+| Фаза 2 | OSRM роутинг + «Дикий путь» | High |
+| Фаза 3 | SRTM рельеф + уклоны | Medium |
+| Фаза 4 | «Красивый маршрут», «Горка» | Medium |
+| Фаза 5 | PWA + оффлайн | Low |
+
+---
+
+*Документ создан автоматически. Для правок — связаться со Стрим.*