docs: restructure phases — per-phase BRD, remove monolithic pilot BRD

This commit is contained in:
2026-05-18 08:47:22 +03:00
parent f561c3bd41
commit 832099c3c6
14 changed files with 439 additions and 162 deletions

View File

@@ -48,6 +48,22 @@
6. Коммиты от имени claude-bot (git config user.name/email уже настроен).
7. Не использовать `--no-verify` без явного одобрения Owner.
## Фазы
| # | Название | Описание |
|---|----------|----------|
| PH-1 | MVP | Карта грунтовок + MVT тайлы |
| PH-2 | Routing | OSRM роутинг + базовый UI |
| PH-3 | Smart Route | Альтернативы, статистика, GPX |
| PH-4 | Advanced Routing | Красивый маршрут, связка, разведка |
| PH-5 | Redesign | Тёмная тема, mobile UI, UX |
| PH-6 | Terrain | Hillshade + гипсометрия + TRI |
| PH-7 | Barriers | Шлагбаумы, тротуары, слой препятствий |
| PH-8 | Elevation Profile | Профиль высот, режим «Горка» |
| PH-9 | PWA | Офлайн режим |
Детали каждой фазы: [docs/phases/](docs/phases/)
## Данные
- Terrain tiles: /home/slin/enduro-trails/data/terrain/ (hillshade, TRI, hypso)
- OSM данные: /home/slin/enduro-trails/data/osm/

View File

