ParkTrack Admin

Русский | English

Фронтенд ParkTrack для администрирования парковочной системы, просмотра аналитики и разметки парковочных зон на кадрах камер и карте.

Приложение работает с backend из api-server, использует ролевой доступ и объединяет в одном интерфейсе пользователей, партнёров, камеры, зоны, источники данных, аналитику и геометрию парковок.

Возможности

Авторизация и профиль

• регистрация и вход через ParkTrack API;
• сохранение и проверка сессии после обновления страницы;
• автоматический выход при недействительной backend-сессии;
• отдельный сценарий восстановления пароля по email;
• просмотр и редактирование данных профиля;
• смена пароля;
• просмотр партнёрских ролей и доступов без внутренней технической информации.

Обзор

• сводные показатели по камерам, зонам, свободным местам и уверенности модели;
• зоны внимания в первом экране;
• быстрые переходы к камерам, зонам, пользователям и профилю;
• недавно обновлённые камеры;
• камеры без координат и зоны с неполной геометрией;
• адаптивные карточки без вывода внутренних API, database и permission-метрик.

Аналитика

• сводная аналитика по доступным парковочным зонам и камерам;
• выбор временного периода и детализации;
• выбор среза прогноза через forecast_created_at;
• ручное обновление и настраиваемое автообновление;
• закреплённая панель управления при прокрутке;
• взаимоисключающий выбор зон или камер для понятного аналитического среза;
• графики фактической и прогнозируемой занятости;
• графики количества наблюдений и уверенности модели;
• кликабельные точки и подробные tooltips;
• относительное время свежести данных;
• качество прогноза;
• таблица состояния всех зон с названиями камер, прокруткой и цветными статусами;
• карта зон и камер;
• отдельные страницы аналитики зоны, камеры и запуска распознавания;
• оценка качества распознавания и просмотр feedback;
• независимое кеширование последнего кадра, последней детекции и размеченного снимка до обновления страницы;
• переключение снимков и обновление текущего кадра в полноэкранном просмотре.

Пользователи

• список, поиск и фильтрация пользователей;
• создание пользователя;
• просмотр и редактирование профиля, глобальной роли и активности;
• добавление найденного пользователя в партнёра;
• просмотр партнёрских memberships и доступов;
• горизонтальная прокрутка широких таблиц;
• массовая активация, деактивация и удаление выбранных пользователей.

Партнёры

• список, создание, редактирование и удаление партнёров;
• необязательные contact_email и contact_phone;
• управление сотрудниками партнёра;
• настройка партнёрской роли и read / write / delete scopes;
• массовая активация, деактивация и удаление выбранных партнёров.

Камеры

• список, поиск и фильтрация камер;
• создание, редактирование и удаление;
• автоматическое определение размера изображения;
• вертикальная прокрутка списка камер;
• Яндекс.Карта с выбором и позиционированием камеры;
• кеширование свежего кадра, кадра последней детекции и размеченного snapshot;
• переключение между текущим кадром, последним распознаванием и визуализацией распознавания;
• полноэкранный просмотр снимков;
• переход к настройке и разметке конкретной камеры;
• массовая активация, деактивация и удаление выбранных камер.

Парковочные зоны

• список и расширенная фильтрация;
• редактирование типа зоны, вместимости, цены, расположения и флагов;
• поддерживаемые расположения: street, yard, open_lot, underground, multilevel;
• флаги активности, частной парковки и парковки для инвалидов;
• создание зон через разметку кадра камеры;
• редактирование геометрии на изображении и Яндекс.Карте;
• перемещение вершин и линий полигона;
• отображение остальных зон камеры во время разметки;
• массовая активация, деактивация и удаление выбранных зон.

Источники данных

• реестр источников;
• фильтры и горизонтальная прокрутка таблицы;
• просмотр подробностей источника;
• переход к связанной сущности.

Интерфейс разметки

• открывается из конкретной камеры или зоны;
• создание и редактирование полигонов поверх snapshot;
• редактирование точек поверх пересекающихся зон;
• перемещение кадра средней или правой кнопкой мыши;
• перемещение двумя пальцами на touch-устройствах;
• масштабирование колёсиком;
• кеширование snapshot до выхода из камеры;
• полноэкранная рабочая область;
• автоматическое заполнение и центрирование кадра при входе в fullscreen;
• отдельная кнопка повторного центрирования кадра;
• переход к геометрии камеры и зоны на Яндекс.Карте;
• сохранение настроек камеры и свойств зоны;
• единый feedback после действий.

Шорткаты интерфейса разметки:

Клавиша	Действие
N	начать создание зоны
E	редактировать выбранный полигон
S	сохранить выбранную зону
M	открыть геометрию зоны на карте
Esc	отменить рисование или вернуться к выбору

Шорткаты не срабатывают во время ввода текста в поля формы.

Feedback и обработка ошибок

• единый слой success, warning, info и error уведомлений;
• подтверждение опасных действий;
• понятные сообщения для API-ошибок 4xx;
• отдельные состояния загрузки, отсутствия данных и частично недоступных блоков;
• Error Boundary для защиты приложения от белого экрана.

