Перейти к основному содержимому

ТЗ на админ-раздел вебсайта для Миши

1. Роль в проекте​

Нужно реализовать ту часть единого сайта ParkTrack, которая отвечает за:

  • авторизацию и работу с пользовательской сессией;
  • общий каркас сайта;
  • личные кабинеты;
  • управление пользователями;
  • управление ролями и доступами;
  • управление камерами;
  • управление парковочными зонами;
  • общий реестр источников данных;
  • системные и служебные настройки, если они нужны для MVP;
  • административные и партнёрские интерфейсы;
  • все CRUD-интерфейсы и рабочие панели, не относящиеся к пользовательской карте.

То есть карта и пользовательский сценарий поиска парковки — это отдельная часть сайта, а здесь нужно сделать всю остальную инфраструктурную и кабинетную часть продукта.

2. Что входит в текущий MVP​

В рамках текущего MVP нужно реализовать:

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

3. Что не входит в текущий MVP​

В текущий MVP не нужно включать:

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

4. Главная цель этой части сайта​

Нужно сделать административно-кабинетную часть продукта так, чтобы:

  • сайт был единым;
  • пользователь логинился один раз;
  • одна и та же сессия работала во всех разделах;
  • карта и кабинеты выглядели как один продукт;
  • администраторы могли управлять всей системой;
  • партнёры могли управлять своими объектами и своими сотрудниками;
  • сотрудники партнёров могли работать только в рамках выданных прав;
  • уже в MVP можно было нормально работать с камерами и зонами без ручных костылей.

5. Общая архитектурная задача​

Эта часть отвечает за “скелет” всего сайта.

Нужно обеспечить:

  • единый домен parktrack.live;
  • единую точку входа;
  • единый механизм авторизации;
  • единый layout;
  • единый header/navigation;
  • единые UI-компоненты;
  • единые стили;
  • единый API client;
  • единый способ обработки ошибок;
  • единый набор базовых типов и DTO.

Эта часть должна стать базой, на которую потом бесшовно встраивается карта.

6. Авторизация и сессии​

6.1 Что нужно реализовать​

Нужно реализовать:

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

6.2 Требования к поведению​

Пользователь должен иметь возможность:

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

6.3 Требования к интеграции​

Нужно сделать так, чтобы карта и кабинеты использовали один и тот же auth/session механизм.

Это значит:

  • нельзя делать отдельный логин только для одной части сайта;
  • нельзя делать независимые сессии для карты и кабинетов;
  • нельзя делать два разных хедера, два разных state auth и две разные схемы проверки пользователя.

7. Пользователи, роли и права​

7.1 Общая модель​

В системе есть:

  • обычные пользователи;
  • администраторы платформы;
  • партнёры (организации);
  • сотрудники партнёров;
  • администраторы партнёров.

У одного пользователя может быть одна или несколько ролей в рамках согласованной модели.

7.2 Что нужно реализовать в UI​

Нужно реализовать интерфейсы для:

  • просмотра пользователей;
  • просмотра карточки пользователя;
  • редактирования базовых данных пользователя;
  • изменения ролей пользователя;
  • управления статусом пользователя;
  • управления принадлежностью к партнёру;
  • настройки прав доступа для сотрудников партнёра.

7.3 Права доступа​

Нужно поддержать в интерфейсах идею, что разные пользователи видят разное.

Примеры:

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

8. Личный кабинет обычного пользователя​

В MVP обычный пользовательский кабинет может быть минимальным.

Нужно реализовать:

  • просмотр своих базовых данных;
  • просмотр текущей роли/ролей;
  • logout;
  • базовую информацию об аккаунте.

Не нужно пока делать тяжёлый пользовательский кабинет с аналитикой, историей поездок и т.д., если для этого ещё нет согласованного API.

9. Кабинет администратора платформы​

Это один из главных разделов этой части сайта.

Администратор платформы должен иметь возможность:

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

10. Кабинет партнёра​

Партнёр — это организация. Создать партнёра может только администратор системы. Также администратор системы может добавлять существующих пользователей в организацию-партнёр и наделять их соответствующими правами, назначать их администраторами партнёра.

Нужно сделать интерфейсы, в которых сотрудники партнёра могут:

  • видеть свои камеры;
  • создавать свои камеры;
  • редактировать свои камеры;
  • удалять свои камеры;
  • видеть свои парковочные зоны;
  • создавать/редактировать/удалять свои зоны;
  • глобально (через navbar) переключаться между разными партнёрами, сотрудниками которых они являются, меняя контекст видимых данных, т. к. каждый пользователь может быть сотрудником нескольких партнёров сразу.

А администраторы партнёра кроме этого могут:

  • видеть своих сотрудников;
  • управлять ролями сотрудников внутри своей организации;
  • управлять правами доступа сотрудников к объектам и данным партнёра;
  • просматривать общий список своих источников данных;
  • редактировать любые камеры, парковочные зоны, источники данных и любые другие ресурсы, созданные и принадлежащие партнёру (сотрудникам партнёра, действующим от имени данного партнёра).

