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

ТЗ по созданию партнёрской аналитики в админ-панели для Миши

1. Задача​

Добавить в админ-панель раздел «Аналитика», где партнёр видит аналитику только по своим камерам и парковочным зонам.

Раздел должен заменить для партнёров текущий просмотр метрик через Grafana. Grafana остаётся внутренним инструментом команды, партнёрам доступ к ней не даём.

В админ-панели нужно показать:

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

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

  • Качество прогнозов (occupancy + forecasts на одном графике с селектором времени создания прогноза) + числовые метрики -> обращаться к Руслану

2. Доступ​

В меню админ-панели добавить раздел:

Аналитика

Доступ:

  • admin видит аналитику по всем партнёрам или по выбранному партнёру;
  • partner видит только свои камеры и парковочные зоны;
  • пользователь без прав на аналитику раздел не видит.

Выбор партнёра использовать существующий, который уже есть в админ-панели.

3. Страницы​

Нужно сделать 4 состояния раздела аналитики:

  1. Общий дашборд аналитики
  2. Аналитика парковочной зоны
  3. Аналитика камеры
  4. Просмотр конкретного распознавания

Можно реализовать как отдельные страницы или как один раздел с переходами внутри него. Главное — пользователь должен понимать, где он находится, и иметь кнопку возврата назад.

4. Общий дашборд аналитики

4.1. Фильтры​

Вверху страницы разместить фильтры:

  • период:

    • сегодня;
    • вчера;
    • 7 дней;
    • 30 дней;
    • произвольный период;

  • парковочные зоны (должно быть возможно отмечать 1 или несколько и искать зоны по id или названию их камеры);

  • камеры (должно быть возможно отмечать 1 или несколько и искать камеры по id и названию);

  • детализация графиков:

    • 5 минут;
    • 15 минут;
    • 1 час;
    • 1 день;

  • кнопка обновления данных;

  • переключатель автообновления.

По умолчанию:

  • период — сегодня;
  • автообновление включено;
  • интервал автообновления — 60 секунд.

API:

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

4.2. KPI-карточки​

Под фильтрами показать карточки (все метрики - только по тем сущностям, к которым у пользователя есть доступ):

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

Если значения нет — показывать —, а не 0.

API:

  • /admin/analytics/summary;
  • /admin/analytics/update-frequency;
  • /admin/analytics/confidence.

4.3. Карта зон и камер​

На отдельной странице дашборда показать карту.

На карте отображать:

  • парковочные зоны;
  • камеры;
  • только объекты выбранного партнёра.

Парковочные зоны раскрашивать по текущей занятости:

  • зелёный — занято меньше 60%;
  • жёлтый — занято от 60% до 85%;
  • красный — занято больше 85%;
  • серый — нет данных;
  • оранжевый — данные устарели (пороговое время в минутах положить в .env).

При клике на зону показывать:

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

При клике на камеру показывать:

  • id, название камеры;
  • статус;
  • последнее обновление;
  • кнопку перехода в редактирование камеры
  • кнопку перехода в аналитику камеры.

API:

  • существующий API зон;
  • существующий API камер;
  • /admin/analytics/summary.

4.4. График занятости​

График: линейный.

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

Ось X:

  • время.

Ось Y:

  • занятость в процентах.

Если выбрана конкретная зона — показывать одну линию.

Если выбрано несколько зон — показывать несколько линий, но не больше 10.

У каждой линии графика должна быть легенда с подписью, при нажатии на подпись линия должна отображаться или скрываться с графика, как в Grafana.

Если зон больше 10 — показывать среднее значение по выбранным зонам.

Tooltip должен показывать:

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

API:

  • /admin/analytics/occupancy-history.

4.5. График прогноза занятости​

График: линейный.

На одном графике показать:

  • фактическую занятость;
  • прогноз занятости.

Факт рисовать обычной линией.

Прогноз рисовать пунктирной линией.

Период прогноза задается в фильтрах, как и для других графиков.

У каждой линии графика должна быть легенда с подписью, при нажатии на подпись линия должна отображаться или скрываться с графика, как в Grafana.

API:

  • /admin/analytics/occupancy-history;
  • /admin/analytics/occupancy-forecast.

4.6. График количества наблюдений​

График: столбчатый.

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

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

Ось X:

  • время.

Ось Y:

  • количество наблюдений.

API:

  • /admin/analytics/observations-rate.

4.7. График уверенности модели​

График: линейный.

Показывать средний confidence за выбранный период.

Название в интерфейсе:

Уверенность модели

Не использовать слово «точность» для confidence.

Ось X:

  • время.

Ось Y:

  • confidence в процентах.

API:

  • /admin/analytics/confidence.

4.8. Таблица проблемных зон​

Таблица должна показывать состояние detector-а по зонам.

Колонки:

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

Статусы:

  • online — данные свежие;
  • stale — данные устарели;
  • offline — давно нет данных;
  • no_data — данных ещё не было;
  • low_confidence — низкая уверенность модели.

Клик по строке открывает аналитику выбранной зоны.

API:

  • /admin/analytics/detector-health.

5. Страница парковочной зоны

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

5.1. Верхний блок​

Показать:

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

Кнопки:

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

API:

  • существующий API зоны;
  • /admin/analytics/summary.

5.2. Карта зоны​

Показать зону на карте. Также вывести координаты опорных точек текстом.

Если есть геометрия — показать polygon.

Если геометрии нет — показать сообщение:

У зоны не задана геометрия.

API:

  • существующий API зоны.

5.3. Графики зоны​