Навигация и доступы

Приложение использует hash-routing:

Маршрут	Назначение
#/	обзор
#/login	вход
#/register	регистрация
#/password-reset	восстановление пароля
#/profile	профиль
#/analytics	аналитика
#/users	пользователи
#/partners	партнёры
#/cameras	камеры
#/zones	зоны
#/sources	источники
#/labeler	разметка выбранной камеры

Разделы sidebar и прямые маршруты проверяют permissions текущей сессии. Например:

• камеры: cameras.view;
• зоны: zones.view;
• источники: sources.view;
• пользователи: admin.users.view или partner_members.view;
• партнёры: admin.partners.view;
• аналитика: admin, admin.analytics.view, analytics.view или активное membership партнёра.

#/labeler не является самостоятельным главным разделом. Без выбранной камеры приложение возвращает пользователя к списку камер.

Администратор может смотреть данные всех партнёров. Пользователь с membership работает в контексте доступного ему партнёра.

Стек

• React 18;
• TypeScript;
• Vite;
• Zustand;
• Konva и React Konva;
• Yandex Maps JS API 2.1;
• nginx для production-контейнера.

Структура проекта

src/
  api/          API-клиенты и контракты
  auth/         состояние backend-сессии
  components/   камеры, разметчик, карты и UI-компоненты
  feedback/     уведомления и подтверждения
  geometry/     преобразования и операции с полигонами
  layout/       shell административной панели
  maps/         загрузка и helpers Яндекс.Карт
  pages/        страницы административных разделов
  router/       hash-routing
  store/        состояние камеры, зон и разметки

Требования

• Node.js 18+;
• npm;
• запущенный backend из api-server;
• доступный PostgreSQL backend-а;
• ключ Яндекс.Карт для полноценной работы карт.

Локальный backend обычно доступен по адресу:

http://127.0.0.1:8000/api/v1

Переменные окружения

Создайте .env на основе .env.example:

VITE_API_BASE_URL=http://127.0.0.1:8000/api/v1
VITE_YANDEX_MAPS_API_KEY=your-yandex-maps-api-key
VITE_ANALYTICS_STALE_MINUTES=10

Переменная	Назначение
VITE_API_BASE_URL	базовый URL ParkTrack API
VITE_YANDEX_MAPS_API_KEY	ключ Yandex Maps JS API 2.1
VITE_ANALYTICS_STALE_MINUTES	порог, после которого аналитические данные считаются устаревшими

Для совместимости карт также поддерживается старое имя VITE_YMAPS_API_KEY, однако использовать следует VITE_YANDEX_MAPS_API_KEY.

Если VITE_API_BASE_URL не задан:

• на localhost используется http://127.0.0.1:8000/api/v1;
• на остальных доменах используется относительный путь /api/v1.

API URL задаётся при сборке и не редактируется конечным пользователем через интерфейс.

Локальный запуск

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

npm install

Запуск dev-сервера:

npm run dev

Приложение будет доступно по адресу:

http://localhost:5173

Production-сборка

Проверка TypeScript и сборка Vite:

npm run build

Локальный просмотр production-сборки:

npm run preview

Docker-сборка принимает API URL как build argument:

docker build \
  --build-arg VITE_API_BASE_URL=https://api.example.com/api/v1 \
  -t parktrack-admin .

Production-образ собирает приложение на Node.js и отдаёт содержимое dist через nginx.

Backend-контракты

Фронтенд использует следующие основные группы ParkTrack API:

• /auth;
• /users;
• /partners;
• /cameras;
• /zones;
• /sources;
• /occupancy;
• /forecasts;
• /admin/analytics;
• /health;
• /version.

Для /cameras/{camera_id}/snapshot поддерживаются три режима:

• без query-параметров — свежий кадр из видеопотока;
• last_detection=true — кадр, сохранённый в момент последней детекции;
• annotated=true&fallback_to_raw=true — визуализация распознавания с возможным fallback на обычный кадр.

Обычный кадр и кадр последней детекции требуют cameras.view. Для визуализации распознавания backend дополнительно проверяет admin.monitoring.view.

Основные analytics endpoints:

• /admin/analytics/summary;
• /admin/analytics/update-frequency;
• /admin/analytics/confidence;
• /admin/analytics/occupancy-history;
• /admin/analytics/occupancy-forecast;
• /admin/analytics/occupancy-heatmap;
• /admin/analytics/observations-rate;
• /admin/analytics/detector-health;
• /admin/analytics/forecast-quality;
• /admin/analytics/cameras/{camera_id}/detections;
• /admin/analytics/detections/{detection_run_id};
• /admin/analytics/detections/{detection_run_id}/feedback.

Защищённые запросы отправляются с bearer-токеном текущей сессии. Сессия сохраняется в localStorage, переживает обновление страницы и валидируется через /auth/me.

Правила разработки

• сохранять существующие API-контракты и permission checks;
• не добавлять ручную настройку API URL в пользовательский интерфейс;
• крупные изменения разделять на небольшие семантические коммиты;
• после изменений интерфейса проверять desktop и mobile layouts;
• перед push обязательно запускать npm run build.