11. Кабинет сотрудника партнёра​

Сотрудник партнёра должен видеть только то, что ему доступно.

Нужно предусмотреть интерфейс, в котором:

  • он видит разрешённые ему камеры;
  • может работать только с разрешёнными ему зонами;
  • может редактировать только те сущности, где у него есть write_scope;
  • не может видеть или менять чужие объекты, если права не выданы;
  • не может попасть в административные разделы платформы.

12. Управление камерами​

Это одна из центральных частей MVP.

12.1 Что нужно реализовать​

Нужно сделать UI для:

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

12.2 Важно​

Камеры — это не просто строчки в таблице. Интерфейс должен быть удобен для реальной работы.

Нужно показать:

  • название;
  • координаты;
  • источник видеопотока;
  • размеры изображения;
  • статус активности (дата и время последнего обновления занятости парковок + фото с размеченными машинами после последнего обновления);
  • принадлежность к партнёру;
  • дату создания;
  • дату обновления.

Если есть связанная зона или зоны, это тоже должно быть видно.

12.3 Требования к UX​

Нужно, чтобы:

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

13. Управление парковочными зонами​

Это второй главный блок MVP.

13.1 Что нужно реализовать​

Нужно сделать UI для:

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

13.2 Особенность зон​

Зона — это не просто таблица, а сущность с геометрией.

В UI должно быть понятно:

  • к какой камере относится зона;
  • какой у неё тип;
  • сколько мест;
  • сколько сейчас свободных мест и какой confidence;
  • платная она или бесплатная;
  • активна ли она;
  • private она или нет;
  • accessible она или нет;
  • какой у неё location_type.

13.3 Работа с геометрией​

Так как API уже использует:

  • geometry
  • image_polygon

интерфейс должен быть спроектирован так, чтобы в дальнейшем можно было удобно редактировать:

  • геометрию зоны на карте;
  • геометрию зоны в изображении камеры.

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

Сейчас Data Sources — это общий реестр источников, а не место настройки конкретных типов источников. Однако раздел управления камерами должен позволять провести их полную настройку.

В MVP нужно реализовать:

  • список источников;
  • фильтрацию по типу;
  • фильтрацию по партнёру;
  • фильтрацию по статусу;
  • переход от записи источника к профильной сущности.

Так как в MVP реальный тип источника только один — камера, интерфейс должен это учитывать, но не должен жёстко ломать будущую расширяемость. В текущей реализации в списке источников должны как минимум быть все камеры. Можно добавить 1-2 других типа данных для тестирования фильтров, без подробных данных для этих типов.

То есть сейчас может быть:

  • entity_type = camera

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

15. Реестр источников и профильные сущности​

Нужно правильно отразить в интерфейсе два уровня:

Уровень 1​

Общий список источников:

  • тип;
  • статус;
  • владелец;
  • активность;
  • последняя активность;
  • ссылка на профильную сущность.

Уровень 2​

Профильная сущность:

  • сейчас это камера;
  • позже это могут быть и другие типы источников.

Нужно не смешивать эти уровни в одном UI так, чтобы потом всё пришлось переписывать.

16. Layout и общая оболочка сайта​

Нужно сделать единый каркас сайта.

В него должны входить:

  • header;
  • навигация;
  • контейнер страниц;
  • система уведомлений (всплывающие диалоги);
  • единые пустые состояния;
  • единые loading states;
  • единые error states.

Важно, чтобы этот каркас был общим и для кабинетной части, и для карты. Поскольку карту пишет Илья Р., необходимо унифицировать с ним все эти компоненты и стиль сайта.

17. Интеграция с картой​

Карта делается отдельно, но эта часть должна её поддерживать архитектурно.

Нужно обеспечить:

  • единую авторизацию;
  • единый layout;
  • единый UI-kit;
  • единый API client;
  • единый механизм обработки ошибок;
  • единый routing сайта.

Переход между картой и кабинетами должен быть бесшовным.

18. Что должно быть готово для стыка с веб-картой​

Нужно подготовить всё, чтобы карта могла нормально встроиться в единый сайт.

Это включает:

  • auth/session;
  • shared layout;
  • shared header/navigation;
  • shared user state;
  • shared UI components;
  • shared toast/error/loading patterns;
  • единый доменный routing.

19. Аналитика​

Так как аналитика сейчас убрана из API, в MVP аналитические разделы реализовывать не нужно.

Имеет смысл:

  • зарезервировать место в навигации;
  • предусмотреть архитектурно, куда потом будет добавлен этот раздел;
  • не делать полноценный UI без API.

20. Системные настройки​

Если для каких-то системных вещей уже есть согласованные API-эндпоинты и они действительно нужны для MVP, можно сделать ограниченные системные настройки.