@@ -68,6 +68,22 @@ migrations/ — миграции БД
.openclaw/ — system prompts агентов
```
## Фазы
| # | Название | Описание |
|---|----------|----------|
| PH-1 | MVP | Карта грунтовок + MVT тайлы |
| PH-2 | Routing | OSRM роутинг + базовый UI |
| PH-3 | Smart Route | Альтернативы, статистика, GPX |
| PH-4 | Advanced Routing | Красивый маршрут, связка, разведка |
| PH-5 | Redesign | Тёмная тема, mobile UI, UX |
| PH-6 | Terrain | Hillshade + гипсометрия + TRI |
| PH-7 | Barriers | Шлагбаумы, тротуары, слой препятствий |
| PH-8 | Elevation Profile | Профиль высот, режим «Горка» |
| PH-9 | PWA | Офлайн режим |
Детали каждой фазы: [docs/phases/](docs/phases/)
## Лицензия
Данные: © OpenStreetMap contributors (ODbL)

View File

@@ -6,3 +6,15 @@
- [design/](./design/) — дизайн-токены, компоненты
- [operations/](./operations/) — runbook, мониторинг
- [api/](./api/) — OpenAPI спецификация
## Фазы
- [PH-1.mvp](./phases/PH-1.mvp/) — MVP: карта грунтовок + MVT тайлы
- [PH-2.routing](./phases/PH-2.routing/) — OSRM роутинг + базовый UI
- [PH-3.smart-route](./phases/PH-3.smart-route/) — Альтернативы, статистика, GPX
- [PH-4.advanced-routing](./phases/PH-4.advanced-routing/) — Красивый маршрут, связка, разведка
- [PH-5.redesign](./phases/PH-5.redesign/) — Тёмная тема, mobile UI, UX
- [PH-6.terrain](./phases/PH-6.terrain/) — Hillshade + гипсометрия + TRI
- [PH-7.barriers](./phases/PH-7.barriers/) — Шлагбаумы, тротуары, слой препятствий
- [PH-8.elevation-profile](./phases/PH-8.elevation-profile/) — Профиль высот, режим «Горка»
- [PH-9.pwa](./phases/PH-9.pwa/) — Офлайн режим

View File

@@ -0,0 +1,46 @@
---
type: phase-brd
phase_id: PH-1.mvp
title: "MVP: карта грунтовок ЦФО + MVT тайлы"
version: 1
status: done
created_at: 2026-05-18
authors:
- "agent:stream"
---
# PH-1 — MVP: карта грунтовок ЦФО
## Цель
Создать веб-карту с фокусом на грунтовые дороги: грунтовки и тропы — главный слой, асфальт — тусклый фон. Данные из OSM, отображение через MapLibre GL JS с кастомным стилем.
## Scope
- Загрузка OSM PBF (Geofabrik, ЦФО + Чувашия)
- Конвертация в SQLite/Spatialite (1.1M треков, 14K POI)
- Self-hosted MVT (vector tiles) через FastAPI
- MapLibre GL JS с кастомным стилем (грунтовки яркие, асфальт тусклый)
- Деплой через Docker Compose на mva154
## Что реализовано
- FastAPI backend с эндпоинтами для MVT тайлов
- SQLite/Spatialite БД с данными ЦФО + Чувашия
- Кастомный стиль MapLibre: цветовая дифференциация по типу покрытия (track grade 1-5)
- Docker Compose конфигурация
- nginx reverse proxy (`/enduro/` → контейнер)
## Ключевые решения
| Решение | Причина |
|---------|---------|
| MapLibre GL JS (не Leaflet) | WebGL, производительность, vector tiles |
| Vanilla JS (не React) | Простота, нет build step, быстрый старт |
| FastAPI (не Django) | Лёгкий, async, минимум зависимостей |
| SQLite/Spatialite (не PostGIS) | Портативность, zero-config, достаточно для 1 региона |
| Self-hosted MVT (не TileServer GL) | Меньше зависимостей, контроль над фильтрацией |
## Дата завершения
02.05.2026

View File

@@ -0,0 +1,43 @@
---
type: phase-brd
phase_id: PH-2.routing
title: "Роутинг: OSRM с кастомным эндуро-профилем"
version: 1
status: done
created_at: 2026-05-18
authors:
- "agent:stream"
---
# PH-2 — Роутинг: «Дикий путь»
## Цель
Добавить построение маршрутов с приоритетом грунтовых дорог. Использовать OSRM с кастомным Lua-профилем, оптимизированным под эндуро.
## Scope
- Кастомный профиль `enduro.lua` для OSRM (приоритет грунтовок, штраф за асфальт)
- Пересборка OSRM графа из OSM PBF (~5.2 GB)
- Базовый UI для построения маршрута (точка А → Б)
- Отображение маршрута на карте
## Что реализовано
- OSRM с профилем enduro.lua (веса: track > path > unclassified > tertiary > secondary)
- API эндпоинт `/api/route` (FastAPI → OSRM)
- UI: клик по карте для установки точек старта/финиша
- Отображение маршрута (GeoJSON LineString на карте)
- Docker-сервис OSRM в compose
## Ключевые решения
| Решение | Причина |
|---------|---------|
| OSRM (не GraphHopper) | Быстрый, проверенный, кастомный lua-профиль |
| Кастомный enduro.lua | Стандартные профили не учитывают грунтовки как приоритет |
| Swap 6 GB | OSRM граф требует ~5.2 GB RAM |
## Дата завершения
03.05.2026

View File

@@ -0,0 +1,43 @@
---
type: phase-brd
phase_id: PH-3.smart-route
title: "Умный маршрут: альтернативы, статистика, GPX"
version: 1
status: done
created_at: 2026-05-18
authors:
- "agent:stream"
---
# PH-3 — Умный маршрут
## Цель
Предоставить пользователю выбор из нескольких вариантов маршрута с разным балансом грунт/асфальт. Показать статистику покрытия и дать возможность экспорта в GPX.
## Scope
- До 5 альтернативных маршрутов с разным балансом грунт/асфальт
- Промежуточные точки (до 8)
- Статистика покрытия (% по типам: track, path, unclassified, tertiary, secondary, primary)
- GPX экспорт (трек + waypoints)
## Что реализовано
- Мульти-запрос к OSRM с варьированием весов профиля
- UI выбора альтернатив (карточки с превью и статистикой)
- Drag-and-drop промежуточных точек на карте
- Панель статистики: дистанция, время, % грунта/асфальта по типам
- GPX экспорт с метаданными (имя маршрута, waypoints, timestamps)
## Ключевые решения
| Решение | Причина |
|---------|---------|
| Варьирование весов (не OSRM alternatives) | OSRM alternatives даёт похожие маршруты; варьирование весов — реально разные |
| До 8 промежуточных точек | Баланс между гибкостью и UX |
| GPX 1.1 формат | Совместимость с большинством навигаторов |
## Дата завершения
04.05.2026

View File

@@ -0,0 +1,42 @@
---
type: phase-brd
phase_id: PH-4.advanced-routing
title: "Продвинутый роутинг: красивый маршрут, связка, разведка"
version: 1
status: done
created_at: 2026-05-18
authors:
- "agent:stream"
---
# PH-4 — Продвинутый роутинг
## Цель
Добавить три специализированных режима маршрутизации: «Красивый маршрут» (замкнутый круг через POI), «Связка» (соединить два трека грунтовками), «Разведка» (статистика грунтовок в радиусе).
## Scope
- **Красивый маршрут** — замкнутый круг заданной длины через живописные POI (озёра, виды, руины, броды)
- **Связка** — соединить два загруженных трека оптимальным грунтовым участком
- **Разведка** — показать статистику грунтовок в радиусе 20/50/100 км от точки
## Что реализовано
- Алгоритм «Красивый маршрут»: выбор POI в радиусе → TSP-оптимизация порядка → OSRM route
- UI загрузки GPX для режима «Связка»
- Алгоритм соединения: найти ближайшие точки двух треков → построить грунтовый мост
- «Разведка»: spatial query по SQLite → агрегация по типам → визуализация на карте (heatmap)
- Переключение режимов в toolbar
## Ключевые решения
| Решение | Причина |
|---------|---------|
| TSP через nearest-neighbor heuristic | Достаточно для 5-10 POI, O(n²) приемлемо |
| Spatialite для spatial queries | Уже есть в стеке, не нужен отдельный сервис |
| Радиусы 20/50/100 км | Покрывают типичные дневные маршруты |
## Дата завершения
04.05.2026

View File

@@ -0,0 +1,50 @@
---
type: phase-brd
phase_id: PH-5.redesign
title: "Редизайн: тёмная тема, mobile UI, UX"
version: 1
status: done
created_at: 2026-05-18
authors:
- "agent:stream"
---
# PH-5 — Редизайн
## Цель
Переработать UI/UX приложения: добавить тёмную/светлую тему с автопереключением, адаптировать под мобильные устройства, улучшить юзабилити (линейка, метки, поиск).
## Scope
- Тёмная/светлая тема (авто по SunCalc — переключение по закату/рассвету)
- Mobile UI: bottom sheets, toolbar, touch-оптимизация
- Линейка (измерение расстояний на карте)
- Метки (сохранение точек интереса, localStorage)
- Поиск (Nominatim geocoding)
- CSS custom properties для theming
- Синхронизация темы карты и UI
## Что реализовано
- Система тем: CSS custom properties, авто (SunCalc), ручное переключение
- Стиль карты MapLibre синхронизирован с UI-темой
- Bottom sheet для мобильных (маршрут, статистика, настройки)
- Toolbar с иконками (режимы, инструменты)
- Touch-события: long press для метки, swipe для bottom sheet
- Линейка: клик-клик для измерения, отображение дистанции
- Метки: создание, редактирование, удаление, persist в localStorage
- Поиск: Nominatim API, debounce, fly-to результату
## Ключевые решения
| Решение | Причина |
|---------|---------|
| SunCalc для авто-темы | Точное время заката для координат пользователя |
| CSS custom properties | Нативный theming без препроцессоров |
| Bottom sheets (не sidebar) | Мобильный паттерн, thumb-friendly |
| localStorage для меток | Простота, нет backend-зависимости |
## Дата завершения
05-06.05.2026

View File

@@ -0,0 +1,48 @@
---
type: phase-brd
phase_id: PH-6.terrain
title: "Рельеф: гипсометрия + hillshade + TRI"
version: 1
status: done
created_at: 2026-05-18
authors:
- "agent:stream"
---
# PH-6 — Рельеф
## Цель
Добавить визуализацию рельефа: гипсометрическая раскраска, hillshade (теневой рельеф), TRI (Terrain Ruggedness Index) для оценки сложности местности.
## Scope
- Загрузка и обработка SRTM 30м (NASA, public domain)
- Генерация raster tiles: гипсометрия, hillshade, TRI
- Раздача через nginx (статические файлы)
- UI: переключение слоёв рельефа, прозрачность
- Легенда для гипсометрии и TRI
## Что реализовано
- Pipeline обработки SRTM: скачивание → merge → reproject → tile generation
- Гипсометрия: цветовая шкала высот (зелёный → коричневый → белый)
- Hillshade: azimuth 315°, altitude 45°, z-factor 1.5
- TRI: классификация (flat, nearly flat, slightly rugged, rugged, very rugged)
- Raster tiles zoom 8-14, формат PNG
- nginx location для раздачи tiles
- UI: layer switcher с opacity slider
- Легенда с цветовой шкалой
## Ключевые решения
| Решение | Причина |
|---------|---------|
| Raster tiles (не Mapbox Terrain RGB) | Простота генерации, nginx отдаёт статику |
| SRTM 30м | Бесплатно, достаточно для ЦФО (равнина) |
| Zoom 8-14 | Баланс между детализацией и объёмом данных |
| TRI как отдельный слой | Помогает оценить сложность без профиля высот |
## Дата завершения
12-14.05.2026

View File

@@ -0,0 +1,51 @@
---
type: phase-brd
phase_id: PH-7.barriers
title: "Барьеры: исключить шлагбаумы и тротуары, слой препятствий"
version: 1
status: active
created_at: 2026-05-18
authors:
- "agent:stream"
---
# PH-7 — Барьеры
## Цель
Сделать роутинг безопасным: маршрут не проходит через физические препятствия (шлагбаумы) и запрещённые для мотоциклов дороги (тротуары, пешеходные зоны). Добавить визуальный слой препятствий на карту.
## Scope
### F-07: Исключить шлагбаумы из OSRM
- Ноды с `barrier=gate|bollard|lift_gate|chain|cycle_barrier|motorcycle_barrier|border_control|block``mode.inaccessible` в OSRM
- `cattle_grid` и `ford` — оставить (проезжие)
### F-08: Исключить тротуары из OSRM
- Ways с `highway=footway|pedestrian|steps|corridor` → исключить из графа (return в process_way)
### F-10: Слой препятствий на карте
- Визуализация шлагбаумов, ворот, блоков на карте
- Иконки по типу барьера
- Popup с информацией (тип, OSM ID)
## Метрики успеха
- Маршрут через точку с шлагбаумом → OSRM обходит или возвращает "не найден"
- Маршрут в городе → не проходит по тротуарам
- Время пересборки графа ≤ 60 мин
- Существующие маршруты без шлагбаумов/тротуаров — не ломаются
## Зависимости
- OSRM граф (пересборка с обновлённым enduro.lua)
- OSM PBF данные (уже есть)
- Work item: [ET-001](../../work-items/ET-001/)
## Риски
| Риск | Митигация |
|------|-----------|
| Пересборка графа ~40 мин (сервис недоступен) | Пересобирать ночью или в low-traffic |
| Слишком много заблокированных нод → маршруты не строятся | cattle_grid и ford оставлены; тестировать на реальных маршрутах |
| OSRM RAM при пересборке | Swap 6 GB уже настроен |

View File

@@ -0,0 +1,35 @@
---
type: phase-brd
phase_id: PH-8.elevation-profile
title: "Профиль высот на маршруте, режим «Горка»"
version: 1
status: planned
created_at: 2026-05-18
authors:
- "agent:stream"
---
# PH-8 — Профиль высот
## Цель
Показать профиль высот построенного маршрута. Добавить режим «Горка» — поиск участков с максимальным перепадом высот (подъёмы/спуски).
## Scope
- Профиль высот: график elevation по дистанции для построенного маршрута
- Данные высот из SRTM 30м (уже есть в PH-6)
- Интерактивный график: hover → маркер на карте
- Статистика: набор высоты, сброс высоты, макс/мин высота
- Режим «Горка»: поиск участков с перепадом > N метров в радиусе
## Зависимости
- PH-6 (SRTM данные, terrain pipeline)
- PH-2/PH-3 (роутинг, маршруты)
## Открытые вопросы
- Формат графика: Canvas или SVG?
- Сэмплирование точек: каждые N метров или адаптивное?
- «Горка»: порог перепада настраиваемый или фиксированный?

View File

@@ -0,0 +1,37 @@
---
type: phase-brd
phase_id: PH-9.pwa
title: "PWA: офлайн режим, кэширование тайлов"
version: 1
status: planned
created_at: 2026-05-18
authors:
- "agent:stream"
---
# PH-9 — PWA офлайн
## Цель
Сделать приложение доступным офлайн: Service Worker для кэширования, предзагрузка тайлов для выбранного региона, сохранение маршрутов локально.
## Scope
- Service Worker: кэширование статики (JS, CSS, шрифты, иконки)
- Предзагрузка тайлов: выбрать область на карте → скачать тайлы для офлайн
- Кэширование vector tiles (MVT) и raster tiles (terrain)
- Офлайн-роутинг: сохранение построенных маршрутов для просмотра без сети
- Install prompt (Add to Home Screen)
- Manifest.json
## Зависимости
- PH-1 (MVT тайлы)
- PH-6 (raster terrain tiles)
- Все предыдущие фазы (UI, роутинг)
## Открытые вопросы
- Лимит кэша (сколько тайлов можно скачать?)
- Стратегия инвалидации кэша
- Офлайн-роутинг: только просмотр сохранённых или локальный OSRM?

View File

@@ -1,122 +0,0 @@
---
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м недостаточно для крутых склонов | Достаточно для ЦФО (равнина) |

View File

@@ -1,40 +0,0 @@
---
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 офлайн