From 15e25637c1036aa622ff94d777016c55f25a7b0b Mon Sep 17 00:00:00 2001 From: 666mxvbee Date: Thu, 4 Jun 2026 21:59:37 +0300 Subject: [PATCH] docs: update frontend feature guide --- README.md | 453 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 312 insertions(+), 141 deletions(-) diff --git a/README.md b/README.md index 1175b0e..43934ae 100644 --- a/README.md +++ b/README.md @@ -1,184 +1,355 @@ # ParkTrack Admin -Админ-панель и интерфейс разметки ParkTrack. Приложение работает с backend из `api-server`, управляет пользователями, партнёрами, камерами, зонами, источниками данных и геометрией разметки. - -## Что есть в приложении - -- `Auth` - - регистрация - - логин / logout - - проверка текущей сессии через API - - восстановление пароля через отдельную страницу -- `Dashboard` - - обзор системы - - health / version - - быстрые переходы по основным ресурсам - - мягкая обработка недоступных необязательных данных -- `Users` - - список пользователей - - создание пользователя - - просмотр карточки - - редактирование профиля, роли и активности - - добавление пользователя в партнёра из карточки пользователя - - просмотр партнёрских доступов - - bulk actions: активировать, деактивировать, удалить выбранных пользователей -- `Partners` - - список партнёров - - создание / редактирование / удаление - - управление участниками партнёра - - настройка роли и read / write / delete scopes - - bulk actions: активировать, деактивировать, удалить выбранных партнёров -- `Cameras` - - список и фильтры - - создание / редактирование / удаление - - автоматическое определение размера изображения при добавлении камеры - - snapshot preview - - fullscreen preview для распознанных автомобилей - - переход в разметку и привязку камеры на карте - - bulk actions: активировать, деактивировать, удалить выбранные камеры -- `Zones` - - список и фильтры - - создание через интерфейс разметки - - редактирование атрибутов - - удаление - - переход в image geometry и map geometry - - редактирование точек и линий геометрии на карте - - bulk actions: активировать, деактивировать, удалить выбранные зоны -- `Sources` - - реестр источников данных - - список, фильтры, detail panel - - переход к профильной сущности -- `Labeler` - - редактирование зон на изображении - - полноэкранный режим рабочей области - - перемещение изображения в рабочей области - - добавление точек поверх существующих зон без случайного выбора старой зоны - - map entrypoint для геометрии - - возврат обратно в админский контекст -- `Feedback` - - единый слой уведомлений - - подтверждения опасных действий - - корректные сообщения для API-ошибок 4xx - -## Основные маршруты +Фронтенд 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: -- `#/` — dashboard -- `#/login` -- `#/register` -- `#/password-reset` -- `#/profile` -- `#/users` -- `#/partners` -- `#/cameras` -- `#/zones` -- `#/sources` -- `#/labeler` - -Раздел `Разметка` не открывается как отдельный главный модуль из sidebar. В нормальном сценарии в него попадают из конкретной камеры или зоны. +| Маршрут | Назначение | +| --- | --- | +| `#/` | обзор | +| `#/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 + TypeScript + Vite` -- `zustand` -- `react-konva` -- `Yandex Maps JS API 2.1` +- React 18; +- TypeScript; +- Vite; +- Zustand; +- Konva и React Konva; +- Yandex Maps JS API 2.1; +- nginx для production-контейнера. + +## Структура проекта + +```text +src/ + api/ API-клиенты и контракты + auth/ состояние backend-сессии + components/ камеры, разметчик, карты и UI-компоненты + feedback/ уведомления и подтверждения + geometry/ преобразования и операции с полигонами + layout/ shell административной панели + maps/ загрузка и helpers Яндекс.Карт + pages/ страницы административных разделов + router/ hash-routing + store/ состояние камеры, зон и разметки +``` ## Требования -- `Node.js 18+` -- запущенный backend из `api-server` -- доступный ParkTrack API +- Node.js 18+; +- npm; +- запущенный backend из `api-server`; +- доступный PostgreSQL backend-а; +- ключ Яндекс.Карт для полноценной работы карт. -Для локальной разработки backend обычно доступен по адресу: +Локальный backend обычно доступен по адресу: ```text http://127.0.0.1:8000/api/v1 ``` +## Переменные окружения + +Создайте `.env` на основе `.env.example`: + +```env +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 задаётся при сборке и не редактируется конечным пользователем через интерфейс. + ## Локальный запуск +Установка зависимостей: + ```bash npm install +``` + +Запуск dev-сервера: + +```bash npm run dev ``` -По умолчанию dev-сервер поднимается на: +Приложение будет доступно по адресу: ```text http://localhost:5173 ``` -## API base URL +## Production-сборка -В production и staging адрес API задаётся через переменную окружения на этапе сборки: +Проверка TypeScript и сборка Vite: -```env -VITE_API_BASE_URL=https://api.dev.parktrack.live/api/v1 -VITE_YANDEX_MAPS_API_KEY=your-yandex-maps-api-key +```bash +npm run build ``` -Если переменная не задана: - -- на `localhost` приложение использует `http://127.0.0.1:8000/api/v1` -- на остальных доменах приложение использует относительный путь `/api/v1` +Локальный просмотр production-сборки: -Ручного поля `API Base` в интерфейсе нет: конечный пользователь не должен настраивать backend-адрес внутри UI. - -## Yandex Maps +```bash +npm run preview +``` -Карты камер и геометрии зон работают через Yandex Maps JS API 2.1. Для staging / production нужно передавать ключ на этапе сборки: +Docker-сборка принимает API URL как build argument: -```env -VITE_YANDEX_MAPS_API_KEY=your-yandex-maps-api-key +```bash +docker build \ + --build-arg VITE_API_BASE_URL=https://api.example.com/api/v1 \ + -t parktrack-admin . ``` -Для совместимости также поддерживается старое имя `VITE_YMAPS_API_KEY`, но новое значение `VITE_YANDEX_MAPS_API_KEY` предпочтительнее. - -## Как приложение работает с backend - -Фронтенд ожидает backend ParkTrack API с ресурсами: - -- `/auth` -- `/users` -- `/partners` -- `/cameras` -- `/zones` -- `/sources` -- `/admin` -- `/health` -- `/version` - -Защищённые ручки вызываются с bearer-токеном текущей сессии. Сессия сохраняется в `localStorage`, переживает обновление страницы и валидируется через API при входе в приложение. - -## Типичный сценарий проверки - -1. Запустить backend из `api-server` -2. Запустить frontend `labeler` -3. Зарегистрироваться или войти -4. Открыть: - - `#/cameras` - - `#/zones` - - `#/sources` - - `#/users` - - `#/partners` - - `#/profile` -5. Проверить создание и редактирование пользователя -6. Проверить создание и редактирование партнёра -7. Проверить добавление пользователя в партнёра -8. Проверить создание / редактирование камеры -9. Проверить snapshot preview и fullscreen -10. Перейти в labeler из камеры или зоны -11. Отредактировать image geometry зоны -12. Отредактировать map geometry зоны -13. Проверить bulk actions на списках камер, зон, пользователей и партнёров -14. Проверить сброс пароля через `#/password-reset` - -## Проверка перед push +Production-образ собирает приложение на Node.js и отдаёт содержимое `dist` через nginx. + +## Backend-контракты + +Фронтенд использует следующие основные группы ParkTrack API: + +- `/auth`; +- `/users`; +- `/partners`; +- `/cameras`; +- `/zones`; +- `/sources`; +- `/occupancy`; +- `/forecasts`; +- `/admin/analytics`; +- `/health`; +- `/version`. + +Основные 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`. + +## Smoke-проверка + +Перед проверкой должны быть запущены PostgreSQL, миграции, backend и frontend. + +1. Войти обычным пользователем и администратором. +2. Обновить страницу и убедиться, что сессия сохранилась. +3. Проверить доступность разделов согласно permissions. +4. Открыть обзор и проверить сводные показатели и зоны внимания. +5. Открыть аналитику: + - изменить период и детализацию; + - выбрать зоны и камеры; + - проверить ручное и автоматическое обновление; + - выбрать срез прогноза; + - проверить tooltips графиков; + - открыть аналитику зоны и камеры; + - проверить таблицу состояния всех зон. +6. Открыть камеру: + - проверить фильтры; + - создать или отредактировать камеру; + - переключить обычный и размеченный snapshot; + - открыть snapshot на весь экран; + - отметить камеру на карте. +7. Перейти в разметку: + - создать зону; + - переместить вершины и линии; + - переместить и масштабировать кадр; + - открыть fullscreen и проверить центрирование; + - изменить геометрию зоны на карте; + - сохранить изменения. +8. Проверить фильтры, редактирование и bulk actions камер, зон, пользователей и партнёров. +9. Проверить добавление пользователя в партнёра и изменение доступов. +10. Проверить реестр источников. +11. Проверить профиль и восстановление пароля. +12. Выполнить production-сборку: ```bash npm run build ``` -Build должен проходить без TypeScript и Vite ошибок. +Сборка должна завершиться без ошибок TypeScript и Vite. + +## Правила разработки + +- сохранять существующие API-контракты и permission checks; +- не добавлять ручную настройку API URL в пользовательский интерфейс; +- крупные изменения разделять на небольшие семантические коммиты; +- после изменений интерфейса проверять desktop и mobile layouts; +- перед push обязательно запускать `npm run build`.