На странице зоны показать:

  1. Занято / свободно

    • line chart;
    • две линии: занято и свободно.

  2. Занятость, %

    • line chart;
    • одна линия: процент занятости.

  3. Прогноз занятости

    • факт + прогноз на 24 часа.

  4. Уверенность модели

    • confidence по времени.

  5. Интервалы обновления

    • средний и максимальный интервал обновления.

API:

  • /admin/analytics/occupancy-history;
  • /admin/analytics/occupancy-forecast;
  • /admin/analytics/occupancy-heatmap;
  • /admin/analytics/confidence;
  • /admin/analytics/update-frequency.

6. Страница камеры

На странице камеры показать аналитику только по одной камере.

6.1. Верхний блок​

Показать:

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

Кнопки:

  • назад к аналитике;
  • открыть камеру в разделе камер;
  • открыть разметку камеры.

API:

  • существующий API камеры;
  • существующий API зон;
  • /admin/analytics/detector-health;
  • /admin/analytics/update-frequency;
  • /admin/analytics/confidence.

6.2. Снимки камеры​

Сделать блок с тремя вкладками:

  1. Последний снимок

    • последний кадр, полученный с камеры.

  2. Последнее распознавание

    • raw-кадр, на котором выполнялась последняя детекция.

  3. С разметкой

    • кадр последней детекции с bounding boxes, confidence и разметкой зоны.

Для каждого изображения показать:

  • timestamp;
  • кнопку обновления;
  • кнопку fullscreen.

Если снимка нет — показать понятную причину.

API:

  • /cameras/{cameraId}/snapshot.

6.3. Графики камеры​

На странице камеры показать:

  1. Количество наблюдений

    • bar chart;
    • сколько наблюдений пришло по этой камере.

  2. Уверенность модели

    • line chart;
    • средний confidence по времени.

  3. Интервалы обновлений

    • bar chart;
    • средний и максимальный интервал обновления.

  4. Здоровье зон камеры

    • таблица зон, которые зависят от этой камеры.

API:

  • /admin/analytics/observations-rate;
  • /admin/analytics/confidence;
  • /admin/analytics/update-frequency;
  • /admin/analytics/detector-health.

6.4. Последние распознавания​

Показать таблицу последних 20 распознаваний камеры.

Колонки:

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

Клик открывает страницу конкретного распознавания.

API:

  • /admin/analytics/cameras/{cameraId}/detections.

7. Страница распознавания

Страница нужна для просмотра одного конкретного запуска распознавания и оценки его качества.

7.1. Информация о распознавании​

Показать:

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

API:

  • /admin/analytics/detections/{detectionRunId}.

7.2. Сравнение изображений​

Показать рядом:

  • raw-изображение;
  • annotated-изображение.

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

Для каждого изображения:

  • fullscreen;
  • открыть в новой вкладке.

7.3. Оценка качества распознавания​

Добавить форму оценки.

Поля:

  • оценка:

    • корректно;
    • частично корректно;
    • некорректно;

  • правильное количество занятых мест;

  • правильное количество свободных мест;

  • тип ошибки:

    • лишняя машина;
    • машина не найдена;
    • машина привязана не к той зоне;
    • плохое освещение;
    • плохой ракурс;
    • проблема калибровки;
    • другое;

  • комментарий.

После сохранения показать сообщение:

Оценка сохранена.

Если оценка уже есть — показывать её на странице.

API:

  • GET /admin/analytics/detections/{detectionRunId};
  • POST /admin/analytics/detections/{detectionRunId}/feedback.

7.4. Просмотр фидбеков по распознаванию (только для администраторов)​

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

На странице распознавания показать блок с историей всех оставленных оценок качества для данного распознавания.

Показать таблицу:

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

Если оценок несколько, отображать их в порядке от новых к старым.

При клике на запись открывать подробный просмотр оценки.

В подробном просмотре показать:

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

Если фидбеков нет, показать сообщение:

Для данного распознавания ещё нет оценок качества.

API:

  • GET /admin/analytics/detections/{detectionRunId}/feedback;
  • GET /admin/analytics/detections/{detectionRunId}/feedback/{feedbackId}.

8. Взаимодействие с backend

Frontend не должен сам считать сложные агрегаты.

На frontend можно считать только:

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

Backend должен отдавать уже подготовленные данные для:

  • KPI;
  • истории занятости;
  • прогноза;
  • heatmap;
  • confidence;
  • частоты обновлений;
  • detector health;
  • snapshots;
  • detection runs;
  • feedback.

Frontend должен передавать в analytics API:

  • выбранного партнёра;
  • выбранный период;
  • выбранную зону;
  • выбранную камеру;
  • выбранную детализацию.

9. Состояния интерфейса

Для каждого блока отдельно обработать:

  • загрузку;
  • ошибку;
  • пустые данные.

Если один график не загрузился, вся страница не должна падать.

Примеры сообщений:

  • Нет данных за выбранный период;
  • Прогноз недоступен;
  • Снимок недоступен;
  • Не удалось загрузить график;
  • У зоны нет свежих наблюдений.

10. Критерии готовности

Задача готова, если:

  • в админ-панели появился раздел Аналитика;
  • партнёр видит только свои данные;
  • admin может смотреть данные всех партнёров или выбранного партнёра;
  • на общем дашборде есть фильтры, KPI, карта, графики и таблица проблемных зон;
  • можно открыть аналитику конкретной зоны;
  • можно открыть аналитику конкретной камеры;
  • на странице камеры есть 3 типа снимков;
  • можно открыть конкретное распознавание;
  • можно сравнить raw и annotated изображение;
  • можно отправить оценку качества распознавания;
  • confidence в интерфейсе называется Уверенность модели;
  • при ошибке одного блока остальные блоки продолжают работать;
  • при пустых данных показываются понятные сообщения.