|
|
@@ -0,0 +1,437 @@
|
|
|
+# MyBeacon - Техническое задание
|
|
|
+
|
|
|
+## О проекте
|
|
|
+
|
|
|
+MyBeacon - это платформа для работы с BLE и WiFi сканерами. Платформа **модульная** - можно подключать разные продукты независимо друг от друга. Сейчас планируются два продукта:
|
|
|
+
|
|
|
+1. **WiFi Analytics** - сбор данных о WiFi устройствах для рекламной аналитики
|
|
|
+2. **BLE Tracking** - отслеживание BLE меток для контроля персонала и активов
|
|
|
+
|
|
|
+В будущем могут появиться другие продукты (например, мониторинг температуры, счетчики посетителей и т.д.). Вся админка и демон железки должны легко расширяться под новые продукты.
|
|
|
+
|
|
|
+## Кто пользуется системой
|
|
|
+
|
|
|
+### 1. Супер-админ
|
|
|
+- Полный доступ ко всему
|
|
|
+- Управляет клиентами (организациями)
|
|
|
+- Управляет железками (может отвязать от клиента, поменять настройки)
|
|
|
+- Видит все данные
|
|
|
+
|
|
|
+### 2. Клиент (организация)
|
|
|
+- Это компания, которая покупает услугу
|
|
|
+- У клиента может быть **несколько пользователей** (сотрудников)
|
|
|
+- Видит только свои железки и свои данные
|
|
|
+- Доступ к продуктам включает админ (WiFi, BLE или оба)
|
|
|
+
|
|
|
+### 3. Пользователь клиента
|
|
|
+- Сотрудник компании-клиента
|
|
|
+- Имеет **права доступа** (может быть read-only или полный доступ)
|
|
|
+- Права настраиваются **для каждого объекта** (например: может смотреть данные, но не менять настройки)
|
|
|
+- Все действия **логируются** (кто, когда, что делал)
|
|
|
+
|
|
|
+## Многопользовательский доступ в организации
|
|
|
+
|
|
|
+У одного клиента может работать много людей:
|
|
|
+- Директор (полный доступ)
|
|
|
+- Менеджеры (read-only по аналитике)
|
|
|
+- Техники (доступ к настройкам железок)
|
|
|
+- Охранники (только просмотр BLE меток на картах)
|
|
|
+
|
|
|
+**Требования:**
|
|
|
+- Владелец организации может добавлять пользователей
|
|
|
+- Каждому пользователю назначаются роли/права
|
|
|
+- Права на уровне объектов (может смотреть эту локацию, но не ту)
|
|
|
+- Логи всех действий: кто куда ходил, что смотрел, что нажимал
|
|
|
+- Возможность ограничить только чтением (read-only mode)
|
|
|
+
|
|
|
+**Роли пользователей в организации:**
|
|
|
+- **Владелец** (Owner) - полный доступ, управление пользователями
|
|
|
+- **Администратор** (Admin) - полный доступ к функционалу, но не может управлять пользователями
|
|
|
+- **Менеджер** (Manager) - доступ к аналитике и отчетам (read-only)
|
|
|
+- **Оператор** (Operator) - доступ к конкретным локациям/объектам
|
|
|
+- **Наблюдатель** (Viewer) - только просмотр, ничего не может менять
|
|
|
+
|
|
|
+## Регистрация и управление клиентами
|
|
|
+
|
|
|
+### Вариант 1: Самостоятельная регистрация
|
|
|
+
|
|
|
+1. Клиент заходит на сайт, жмет "Зарегистрироваться"
|
|
|
+2. Заполняет форму: email, пароль, название компании, телефон
|
|
|
+3. Ему приходит письмо с подтверждением email
|
|
|
+4. Кликает по ссылке - email подтвержден
|
|
|
+5. Логинится в личный кабинет - видит сообщение "Ожидается активация администратором"
|
|
|
+6. **По умолчанию доступа к продуктам НЕТ** (wifi_enabled=false, ble_enabled=false)
|
|
|
+7. Админ видит нового клиента в списке "Ожидают активации"
|
|
|
+8. Админ включает нужные продукты (WiFi, BLE или оба) - клиенту приходит уведомление
|
|
|
+9. Клиент заходит - видит активированные продукты
|
|
|
+
|
|
|
+### Вариант 2: Создание админом
|
|
|
+
|
|
|
+1. Админ создает клиента: email, название, телефон
|
|
|
+2. Выбирает какие продукты доступны (WiFi, BLE)
|
|
|
+3. Система генерирует пароль, отправляет на email клиента
|
|
|
+4. Клиент получает письмо с логином и паролем
|
|
|
+5. Логинится - сразу видит активные продукты
|
|
|
+
|
|
|
+## Железки (устройства)
|
|
|
+
|
|
|
+### Простой 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 адреса
|
|
|
+- Показывает статистику: уникальные посетители, повторные визиты, время нахождения
|
|
|
+- Экспортирует данные для рекламщиков
|
|
|
+
|
|
|
+**Личный кабинет клиента:**
|
|
|
+
|
|
|
+1. **Dashboard**
|
|
|
+ - Общая статистика за период (сегодня/неделя/месяц)
|
|
|
+ - Уникальные MAC адреса
|
|
|
+ - Фейковые vs настоящие
|
|
|
+ - График по дням/часам
|
|
|
+ - Топ производителей устройств (Apple, Samsung и т.д.)
|
|
|
+
|
|
|
+2. **Мои железки**
|
|
|
+ - Список своих сканеров
|
|
|
+ - Статус (онлайн/офлайн)
|
|
|
+ - Сколько событий собрали за период
|
|
|
+ - Простой ID + MAC адрес
|
|
|
+
|
|
|
+3. **Экспорт данных**
|
|
|
+ - Выбрать период
|
|
|
+ - Выбрать формат (CSV, JSON)
|
|
|
+ - Опции: исключить фейковые MAC
|
|
|
+ - Скачать файл
|
|
|
+ - История экспортов (когда, кто скачал)
|
|
|
+
|
|
|
+## Продукт 2: BLE Tracking
|
|
|
+
|
|
|
+**Для кого:** магазины, склады, больницы, офисы - где нужно отслеживать людей или объекты.
|
|
|
+
|
|
|
+**Что делает:**
|
|
|
+- Отслеживает BLE метки (iBeacon)
|
|
|
+- Показывает на карте где находятся метки
|
|
|
+- Привязывает метки к людям/объектам ("Марья Ивановна", "Велосипед №5")
|
|
|
+- История перемещений
|
|
|
+
|
|
|
+**Личный кабинет клиента:**
|
|
|
+
|
|
|
+### 1. Локации (объекты)
|
|
|
+
|
|
|
+Клиент может иметь несколько объектов:
|
|
|
+- Магазин на Ленина
|
|
|
+- Магазин на Пушкина
|
|
|
+- Склад №3
|
|
|
+
|
|
|
+Для каждой локации:
|
|
|
+- Название
|
|
|
+- Адрес
|
|
|
+- Свои приемники
|
|
|
+- Свои планы помещений
|
|
|
+
|
|
|
+### 2. Планы помещений
|
|
|
+
|
|
|
+**Загрузка плана:**
|
|
|
+1. Клиент загружает картинку (JPG/PNG) - растровый план
|
|
|
+2. Система автоматически конвертирует в вектор (SVG)
|
|
|
+3. Клиент в редакторе может:
|
|
|
+ - Подправить контуры стен
|
|
|
+ - Выделить зоны/комнаты
|
|
|
+ - Добавить подписи
|
|
|
+ - Указать масштаб (сколько метров в одном пикселе)
|
|
|
+
|
|
|
+**Цветовая схема (светлая тема):**
|
|
|
+- Фон: светло-зеленый `#E5F2E5`
|
|
|
+- Стены/контуры: серо-бежевый `#D4CFC4`
|
|
|
+- Комнаты: пастельные тона
|
|
|
+ - Бежевый `#F5EFE0`
|
|
|
+ - Персиковый `#FFE8D6`
|
|
|
+ - Голубой `#E0F7FA`
|
|
|
+- Выделенные зоны: оранжевый контур `#FF9800`
|
|
|
+- Подписи: черный текст `#000000`
|
|
|
+
|
|
|
+*(Для темной темы - потом придумаем)*
|
|
|
+
|
|
|
+### 3. Размещение приемников на плане
|
|
|
+
|
|
|
+**Как работает:**
|
|
|
+1. Клиент открывает план помещения
|
|
|
+2. Видит список своих приемников (по простым ID: Приемник #1, #2, #3...)
|
|
|
+3. Перетаскивает иконку приемника на нужное место на карте
|
|
|
+4. Приемник показывается как **прямоугольная иконка с логотипом** (logo.svg)
|
|
|
+5. Можно повернуть иконку (если направление важно)
|
|
|
+6. Сохраняет расположение
|
|
|
+
|
|
|
+**Логотип приемника:**
|
|
|
+- Использовать `logo.svg` (beacon с концентрическими кругами)
|
|
|
+- Размер: ~32x32px на карте
|
|
|
+- Цвет: голубой `#1CB5D5`
|
|
|
+- При наведении - показывает: "Приемник #5 (онлайн)"
|
|
|
+
|
|
|
+### 4. Зоны на плане
|
|
|
+
|
|
|
+**Зачем нужны зоны:**
|
|
|
+С таким железом точная навигация не получится - только определение зоны нахождения. Этого достаточно в большинстве случаев: понять что человек в столовой, на складе или в туалете.
|
|
|
+
|
|
|
+**Как рисовать зоны:**
|
|
|
+1. Клиент открывает редактор плана
|
|
|
+2. Выбирает инструмент "Нарисовать зону"
|
|
|
+3. Рисует полигон (многоугольник) поверх плана
|
|
|
+4. Зона показывается **полупрозрачной** (например, синий с прозрачностью 30%)
|
|
|
+5. Зоне автоматически присваивается номер: Зона #1, Зона #2, Зона #3...
|
|
|
+6. Клиент может дать зоне название: "Столовая", "Зал", "Склад", "Туалет", "Задний вход"
|
|
|
+7. Сохраняет
|
|
|
+
|
|
|
+**Свойства зоны:**
|
|
|
+- Номер (автоматический, уникальный на плане)
|
|
|
+- Название (задает клиент)
|
|
|
+- Цвет (можно выбрать из палитры)
|
|
|
+- Полигон (координаты вершин)
|
|
|
+
|
|
|
+**Примеры зон:**
|
|
|
+- Зона #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).
|
|
|
+
|
|
|
+**Как работает:**
|
|
|
+1. Админ в списке железок жмет кнопку **[Открыть SSH]**
|
|
|
+2. Открывается новая страница с сообщением "Подключение к устройству..."
|
|
|
+3. Система:
|
|
|
+ - Включает SSH туннель на железке
|
|
|
+ - Ждет пока железка подключится (до 60 секунд)
|
|
|
+ - Запускает ttyd (веб-терминал)
|
|
|
+4. В браузере открывается терминал - админ работает как в SSH
|
|
|
+5. При закрытии вкладки - терминал убивается (через 60 секунд grace period)
|
|
|
+6. Туннель остается активным (можно переоткрыть терминал)
|
|
|
+
|
|
|
+### Dashboard туннель
|
|
|
+
|
|
|
+**Зачем:** админ или клиент может открыть веб-интерфейс железки.
|
|
|
+
|
|
|
+**Как работает:**
|
|
|
+1. Жмет кнопку **[Открыть Dashboard]**
|
|
|
+2. Ожидание подключения...
|
|
|
+3. Открывается iframe с dashboard железки
|
|
|
+4. Можно смотреть статус, логи, менять настройки прямо на железке
|
|
|
+
|
|
|
+## Права доступа и логирование
|
|
|
+
|
|
|
+### Система прав
|
|
|
+
|
|
|
+**На уровне организации:**
|
|
|
+- Владелец может добавлять/удалять пользователей
|
|
|
+- Владелец назначает роли
|
|
|
+- Администратор не может управлять пользователями, но может все остальное
|
|
|
+
|
|
|
+**На уровне объектов (для 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":**
|
|
|
+1. В клиентах добавляется флаг `temperature_enabled`
|
|
|
+2. В API добавляется группа `/api/v1/client/temperature/*`
|
|
|
+3. В демоне железки добавляется модуль сбора температуры
|
|
|
+4. Во frontend добавляется раздел "Температура"
|
|
|
+5. Админ включает продукт клиенту - тот видит новый раздел
|
|
|
+
|
|
|
+**Переиспользование в других проектах:**
|
|
|
+- Можно взять только админку и использовать для управления любыми 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 для просмотра логов
|
|
|
+
|
|
|
+## Открытые вопросы
|
|
|
+
|
|
|
+1. **Домен**: какой? mybeacon.ru?
|
|
|
+2. **Email**: SMTP настройки? Свой сервер или SendGrid?
|
|
|
+3. **File storage**: где хранить планы и фото? `/uploads` на сервере?
|
|
|
+4. **Real-time BLE**: polling каждые 5 сек или WebSocket?
|
|
|
+5. **Экспорт WiFi**: какой формат CSV нужен? Какие поля?
|
|
|
+6. **Хранение событий**: сколько хранить в ClickHouse? Год?
|
|
|
+7. **Ресурсы сервера**: сколько RAM/CPU? Сколько железок планируется?
|
