MyBeacon - Техническое задание

О проекте

MyBeacon - это платформа для работы с BLE и WiFi сканерами. Платформа модульная - можно подключать разные продукты независимо друг от друга. Сейчас планируются два продукта:

WiFi Analytics - сбор данных о WiFi устройствах для рекламной аналитики
BLE Tracking - отслеживание BLE меток для контроля персонала и активов

В будущем могут появиться другие продукты (например, мониторинг температуры, счетчики посетителей и т.д.). Вся админка и демон железки должны легко расширяться под новые продукты.

Кто пользуется системой

1. Супер-админ

Полный доступ ко всему
Управляет клиентами (организациями)
Управляет железками (может отвязать от клиента, поменять настройки)
Видит все данные

2. Клиент (организация)

Это компания, которая покупает услугу
У клиента может быть несколько пользователей (сотрудников)
Видит только свои железки и свои данные
Доступ к продуктам включает админ (WiFi, BLE или оба)

3. Пользователь клиента

Сотрудник компании-клиента
Имеет права доступа (может быть read-only или полный доступ)
Права настраиваются для каждого объекта (например: может смотреть данные, но не менять настройки)
Все действия логируются (кто, когда, что делал)

Многопользовательский доступ в организации

У одного клиента может работать много людей:

Директор (полный доступ)
Менеджеры (read-only по аналитике)
Техники (доступ к настройкам железок)
Охранники (только просмотр BLE меток на картах)

Требования:

Владелец организации может добавлять пользователей
Каждому пользователю назначаются роли/права
Права на уровне объектов (может смотреть эту локацию, но не ту)
Логи всех действий: кто куда ходил, что смотрел, что нажимал
Возможность ограничить только чтением (read-only mode)

Роли пользователей в организации:

Владелец (Owner) - полный доступ, управление пользователями
Администратор (Admin) - полный доступ к функционалу, но не может управлять пользователями
Менеджер (Manager) - доступ к аналитике и отчетам (read-only)
Оператор (Operator) - доступ к конкретным локациям/объектам
Наблюдатель (Viewer) - только просмотр, ничего не может менять

Регистрация и управление клиентами

Вариант 1: Самостоятельная регистрация

Клиент заходит на сайт, жмет "Зарегистрироваться"
Заполняет форму: email, пароль, название компании, телефон
Ему приходит письмо с подтверждением email
Кликает по ссылке - email подтвержден
Логинится в личный кабинет - видит сообщение "Ожидается активация администратором"
По умолчанию доступа к продуктам НЕТ (wifi_enabled=false, ble_enabled=false)
Админ видит нового клиента в списке "Ожидают активации"
Админ включает нужные продукты (WiFi, BLE или оба) - клиенту приходит уведомление
Клиент заходит - видит активированные продукты

Вариант 2: Создание админом

Админ создает клиента: email, название, телефон
Выбирает какие продукты доступны (WiFi, BLE)
Система генерирует пароль, отправляет на email клиента
Клиент получает письмо с логином и паролем
Логинится - сразу видит активные продукты

Железки (устройства)

Простой ID для общения с клиентами

Железки имеют MAC адрес (например 38:54:39:4b:1b:ac), но клиентам так общаться неудобно.

Решение: Каждой железке присваивается простой ID начиная с 1:

Приемник #1
Приемник #2
Приемник #3
...

Когда клиент звонит в поддержку: "У нас проблема с приемником номер 5" - админ по фильтру легко находит его в базе.

Как работает:

ID назначается автоматически при регистрации железки
ID уникальный в рамках всей системы (не сбрасывается)
В админке можно искать как по MAC, так и по простому ID
Клиенту показывается "Приемник #5", но можно раскрыть и увидеть MAC

Управление железками

Админ может:

Видеть все железки (все клиенты)
Фильтровать: по клиенту, по статусу (онлайн/офлайн), по MAC, по простому ID
Привязывать/отвязывать железку к клиенту
Менять настройки любой железки
Открыть SSH терминал (через туннель)
Открыть dashboard железки (через туннель)

Клиент может:

Видеть только свои железки
Менять настройки (если есть права)
Видеть статус (онлайн/офлайн)
Видеть последнюю активность
Назначать железку на конкретную локацию (для BLE)

