Treeline Tracker 🌲🛰️

Treeline Tracker — современная защищенная веб-платформа для координации туристических групп, мониторинга местоположения участников в реальном времени и содействия поисково-спасательным операциям (Search & Rescue / SAR) в условиях дикой природы и высокогорья.

👥 Команда проекта (Core Team)

Разработка ведётся студентами группы ВИС31 направления подготовки 09.03.02 «Информационные системы и технологии» в рамках дисциплины «Проектный практикум»:

Даниил — Проект-менеджер, разработчик (координация, сроки, Канбан-доска, системная архитектура FSD, шифрование).
Александр — Разработчик (функциональные модули, картография, высотные профили, интеграции).
Кирилл — Разработчик (клиентские и серверные компоненты, оптимизация работы системы, гео-хеширование, шифрование).

🚀 Ключевые возможности (Key Features)

🧭 Панель состояния экспедиции (Expedition Status Bar): Сквозной мониторинг статуса геопозиционирования (GPS фикс ±3–5м), активного канала связи (Интернет, MeshCore LoRa, Офлайн-буфер IndexedDB), E2EE-защиты и заряда аккумулятора с быстрым переключателем ролей RBAC.
⛰️ Автономное геоопределение региона и типа маршрута (Zero-Select Architecture): Полный отказ от ручного выбора регионов и видов маршрута. Сервис detectRouteRegion автоматически определяет горный район (Приэльбрусье, Домбай, Безенги, Красная Поляна, Алтай, Байкал/ББТ, Саяны, Хибины, Камчатка, Крым, Урал, Альпы) по координатам, а autoDetectRouteType и autoDetectRoutingProfile классифицируют маршрут на «Горный» / «Равнинный» и подбирают пешеходный профиль на основе уклона ($\ge 15^\circ$), высоты ($\ge 900$м) или набора высоты ($\ge 250$м).
⚡ Физиологическое моделирование энергозатрат и темпа: Расчет расхода энергии туриста по метаболическому уравнению Alberto E. Minetti ($C = 280.5 \cdot i^5 - 58.7 \cdot i^4 - 289.2 \cdot i^3 + 60.1 \cdot i^2 + 52.8 \cdot i + 284.3$ Дж/(кг·км)), пешеходная функция Тоблера (Tobler's Hiking Function) с поправкой на крутизну склонов, шкала сложности SAC (T1–T4) и модальное окно глубокой аналитики рельефа RouteTerrainAnalyticsModal.
🧩 Модульный реестр экранов View Registry и изоляция сбоев: Децентрализованная архитектура представлений view-registry.ts с динамической ленивой загрузкой чанков (React.lazy), централизованной проверкой прав и изоляцией каждого экрана через ViewErrorBoundary. Ошибка в одном представлении не приводит к падению приложения.
💾 Оффлайн-кэш тайлов карты и Zero-Hang Firestore: Двухуровневое кэширование картографических тайлов OpenTopoMap в IndexedDB (treeline_map_tiles_cache) и Service Worker (sw.js). Защита репозиториев от 10-секундных сетевых зависаний Firestore (withFirestoreTimeout) с мгновенным переключением на автономное локальное хранилище.
🛡️ Геозоны безопасности (safeRadiusMeters) и контроль дистанции (FR-002, UC-02): Интерактивная настройка безопасного радиуса группы (от 50 до 10 000м), отрисовка геозоны вокруг лидера на Leaflet, расчет удаления участников по формуле Haversine со статусами INSIDE (в зоне), WARNING (приближение к границе) и BREACH (выход из зоны с тревожным баннером и алертом в аудит-лог).
📡 Адаптивная фильтрация GNSS (Deadband + Throttle, FR-006): Модуль LocationFilter отсекает статическое дрожание координат (< 5м), троттлит частоту отправки (5с) с адаптивным энергосбережением (до 30с при заряде батареи $\le 15%$), пространственным base32 Geohash (стандарт geofire-common) и мгновенным байпасом для сигналов SOS.
🔐 Zero-Knowledge сквозное шифрование (E2EE) и цифровая подпись: Реализация на базе W3C Web Crypto API: аутентифицированное шифрование AES-256-GCM AEAD для сообщений группового чата и телеметрии, цифровая подпись каждого пакета закрытым ключом Ed25519, защита от атак повторного воспроизведения (Anti-Replay) с монотонным sequence и 10-минутным окном свежести. Управление 256-битными симметричными ключами групп в IdentityManager.
🛡️ Комплексная безопасность API и HTTP-заголовки (OWASP): Скользящий Rate Limiter по IP-адресам для предотвращения DoS-атак и злоупотреблений, строгая валидация входящих тел запросов через Zod-схемы на границах всех API-эндпоинтов (включая /api/routes/classify), санитизация серверных ошибок и продакшн-заголовки в next.config.ts (HSTS, CSP, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy, Permissions-Policy).
📡 Многоканальный отказоустойчивый транспорт (TransportManager): Прозрачный каскадный маршрутизатор передачи данных: первичный интернет-канал (Cloud Firestore / HTTPS) ➔ радиосеть LoRa MeshCore (-70..-105 dBm) ➔ персистентная оффлайн-очередь store-and-forward (OfflineQueue) с автоматическим сбросом и дедупликацией при восстановлении связи.
🧪 Хаос-симулятор полевых условий (ChaosSimulator): Встроенная панель хаос-тестирования (FR-024) для моделирования экстремального высокогорья: глушение сотовой связи, экранирование радиоэфира, искусственная потеря пакетов (до 75%), сетевая задержка и критический разряд батареи (8%).
📜 Прозрачный журнал аудита событий (AuditLogger): Сквозной стриминг и экспорт структурированных системных событий по категориям [GPS], [SECURITY], [TRANSPORT], [OCC], [AUTH], [SOS] в JSON-формате.
🔀 Разрешение конфликтов (OCC Engine с авто-ретраем): Оптимистическая блокировка версий (validateAndIncrementVersion) с автоматическим повтором мутаций (withOccRetry) для предотвращения затирания данных при одновременном редактировании треков несколькими гидами.
🛡️ Многоуровневая ролевая модель (RBAC & MFA): Четкое разделение прав (hiker / турист, guide / лидер группы, rescuer / спасатель, admin / администратор) с поддержкой двухфакторной аутентификации (MFA TOTP) и декларативной защитой в firestore.rules.
👤 Профиль туриста и криптографическая идентичность: Интерактивный экран ProfilePage с динамическим индикатором заполненности (0%–100%), локальной генерацией и ротацией ключей Ed25519, визуализацией отпечатка (fingerprint) и селектором режимов геоприватности (NORMAL, REDUCED, STEALTH, EMERGENCY).
🚨 Экстренный диспетчерский пункт и SOS-маяк: Мгновенный сигнал бедствия с фиксацией координат, высоты и заряда батареи, звуковой тревоги, мигания экрана, автоматическим снятием огрубления геоданных и сквозной диспетчеризацией через радиосеть и интернет.
🤖 Безопасный ИИ-поиск пропавших (SAR AI): Построение вероятностных полигонов поиска с учетом рельефа и темпа движения через Genkit и Gemini 2.5 Flash с защитой от Prompt Injection, строгими Zod-схемами, Rate Limiting и неизменяемым аудиторским логом.
🗺️ Интерактивная карта, BRouter-автомаршрутизация и кластеризация: Отрисовка треков на Leaflet с кластеризацией участников (leaflet.markercluster), автоматической трассировкой пеших троп между точками А и Б, расчетом набора/сброса высоты и экспортом в GPX.
📱 Адаптивный эргономичный интерфейс: 5-кнопочная нижняя панель навигации для смартфонов (Карта, Трекер, Маршруты, SOS, Меню) с увеличенными тач-зонами (≥ 44×44px) для работы в перчатках.
🧪 Автоматизированное тестирование (Vitest + RTL): 100% прохождение 152+ интеграционных и юнит-тестов по 13 сьютам (криптография, сквозное E2EE, ролевой доступ, каскадный транспорт, OCC auto-retry, геозоны, оффлайн-очередь IndexedDB, санитизация Base64, rate limiting, физика рельефа, классификация маршрутов и рендеринг компонентов).

📂 Реальная структура проекта (Actual Directory Structure)

Репозиторий сочетает принципы Feature-Sliced Design (FSD) с доменным ядром и интеграциями:

.
├── .github/workflows/      # CI/CD автоматизация (Lint, Typecheck, Secret Scan, Build)
├── .githooks/              # Git-хуки для разработчиков (pre-commit с TruffleHog)
├── docs/                   # Полная архитектурная и продуктовая документация (C4, ADR, RBAC)
├── public/                 # Статические ассеты (иконки, изображения, картографические стили)
├── scripts/                # Скрипты автоматизации и проверки безопасности (secret-scan.mjs)
├── src/
│   ├── app/                # [App Layer] Next.js App Router (layout.tsx, page.tsx, API /api/*)
│   ├── views/              # [Views Layer] Полностраничные модульные экраны (map-view, profile, about, emergency)
│   ├── features/           # [Features Layer] Пользовательские функциональные блоки
│   │   ├── route-drawing/  # Конструктор маршрутов, аналитика рельефа и форма сохранения
│   │   ├── routing/        # Физика рельефа, классификация, Minetti/Tobler и BRouter сервисы
│   │   ├── elevation/      # Сервис высот Open-Meteo DEM и топографическая интерполяция
│   │   ├── hiker-search/   # ИИ-поиск пропавших (SAR AI)
│   │   ├── expedition/     # Expedition Status Bar, телеметрия и модальные окна
│   │   └── group-management/ # Управление туристическими группами и геозонами
│   ├── entities/           # [Entities Layer] Доменные бизнес-сущности (group, route, hiker, app)
│   ├── core/               # [Core Domain] Архитектурное ядро
│   │   ├── domain/         # Интерфейсы доменных моделей и OCC engine (types.ts, schemas.ts, occ.ts)
│   │   ├── location/       # Гео-фильтрация (location-filter.ts, geohash.ts, Haversine, Deadband, Throttle)
│   │   ├── transport/      # Отказоустойчивый транспорт (TransportManager, OfflineQueue, IndexedDB, Chaos)
│   │   ├── security/       # Криптографические протоколы (E2EE AES-GCM, Ed25519, ReplayProtection, api-security.ts)
│   │   ├── repositories/   # Абстракции репозиториев (Firebase / LocalStorage) с защитой от зависаний
│   │   └── utils/          # Вспомогательные утилиты ядра (gpx-exporter.ts)
│   ├── ai/                 # [AI Subsystem] Конфигурация Genkit и модели Gemini 2.5 Flash
│   ├── firebase/           # [Infrastructure] Клиентская инициализация Firebase SDK (persistentLocalCache)
│   ├── shared/             # [Shared Layer] Переиспользуемая инфраструктура (view-registry, offline-map-cache, UI, config)
│   └── test/               # Комплексные автотесты (170 тестов в 14 сьютах: view registry, routing, terrain physics, security, offline, rbac)
├── .env.example            # Эталонный шаблон переменных окружения (без секретов)
├── .gitignore              # Исключения версионного контроля (.env*, .idx/, .modified, ключи)
├── package-lock.json       # Фиксация зависимостей
├── package.json            # Манифест зависимостей и команд запуска
├── firestore.rules         # Декларативные правила безопасности Cloud Firestore (RBAC)
└── firebase-blueprint.json # Спецификация схемы данных Firestore

🔒 Безопасность и автоматические Pre-commit хуки

В проекте действует строгий регламент предотвращения утечек учетных данных:

Pre-commit хуки с TruffleHog: В проекте настроен хук .githooks/pre-commit и скрипт scripts/secret-scan.mjs. При каждом вызове git commit:
- Автоматически вызывается TruffleHog (если установлен локально или через Docker) для глубокого анализа энтропии и паттернов коммита.
- Скрипт scripts/secret-scan.mjs проверяет подготовленные к коммиту файлы (staged files) на наличие API-ключей Gemini/Google (AIzaSy...), приватных ключей (.pem, .key, id_rsa), .env-файлов и JSON-сервисных аккаунтов.
- При обнаружении любого секрета коммит немедленно прерывается с кодом ошибки.
- Активация хуков в локальном репозитории:
```
npm run hooks:install
# или: bun run hooks:install
```
Исключение служебных файлов в .gitignore:
- Файлы окружения .env, .env.local, .env.production
- Служебные каталоги IDE и рабочих окружений: .idx/, .modified
- Приватные криптографические ключи и сертификаты: *.pem, *.key, id_rsa*
Хранение секретов в продакшене: В боевом контуре ключи (GEMINI_API_KEY) передаются через Firebase App Hosting Secrets или Google Secret Manager и никогда не попадают в клиентский бандл.
CI-верификация: В GitHub Actions (.github/workflows/ci.yml) при каждом pull request и push запускаются шаги TruffleHog OSS Scan и проверка репозитория.

🛠️ Менеджер пакетов и технологический стек

Проект поддерживает два основных менеджера пакетов:

Bun (Рекомендуется для локальной разработки): В репозитории присутствует bun.lock, обеспечивающий мгновенную установку зависимостей и высокую скорость выполнения.
npm (Стандартный менеджер Node.js): Полная совместимость для CI/CD-пайплайнов и сред на базе Node.js 20+.

Основной стек:

Frontend & Backend: Next.js 15+ (App Router), React 18, TypeScript 5.
Стилизация: Tailwind CSS, Radix UI Primitives, Lucide Icons.
Картография: Leaflet, React-Leaflet, geofire-common spatial hashing.
База данных и Auth: Cloud Firestore с persistentLocalCache, Firebase Authentication, Firebase Security Rules (RBAC).
Искусственный Интеллект (AI Subsystem): Google Genkit (genkit + @genkit-ai/google-genai) с моделью Gemini 2.5 Flash. Используется для оркестрации поисково-спасательного ИИ-агента (suggestSearchAreasForLostHiker), структурированного Zod-вывода и защищенных серверных флоу.
Криптография и Безопасность: W3C Web Crypto API (Ed25519, AES-256-GCM AEAD, SHA-256), Anti-Replay, TruffleHog scanner.
Тестирование: Vitest 4.x, React Testing Library, JSDOM (57 тестов, 100% pass).
Валидация: Zod runtime schema validation.

⚡️ Быстрый старт (Getting Started)

1. Клонирование репозитория

git clone https://github.com/asakue/Treeline-Tracker.git
cd Treeline-Tracker

2. Установка зависимостей

С использованием Bun (рекомендуется):

bun install

Или с использованием npm:

npm install

3. Активация pre-commit хуков безопасности

# Настраивает Git на использование хуков из каталога .githooks/
bun run hooks:install
# или: npm run hooks:install

4. Настройка переменных окружения

Скопируйте шаблон .env.example в .env.local и укажите необходимые ключи:

cp .env.example .env.local

5. Запуск сервера разработки

С использованием Bun:

bun run dev

Или с использованием npm:

npm run dev

Приложение откроется по адресу http://localhost:3000.

📜 Доступные команды и скрипты (Available Scripts)

Скрипт (npm / Bun)	Описание и назначение	Когда запускать
`npm run dev`	Запуск локального сервера разработки на порту 3000 (Next.js Turbo/HMR).	Во время активной разработки интерфейса и API.
`npm run test`	Запуск полного набора автоматических тестов (Vitest + RTL: 170 тестов по 14 сьютам).	Обязательно перед созданием PR и коммитом.
`npm run test:watch`	Запуск Vitest в интерактивном watch-режиме с мгновенным перезапуском при изменениях.	При разработке новых тестов и TDD.
`npm run typecheck`	Строгая проверка типов TypeScript (`tsc --noEmit`).	Перед каждым коммитом и в CI конвейере.
`npm run lint`	Проверка кода линтером ESLint 9 на соответствие кодстайлу.	Перед коммитом и в CI пайплайне.
`npm run security:scan`	Запуск `scripts/secret-scan.mjs` и сканера TruffleHog на утечки ключей и `.env`.	Обязательно перед деплоем и публикацией релизов.
`npm run analyze`	Запуск production-сборки с анализатором размера бандла (`@next/bundle-analyzer`).	При оптимизации размера клиентских бандлов перед релизом.
`npm run build`	Компиляция оптимизированной production-сборки приложения (Next.js standalone).	При подготовке к деплою в Cloud Run / App Hosting.
`npm run start`	Запуск скомпилированного production-сервера.	На сервере или в Docker-контейнере в проде.
`npm run genkit:dev`	Запуск локальной панели инструментов Genkit Developer UI (`src/ai/dev.ts`).	При тестировании и отладке промптов/флоу ИИ.

Name		Name	Last commit message	Last commit date
.aistudio/artifacts/brain/fd99324f-c8cd-4de6-b521-0eb901dedd25		.aistudio/artifacts/brain/fd99324f-c8cd-4de6-b521-0eb901dedd25
.githooks		.githooks
.github/workflows		.github/workflows
docs		docs
public		public
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
apphosting.yaml		apphosting.yaml
components.json		components.json
eslint.config.mjs		eslint.config.mjs
firebase-blueprint.json		firebase-blueprint.json
firebase.json		firebase.json
firestore.rules		firestore.rules
metadata.json		metadata.json
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository navigation

About

Repository files navigation

Treeline Tracker 🌲🛰️

👥 Команда проекта (Core Team)

🚀 Ключевые возможности (Key Features)

📂 Реальная структура проекта (Actual Directory Structure)

🔒 Безопасность и автоматические Pre-commit хуки

🛠️ Менеджер пакетов и технологический стек

⚡️ Быстрый старт (Getting Started)

1. Клонирование репозитория

2. Установка зависимостей

3. Активация pre-commit хуков безопасности

4. Настройка переменных окружения

5. Запуск сервера разработки

📜 Доступные команды и скрипты (Available Scripts)

📚 Документация проекта

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Treeline Tracker 🌲🛰️

👥 Команда проекта (Core Team)

🚀 Ключевые возможности (Key Features)

📂 Реальная структура проекта (Actual Directory Structure)

🔒 Безопасность и автоматические Pre-commit хуки

🛠️ Менеджер пакетов и технологический стек

⚡️ Быстрый старт (Getting Started)

1. Клонирование репозитория

2. Установка зависимостей

3. Активация pre-commit хуков безопасности

4. Настройка переменных окружения

5. Запуск сервера разработки

📜 Доступные команды и скрипты (Available Scripts)

📚 Документация проекта

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages