From 0480be2539da58c196527a151a3850fa90b8c0b4 Mon Sep 17 00:00:00 2001 From: Slava Date: Fri, 15 May 2026 15:59:44 +0300 Subject: [PATCH] docs: add project README, phase BRD and plan MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md with project overview, features, stack - docs/phases/pilot/00-phase-brd.md — full project BRD - docs/phases/pilot/01-phase-plan.md — current phase plan Refs: multi-agent F0-3 --- README.md | 76 +++++++++++++++++- docs/phases/pilot/00-phase-brd.md | 122 +++++++++++++++++++++++++++++ docs/phases/pilot/01-phase-plan.md | 40 ++++++++++ 3 files changed, 236 insertions(+), 2 deletions(-) create mode 100644 docs/phases/pilot/00-phase-brd.md create mode 100644 docs/phases/pilot/01-phase-plan.md diff --git a/README.md b/README.md index 0ce914d..0e96dde 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,75 @@ -# enduro-trails +# Enduro Trails 🏍️ + +OSM-карта с фокусом на грунтовые дороги для построения эндуро-маршрутов. + +## Что это + +Обычные карты оптимизированы под автомобили — асфальт яркий, грунтовки не видны. Enduro Trails переворачивает логику: **грунтовки и тропы — главный слой**, асфальт — тусклый фон. + +Приложение помогает: +- Найти грунтовые дороги в любом районе +- Построить маршрут с максимумом грунта и минимумом асфальта +- Оценить сложность (grade 1-5, покрытие, уклон) +- Найти живописные места (озёра, виды, руины, броды) +- Экспортировать маршрут в GPX для навигатора + +## Демо + +https://openclaw.mva154.duckdns.org/enduro/ + +## Фичи + +- 🗺️ **Карта грунтовок** — MapLibre GL JS, кастомный стиль, тёмная/светлая тема +- 🛤️ **Маршрут** — до 5 альтернатив с разным балансом грунт/асфальт, промежуточные точки +- ✨ **Красивый маршрут** — замкнутый круг через живописные POI +- 🔗 **Связка** — соединить два трека грунтовками +- 🔍 **Разведка** — статистика грунтовок в радиусе 20/50/100 км +- 📏 **Линейка** — измерение расстояний на карте +- 📍 **Метки** — сохранение точек интереса +- 🏔️ **Рельеф** — гипсометрия + hillshade (SRTM 30м) +- 📊 **Статистика** — % грунта/асфальта, время, дистанция +- 📥 **GPX экспорт** — трек + waypoints для навигатора +- 🌙 **Тёмная тема** — авто (по закату), ручная, синхронизация карты и UI + +## Стек + +| Компонент | Технология | +|-----------|-----------| +| Frontend | MapLibre GL JS + vanilla JS | +| Backend | Python 3.12 + FastAPI + uvicorn | +| БД | SQLite + Spatialite (1.1M треков, 14K POI) | +| Роутинг | OSRM с кастомным эндуро-профилем | +| Тайлы | Self-hosted raster (terrain, hillshade, TRI) | +| Контейнеризация | Docker + Compose | +| CI | Gitea Actions | + +## Регион + +ЦФО + Чувашия (расширение по запросу) + +## Быстрый старт + +```bash +make dev # поднять локально (Docker Compose) +make test # запустить тесты +make lint # линтеры +make build # собрать Docker-образ +``` + +## Структура + +``` +src/api/ — FastAPI backend (маршруты, тайлы, поиск) +src/web/ — фронтенд (MapLibre, UI) +tests/ — тесты (unit, integration, e2e) +docs/ — документация, ADR, work-items +scripts/ — утилиты +migrations/ — миграции БД +.openclaw/ — system prompts агентов +``` + +## Лицензия + +Данные: © OpenStreetMap contributors (ODbL) +Рельеф: NASA SRTM (Public Domain) -Карта эндуро-маршрутов с рельефом и навигацией \ No newline at end of file diff --git a/docs/phases/pilot/00-phase-brd.md b/docs/phases/pilot/00-phase-brd.md new file mode 100644 index 0000000..0034cb1 --- /dev/null +++ b/docs/phases/pilot/00-phase-brd.md @@ -0,0 +1,122 @@ +--- +type: phase-brd +phase_id: pilot +title: "Enduro Trails — пилотный проект мультиагентной разработки" +version: 1 +status: approved +created_at: 2026-05-15 +authors: + - "agent:stream" + - "human:slava" +--- + +# BRD — Enduro Trails (пилотный проект) + +## 1. Цель и метрика успеха + +**Цель:** Создать веб-приложение для планирования эндуро-маршрутов с визуализацией грунтовых дорог, рельефа и навигацией — как пилотный проект мультиагентной системы разработки. + +**Метрики успеха:** +- Рабочее приложение доступно по URL (https://openclaw.mva154.duckdns.org/enduro/) +- Покрытие региона: ЦФО + Чувашия (1.1M треков, 14K POI) +- Построение маршрута < 5 секунд +- Мобильный UI (PWA-ready) +- Агентный конвейер: фича от постановки до деплоя ≤ 4 часа + +## 2. Стейкхолдеры + +| Роль | Кто | Интерес | +|------|-----|---------| +| Заказчик / Owner | Слава | Использует для планирования поездок | +| Analyst | Стрим (OpenClaw) | BRD, ТЗ, координация | +| Разработка | Claude Code CLI агенты | Architect, Developer, Reviewer, Tester, Deployer | + +## 3. Scope + +### В скоупе +- Карта грунтовых дорог (MapLibre GL JS, кастомный стиль) +- Роутинг «Дикий путь» (OSRM, кастомный профиль enduro.lua) +- Альтернативные маршруты (до 5 вариантов) +- Промежуточные точки (до 8) +- Статистика покрытия (% грунт/асфальт по типам) +- «Красивый маршрут» (замкнутый круг через POI) +- «Связка» (соединить два трека) +- «Разведка» (грунтовки в радиусе) +- Рельеф (гипсометрия + hillshade, SRTM 30м) +- TRI (Terrain Ruggedness Index) +- Линейка, метки, GPX экспорт +- Тёмная/светлая тема (авто по SunCalc) +- Мобильный UI (bottom sheets, toolbar, touch) +- Поиск (Nominatim geocoding) + +### Вне скоупа (v1) +- PWA офлайн режим +- GPS-трекинг в реальном времени +- Народные треки (Wikiloc, Komoot) +- Профиль высот на маршруте +- Мультирегион (вся Россия) +- Нативное мобильное приложение + +## 4. Архитектура + +### Компоненты +- **Frontend** — MapLibre GL JS, vanilla JS (ES modules), CSS custom properties +- **Backend API** — FastAPI (Python 3.12), uvicorn (4 workers) +- **Tile Server** — статические raster tiles через nginx +- **Vector Tiles** — MVT из SQLite (self-hosted, FastAPI) +- **Routing Engine** — OSRM с кастомным профилем `enduro.lua` +- **Database** — SQLite + Spatialite (431 MB) +- **Reverse Proxy** — nginx (`/enduro/` → контейнер) + +### Инфраструктура +- Один сервер: mva154 (82.22.50.71) +- Docker Compose +- Gitea (git + CI) +- Plane (управление задачами) + +### Данные +- OSM PBF (Geofabrik, ЦФО + Чувашия) +- SRTM 30м (NASA, public domain) +- OSRM граф (~5.2 GB) + +## 5. Реализованные фазы + +| Фаза | Описание | Статус | Дата | +|------|----------|--------|------| +| 1 | MVP: карта + MVT тайлы | ✅ | 02.05.2026 | +| 2 | Роутинг + базовый UI | ✅ | 03.05.2026 | +| 3 | Умный маршрут (альтернативы, статистика, GPX) | ✅ | 04.05.2026 | +| 4 | Продвинутый роутинг (красивый, связка, разведка) | ✅ | 04.05.2026 | +| 5 | Редизайн (тёмная тема, mobile UI, UX) | ✅ | 05-06.05.2026 | +| 5.4 | Рельеф (hillshade + гипсометрия + TRI) | ✅ | 12-14.05.2026 | + +## 6. Бэклог + +| Фаза | Описание | Приоритет | +|------|----------|-----------| +| 3.1 | Улучшение роутинга (шлагбаумы, тротуары, слой препятствий) | Высокий | +| 6 | SRTM продвинутый (профиль высот, «Горка») | Средний | +| 7 | PWA + офлайн | Средний | +| 8 | Народные треки | Низкий | + +## 7. Ключевые решения + +| Решение | Причина | +|---------|---------| +| MapLibre GL JS (не Leaflet) | WebGL, производительность, vector tiles | +| Vanilla JS (не React) | Простота, нет build step, быстрый старт | +| FastAPI (не Django) | Лёгкий, async, минимум зависимостей | +| SQLite/Spatialite (не PostGIS) | Портативность, zero-config, достаточно для 1 региона | +| OSRM (не GraphHopper) | Быстрый, проверенный, кастомный lua-профиль | +| Self-hosted MVT (не TileServer GL) | Меньше зависимостей, контроль над фильтрацией | +| Raster tiles для terrain (не Mapbox Terrain RGB) | Простота генерации, nginx отдаёт статику | +| Docker Compose | Один файл — весь стек | + +## 8. Риски + +| Риск | Митигация | +|------|-----------| +| OSRM граф большой (5.2 GB RAM) | Swap 6 GB настроен | +| SQLite не масштабируется | Миграция на PostGIS при необходимости | +| Один сервер — single point of failure | Бэкапы, Docker restart policy | +| SRTM 30м недостаточно для крутых склонов | Достаточно для ЦФО (равнина) | diff --git a/docs/phases/pilot/01-phase-plan.md b/docs/phases/pilot/01-phase-plan.md new file mode 100644 index 0000000..2a9e4d6 --- /dev/null +++ b/docs/phases/pilot/01-phase-plan.md @@ -0,0 +1,40 @@ +--- +type: phase-plan +phase_id: pilot +title: "План пилотной фазы" +version: 1 +status: active +--- + +# План пилотной фазы — Enduro Trails + +## Текущий статус + +Проект в стадии перехода от прототипа к управляемой мультиагентной разработке. + +### Выполнено (прототип, 02-14.05.2026) +- Фазы 1-5.4 реализованы вручную (Стрим + Dev-агент) +- Все основные фичи работают +- Приложение доступно по URL + +### В процессе (мультиагентная инфраструктура, 15.05.2026) +- ✅ Репо в Gitea с канонической структурой +- ✅ Claude Code CLI авторизован +- ✅ Service account claude-bot +- ✅ Branch protection +- ✅ CI pipeline +- ✅ System prompts агентов +- 🔄 Миграция прототипа в репо + +### Следующие шаги +1. Merge миграции в main +2. Первая задача через полный агентный конвейер (Фаза 1 мультиагентного BRD) +3. Orchestrator MVP (Фаза 2 мультиагентного BRD) + +## Приоритет фич (бэклог) + +1. **F-07 + F-08** — Исключить шлагбаумы и тротуары из OSRM (пересборка графа) +2. **F-10** — Слой препятствий на карте +3. **F-09** — Больше альтернатив (penalized re-query) +4. Профиль высот на маршруте +5. PWA офлайн