Продукт 1: WiFi Analytics

Для кого: рекламные агентства, торговые центры, аэропорты - всем кто хочет знать сколько людей проходит мимо.

Что делает:

Собирает данные о WiFi устройствах (MAC адреса)
Фильтрует фейковые (рандомизированные) MAC адреса
Показывает статистику: уникальные посетители, повторные визиты, время нахождения
Экспортирует данные для рекламщиков

Личный кабинет клиента:

Dashboard
- Общая статистика за период (сегодня/неделя/месяц)
- Уникальные MAC адреса
- Фейковые vs настоящие
- График по дням/часам
- Топ производителей устройств (Apple, Samsung и т.д.)
Мои железки
- Список своих сканеров
- Статус (онлайн/офлайн)
- Сколько событий собрали за период
- Простой ID + MAC адрес
Экспорт данных
- Выбрать период
- Выбрать формат (CSV, JSON)
- Опции: исключить фейковые MAC
- Скачать файл
- История экспортов (когда, кто скачал)

Продукт 2: BLE Tracking

Для кого: магазины, склады, больницы, офисы - где нужно отслеживать людей или объекты.

Что делает:

Отслеживает BLE метки (iBeacon)
Показывает на карте где находятся метки
Привязывает метки к людям/объектам ("Марья Ивановна", "Велосипед №5")
История перемещений

Личный кабинет клиента:

1. Локации (объекты)

Клиент может иметь несколько объектов:

Магазин на Ленина
Магазин на Пушкина
Склад №3

Для каждой локации:

Название
Адрес
Свои приемники
Свои планы помещений

2. Планы помещений

Загрузка плана:

Клиент загружает картинку (JPG/PNG) - растровый план
Система автоматически конвертирует в вектор (SVG)
Клиент в редакторе может:
- Подправить контуры стен
- Выделить зоны/комнаты
- Добавить подписи
- Указать масштаб (сколько метров в одном пикселе)

Цветовая схема (светлая тема):

Фон: светло-зеленый #E5F2E5
Стены/контуры: серо-бежевый #D4CFC4
Комнаты: пастельные тона
- Бежевый #F5EFE0
- Персиковый #FFE8D6
- Голубой #E0F7FA
Выделенные зоны: оранжевый контур #FF9800
Подписи: черный текст #000000

(Для темной темы - потом придумаем)

3. Размещение приемников на плане

Как работает:

