# CLAUDE.md — паспорт проекта enduro-trails

## TL;DR
Карта эндуро-маршрутов с рельефом, навигацией и слоями terrain/TRI/hillshade.
Веб-приложение для планирования офф-роуд маршрутов с учётом сложности рельефа.

## Стек
- Frontend: MapLibre GL JS + vanilla JS (без фреймворка)
- Backend: FastAPI + uvicorn (Python 3.12)
- БД: SQLite (Spatialite) → PostGIS (при масштабировании)
- Тайлы: self-hosted raster tiles (terrain, hillshade, TRI)
- Роутинг: OSRM (кастомный эндуро-профиль)
- Контейнеризация: Docker + Compose
- CI/CD: Gitea Actions
- Деплой: docker compose up -d на mva154

## Команды
- `make dev` — поднять локально
- `make test` — все тесты
- `make lint` — линтеры (ruff + eslint)
- `make build` — собрать Docker-образ
- `make deploy-test` — деплой в test

## Среды
- **dev** — локально, http://localhost:5556
- **test** — https://openclaw.mva154.duckdns.org/enduro/

## Структура
- `src/api/` — FastAPI backend (маршруты, тайлы, поиск)
- `src/web/` — фронтенд (MapLibre, UI компоненты)
- `tests/` — тесты (unit, integration, e2e)
- `docs/` — документация, ADR, work-items
- `scripts/` — утилиты (lint, coverage, deploy)
- `migrations/` — миграции БД

## Конвенции
- Conventional Commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`)
- Ветки: `feature/PROJ-NNN-slug`, `bugfix/PROJ-NNN-slug`
- ADR: `docs/work-items/<work-item-id>/06-adr/<slug>.md` (per work-item ADRs)
- Global ADR: `docs/architecture/adr/adr-NNNN-slug.md` (cross-cutting decisions)
- Work items: `docs/work-items/<plane-id>/`

## Правила для агентов
1. Перед любым действием прочесть этот файл и `docs/architecture/README.md`.
2. Никогда не править артефакты других этапов.
3. Никогда не комментировать ТЗ задним числом — если ТЗ не годится, возвращай в Анализ.
4. Никогда не закрывать задачу самостоятельно — это делает CI.
5. Бюджет токенов на задачу — в `.openclaw/budget.yaml`.
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/
- OSRM графы: /home/slin/enduro-trails/data/osrm/