Если таких контрактов ещё нет (на момент написания ТЗ вроде нет), не нужно искусственно выдумывать большой системный раздел.

В MVP главное:

  • auth;
  • пользователи;
  • роли;
  • партнёры;
  • камеры;
  • зоны;
  • sources registry;
  • единый каркас сайта.

21. Интеграция с API​

Нужно использовать текущее согласованное API.

Минимально нужны следующие разделы:

Auth​

  • POST /auth/register
  • POST /auth/login
  • POST /auth/logout
  • GET /auth/me
  • POST /auth/refresh, если refresh используется в финальной схеме

Users​

  • GET /users
  • GET /users/<user_id>
  • PUT /users/<user_id>
  • всё, что согласовано для ролей, статусов и профиля

Partners​

  • GET /partners
  • GET /partners/<partner_id>
  • POST /partners/new
  • PUT /partners/<partner_id>
  • DELETE /partners/<partner_id>

Cameras​

  • GET /cameras
  • GET /cameras/<camera_id>
  • POST /cameras/new
  • PUT /cameras/<camera_id>
  • DELETE /cameras/<camera_id>

Parking Zones​

  • GET /zones
  • GET /zones/<zone_id>
  • POST /zones/new
  • PUT /zones/<zone_id>
  • DELETE /zones/<zone_id>

Data Sources​

  • GET /sources
  • GET /sources/<source_id>

Если для нужного интерфейса не хватает endpoint’а или данных, это нужно явно зафиксировать и согласовать изменение API, а не замалчивать проблему.

22. Работа с правами доступа в интерфейсе​

Нужно проектировать UI так, чтобы он учитывал права доступа, а не просто надеялся на backend.

То есть:

  • если у пользователя нет права, кнопка не должна просто бесполезно бить в API;
  • интерфейс должен скрывать или disable-ить недоступные действия;
  • но backend-проверки всё равно остаются обязательными;
  • если право внезапно не прошло, ошибка должна быть понятной.

23. Состояние приложения​

Нужно централизованно управлять как минимум следующими состояниями:

  • auth/session state;
  • current user state;
  • permissions state;
  • current partner context state;
  • users list/filter state;
  • partners list/filter state;
  • cameras list/filter state;
  • zones list/filter state;
  • sources list/filter state;
  • forms state;
  • modal/dialog state;
  • notifications state;
  • loading/error/empty states.

Состояния не должны быть хаотично размазаны по страницам и компонентам.

24. UX и обратная связь интерфейса​

На любое значимое действие интерфейс должен давать понятный feedback.

Обязательные состояния:

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

Обязательно:

  • skeleton/spinner там, где нужно;
  • empty-state вместо “пустой дыры”;
  • понятные тексты ошибок;
  • нормальные success-сообщения;
  • отсутствие “тихих” неудач.

Пользователи должны однозначно понимать что происходит, даже если ошибка на стороне API, или внезапно пропал интернет, все эти сценарии нужно предусмотреть. Каждое действие должно фиксироваться, пользователям должно быть ясно, сохранились изменения или нет.

25. Навигация по сайту​

Нужно продумать понятную структуру разделов.

Минимально должны существовать маршруты для:

  • login;
  • registration;
  • profile;
  • users;
  • partners;
  • cameras;
  • zones;
  • sources;
  • admin home / dashboard shell;
  • входа в пользовательскую карту.

Нужно согласовать routing так, чтобы:

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

26. Нефункциональные требования​

Согласованность с другими клиентами​

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

Требования к качеству продукта​

  • сайт должен выглядеть как готовый коммерческий продукт, а не как набор техпанелей;
  • основные сценарии должны быть интуитивно понятны;
  • все формы должны быть удобны и не перегружены;
  • loading / success / error / empty состояния должны быть оформлены единообразно;
  • интерфейс должен быть устойчив к плохим данным, пустым данным и временным ошибкам API;
  • ключевые действия должны сопровождаться понятным feedback.

27. Требования к качеству кода​

Код должен быть:

  • типизированным;
  • модульным;
  • расширяемым;
  • читаемым;
  • с понятным разделением UI, data и domain логики;
  • без размазывания бизнес-логики по компонентам;
  • пригодным для дальнейшего масштабирования.

28. Производительность​

Нужно обеспечить:

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

29. Надёжность​

Нужно корректно обрабатывать:

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

30. Безопасность​

Нужно обеспечить:

  • корректную работу logout;
  • безопасную работу с auth/session;
  • отсутствие утечки чувствительных данных в UI и логах;
  • нормальную обработку истёкшей или инвалидированной сессии;
  • отсутствие возможности случайного доступа к закрытым разделам через прямой URL без повторной проверки прав.

31. Что считается готовым MVP​

MVP можно считать готовым, если:

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

32. Ожидаемый результат​

На выходе должна получиться кабинетно-административная часть ParkTrack, которая:

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