Клиент открывает план помещения
Видит список своих приемников (по простым ID: Приемник #1, #2, #3...)
Перетаскивает иконку приемника на нужное место на карте
Приемник показывается как прямоугольная иконка с логотипом (logo.svg)
Можно повернуть иконку (если направление важно)
Сохраняет расположение

Логотип приемника:

Использовать logo.svg (beacon с концентрическими кругами)
Размер: ~32x32px на карте
Цвет: голубой #1CB5D5
При наведении - показывает: "Приемник #5 (онлайн)"

4. Зоны на плане

Зачем нужны зоны: С таким железом точная навигация не получится - только определение зоны нахождения. Этого достаточно в большинстве случаев: понять что человек в столовой, на складе или в туалете.

Как рисовать зоны:

Клиент открывает редактор плана
Выбирает инструмент "Нарисовать зону"
Рисует полигон (многоугольник) поверх плана
Зона показывается полупрозрачной (например, синий с прозрачностью 30%)
Зоне автоматически присваивается номер: Зона #1, Зона #2, Зона #3...
Клиент может дать зоне название: "Столовая", "Зал", "Склад", "Туалет", "Задний вход"
Сохраняет

Свойства зоны:

Номер (автоматический, уникальный на плане)
Название (задает клиент)
Цвет (можно выбрать из палитры)
Полигон (координаты вершин)

Примеры зон:

Зона #1: "Столовая" (голубой)
Зона #2: "Торговый зал" (зеленый)
Зона #3: "Склад" (желтый)
Зона #4: "Туалет" (розовый)
Зона #5: "Задний вход" (оранжевый)

Определение принадлежности метки к зоне:

Бэк по координатам метки определяет в какой зоне она находится (point-in-polygon)
Если метка видна несколькими приемниками - берется среднее положение
Если не попала ни в одну зону - показывается "Вне зон"

Аналитика по зонам:

Сколько времени метка провела в каждой зоне
Сколько меток сейчас в каждой зоне
Тепловая карта по зонам (какие зоны самые посещаемые)
Маршруты: Зона #1 → Зона #3 → Зона #2

5. Управление метками (Beacons)

Добавление метки:

UUID, Major, Minor (технические идентификаторы iBeacon)
Привязать к объекту:
- Тип: Человек / Актив / Транспорт
- Имя: "Марья Ивановна", "Велосипед №5", "Погрузчик ПГ-12"
- Фото (опционально)
- Описание

Список меток:

Поиск по имени
Фильтр по типу
Статус: активна / не видна >10 минут
Последнее местоположение

5. Real-time карта

Что видит клиент:

План помещения
Иконки приемников (с логотипами) на своих местах
Метки на карте:
- Показываются иконкой (точка или аватарка)
- Рядом с меткой: "Марья Ивановна, -65dB"
- RSSI показывает силу сигнала (близость к приемнику)
- Если метка видна несколькими приемниками - показывается примерная позиция

Обновление:

Каждые 5-10 секунд карта обновляется
Можно включить автообновление (polling) или WebSocket

История:

Можно включить "воспроизведение" - как двигалась метка за последний час/день
Тепловая карта (где метка проводила больше времени)

Туннели (удаленный доступ)

SSH туннель

Зачем: админ может подключиться к терминалу железки удаленно (даже если она за NAT).

Как работает:

Админ в списке железок жмет кнопку [Открыть SSH]
Открывается новая страница с сообщением "Подключение к устройству..."
Система:
- Включает SSH туннель на железке
- Ждет пока железка подключится (до 60 секунд)
- Запускает ttyd (веб-терминал)
В браузере открывается терминал - админ работает как в SSH
При закрытии вкладки - терминал убивается (через 60 секунд grace period)
Туннель остается активным (можно переоткрыть терминал)

Dashboard туннель

Зачем: админ или клиент может открыть веб-интерфейс железки.

Как работает:

Жмет кнопку [Открыть Dashboard]
Ожидание подключения...
Открывается iframe с dashboard железки
Можно смотреть статус, логи, менять настройки прямо на железке

Права доступа и логирование

Система прав

На уровне организации:

Владелец может добавлять/удалять пользователей
Владелец назначает роли
Администратор не может управлять пользователями, но может все остальное

На уровне объектов (для BLE):

Пользователь может иметь доступ только к определенным локациям
Пример: охранник видит только "Магазин на Ленина", но не видит "Склад №3"
Права: read-only (только смотреть) или read-write (менять настройки)

Матрица прав:

Действие                 | Owner | Admin | Manager | Operator | Viewer
-------------------------|-------|-------|---------|----------|-------
Просмотр аналитики       |   ✓   |   ✓   |    ✓    |    ✓     |   ✓
Экспорт данных           |   ✓   |   ✓   |    ✓    |    ✗     |   ✗
Настройки железок        |   ✓   |   ✓   |    ✗    |    ✓     |   ✗
Управление метками       |   ✓   |   ✓   |    ✗    |    ✓     |   ✗
Управление пользователями|   ✓   |   ✗   |    ✗    |    ✗     |   ✗
Изменение планов         |   ✓   |   ✓   |    ✗    |    ✓     |   ✗

Детальное логирование

Что логируется:

Вход/выход пользователя (timestamp, IP адрес)
Переходы по страницам ("открыл страницу локации X")
Просмотр данных ("посмотрел аналитику за период Y")
Изменения ("изменил настройки железки #5", "привязал метку к человеку")
Экспорты ("скачал CSV с данными за месяц")
Действия с пользователями ("добавил пользователя", "изменил права")

Формат лога:

2024-01-15 10:30:45 | user@example.com | Просмотр | Локация "Магазин на Ленина" | IP: 192.168.1.100
2024-01-15 10:31:12 | user@example.com | Изменение | Метка #42: "Велосипед №5" → "Велосипед №6" | IP: 192.168.1.100
2024-01-15 10:35:00 | user@example.com | Экспорт | WiFi Analytics, 2024-01-01 - 2024-01-15, CSV | IP: 192.168.1.100

Где смотреть логи:

Владелец и Админ видят все логи своей организации
Фильтры: по пользователю, по действию, по дате
Экспорт логов в CSV

Модульность системы

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

Принципы:

Каждый продукт - независимый модуль
Админка - общая (управление клиентами, железками, пользователями)
Демон железки универсальный (можно включать/выключать модули в конфиге)
API универсальное (endpoints группируются по продуктам)

Пример добавления нового продукта "Temperature Monitoring":

В клиентах добавляется флаг temperature_enabled
В API добавляется группа /api/v1/client/temperature/*
В демоне железки добавляется модуль сбора температуры
Во frontend добавляется раздел "Температура"
Админ включает продукт клиенту - тот видит новый раздел

Переиспользование в других проектах:

Можно взять только админку и использовать для управления любыми IoT устройствами
Можно взять демон железки и адаптировать под другое железо (Raspberry Pi, ESP32)
API спроектировано универсально

Технический стек

Backend

Python + FastAPI
PostgreSQL - клиенты, пользователи, железки, права
ClickHouse - события (BLE/WiFi), аналитика
Redis - очереди, кеш

Frontend

Vue 3 + Vite
Vue Router + Pinia
TailwindCSS (или Vuetify)

Деплой

БЕЗ Docker (обычный Linux + systemd)
Скрипт установки всех зависимостей
PostgreSQL, ClickHouse, Redis, Nginx
Автоматические миграции БД

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

Этап 1: Фундамент (2-3 недели)

Auth (многопользовательский, роли)
Админка: клиенты + пользователи в организациях
Device API (регистрация, конфиг)
Управление железками (с простыми ID)
Background worker: буфер → ClickHouse

Этап 2: WiFi Analytics (1-2 недели)

WiFi события в ClickHouse
Аналитика (уникальные MAC, фейковые)
Клиентский кабинет WiFi
Экспорт данных

Этап 3: Tunnels (1 неделя)

SSH + Dashboard туннели
ttyd для веб-терминала
UI: кнопки + ожидание подключения

Этап 4: BLE Tracking (2-3 недели)

Локации, планы, метки
Загрузка и редактирование планов
Размещение приемников на карте
Real-time отображение меток

Этап 5: Права и логи (1 неделя)

Детальная система прав
Логирование всех действий
UI для просмотра логов

Открытые вопросы

Домен: какой? mybeacon.ru?
Email: SMTP настройки? Свой сервер или SendGrid?
File storage: где хранить планы и фото? /uploads на сервере?
Real-time BLE: polling каждые 5 сек или WebSocket?
Экспорт WiFi: какой формат CSV нужен? Какие поля?
Хранение событий: сколько хранить в ClickHouse? Год?
Ресурсы сервера: сколько RAM/CPU? Сколько железок планируется?

BACKEND.md 24 KB History Raw

MyBeacon - Техническое задание

О проекте

Кто пользуется системой

1. Супер-админ

2. Клиент (организация)

3. Пользователь клиента

Многопользовательский доступ в организации

Регистрация и управление клиентами

Вариант 1: Самостоятельная регистрация

Вариант 2: Создание админом

Железки (устройства)

Простой ID для общения с клиентами

Управление железками

Продукт 1: WiFi Analytics

Продукт 2: BLE Tracking

1. Локации (объекты)

2. Планы помещений

3. Размещение приемников на плане

4. Зоны на плане

5. Управление метками (Beacons)

5. Real-time карта

Туннели (удаленный доступ)

SSH туннель

Dashboard туннель

Права доступа и логирование

Система прав

Детальное логирование

Модульность системы

Технический стек

Backend

Frontend

Деплой

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

Этап 1: Фундамент (2-3 недели)

Этап 2: WiFi Analytics (1-2 недели)

Этап 3: Tunnels (1 неделя)

Этап 4: BLE Tracking (2-3 недели)

Этап 5: Права и логи (1 неделя)

Открытые вопросы

BACKEND.md 24 KB

History Raw