MyBeacon Backend

Модульная платформа BLE/WiFi мониторинга с multi-tenant архитектурой.

Стек технологий

Backend: Python 3.11+, FastAPI, SQLAlchemy (async)
Database: PostgreSQL 16 (metadata), Redis (cache)
Authentication: JWT (python-jose), bcrypt
Development: Poetry, uvicorn --reload

Архитектура

Multi-tenant

Полная изоляция данных между организациями:

Каждый пользователь принадлежит организации
Устройства назначаются организациям
API автоматически фильтрует данные по organization_id

Роли (RBAC)

superadmin - полный доступ ко всем организациям и устройствам
owner - управление своей организацией (создание/удаление пользователей, устройств)
admin - управление пользователями в организации
manager - просмотр и частичное управление
operator - только просмотр устройств
viewer - минимальный доступ (только чтение)

Автоматическая регистрация устройств

Superadmin включает авторегистрацию через API
Новые устройства регистрируются автоматически при первом подключении
Авторегистрация автоматически отключается через 1 час после последнего зарегистрированного устройства
Незарегистрированные устройства (organization_id = NULL) назначаются superadmin'ом

API Endpoints

Authentication (`/api/v1/auth/*`)

POST /auth/register      - Регистрация нового пользователя
POST /auth/login         - Вход (получение JWT токенов)
POST /auth/refresh       - Обновление access token
GET  /auth/me            - Информация о текущем пользователе

Superadmin API (`/api/v1/superadmin/*`)

Organizations:

GET    /superadmin/organizations       - Список всех организаций
POST   /superadmin/organizations       - Создание организации
GET    /superadmin/organizations/:id   - Просмотр организации
PATCH  /superadmin/organizations/:id   - Обновление (статус, модули)
DELETE /superadmin/organizations/:id   - Удаление организации

Users:

GET    /superadmin/users                - Список всех пользователей
POST   /superadmin/users                - Создание пользователя
GET    /superadmin/users/:id            - Просмотр пользователя
PATCH  /superadmin/users/:id            - Обновление пользователя
DELETE /superadmin/users/:id            - Удаление пользователя
POST   /superadmin/users/:id/change-password - Смена пароля

Devices:

GET    /superadmin/devices              - Список всех устройств
POST   /superadmin/devices              - Регистрация устройства
GET    /superadmin/devices/:id          - Просмотр устройства
PATCH  /superadmin/devices/:id          - Обновление (назначение организации)
DELETE /superadmin/devices/:id          - Удаление устройства

Settings:

GET  /superadmin/settings/auto-registration  - Статус авторегистрации
POST /superadmin/settings/auto-registration  - Включить/выключить авторегистрацию

Client API (`/api/v1/client/*`)

Organization:

GET /client/organization/me - Информация о своей организации

Users (owner/admin only):

GET    /client/users                    - Пользователи в организации
POST   /client/users                    - Создать пользователя
GET    /client/users/:id                - Просмотр пользователя
PATCH  /client/users/:id                - Обновление пользователя
DELETE /client/users/:id                - Удаление пользователя
POST   /client/users/:id/change-password - Смена пароля

Devices:

GET /client/devices     - Устройства организации
GET /client/devices/:id - Просмотр устройства

Device API (для железок)

Registration:

POST /api/v1/registration
Body: {"device_id": "MAC_ADDRESS", "ssh_public_key": "..."}
Response: {"device_token": "...", "device_password": "..."}

Configuration:

GET /api/v1/config?device_id=MAC_ADDRESS
Headers: Authorization: Bearer DEVICE_TOKEN
Response: {config object with BLE/WiFi settings}

Events:

POST /api/v1/ble   - BLE scan events batch
POST /api/v1/wifi  - WiFi probe events batch
Headers: Authorization: Bearer DEVICE_TOKEN
Headers: Content-Encoding: gzip (optional)
Body: {"count": N, "events": [...]}

Database Schema

Основные таблицы

users - Пользователи (superadmin + org users)

id, email, hashed_password, full_name, phone,
role, status, organization_id, email_verified,
last_login_at, created_at

organizations - Организации (клиенты)

id, name, contact_email, contact_phone,
wifi_enabled, ble_enabled, status, notes, created_at

devices - Устройства (receivers)

id, simple_id, mac_address, organization_id,
device_token, device_password, status, last_seen_at,
config (JSONB), created_at

settings - Системные настройки

id, key, value (JSONB), updated_at

refresh_tokens - JWT refresh tokens

id, user_id, token, expires_at, created_at

Simple ID

Устройства получают автоинкрементный simple_id для отображения:

Устройство #1, #2, #3... вместо MAC-адресов
PostgreSQL sequence гарантирует уникальность
Используется для customer support

Установка и запуск

Требования

Python 3.11+
PostgreSQL 16+
Redis 7+
Poetry

Установка

cd backend

# Установка зависимостей
poetry install

# Копирование .env
cp .env.example .env
# Редактировать .env (DATABASE_URL, SECRET_KEY)

# Миграции
poetry run alembic upgrade head

# Создание superadmin (вручную или через скрипт)
poetry run python -c "
from app.core.security import hash_password
print(hash_password('YOUR_PASSWORD'))
"
# Вставить в БД:
# INSERT INTO users (email, hashed_password, role, status, email_verified)
# VALUES ('admin@example.com', 'HASHED_PASSWORD', 'superadmin', 'active', true);

Запуск

Development:

poetry run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Production:

poetry run uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

Swagger UI: http://localhost:8000/docs

Тестирование

Включение авторегистрации

curl -X POST http://localhost:8000/api/v1/superadmin/settings/auto-registration \
  -H "Authorization: Bearer SUPERADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Проверка регистрации устройства

# На устройстве (автоматически при старте):
# POST /api/v1/registration с MAC-адресом

# Проверка в базе:
psql -U mybeacon -d mybeacon -c "SELECT simple_id, mac_address, status FROM devices;"

Назначение устройства организации

curl -X PATCH http://localhost:8000/api/v1/superadmin/devices/DEVICE_ID \
  -H "Authorization: Bearer SUPERADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"organization_id": ORG_ID}'

Конфигурация

Environment Variables (.env)

# Database
DATABASE_URL=postgresql+asyncpg://mybeacon:password@localhost/mybeacon

# Security
SECRET_KEY=your-secret-key-here-minimum-32-chars
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=15
REFRESH_TOKEN_EXPIRE_DAYS=30

# Redis (optional)
REDIS_URL=redis://localhost:6379/0

# Server
HOST=0.0.0.0
PORT=8000

Device Default Config

Дефолтная конфигурация для устройств (см. app/api/v1/config.py):

BLE enabled, batch_interval_ms: 2500
WiFi monitor disabled по умолчанию
SSH/Dashboard tunnels disabled
NTP servers: pool.ntp.org, time.google.com

Конфигурация перезаписывается через device.config (JSONB).

Безопасность

JWT токены с expiration (15 мин access, 30 дней refresh)
Device tokens уникальные, хранятся в БД
Bcrypt для паролей (cost factor 12)
HTTPS рекомендуется (nginx reverse proxy)
RBAC на уровне endpoints
Multi-tenant изоляция в SQL queries

Мониторинг

События логируются в консоль:

[REGISTRATION] device=MAC simple_id=N
[BLE BATCH] device=MAC simple_id=N count=X
[WIFI BATCH] device=MAC simple_id=N count=X

ClickHouse для хранения событий будет добавлен позже.

Roadmap

ClickHouse интеграция для событий
WebSocket для real-time BLE карты
Frontend (Vue 3)
Email notifications
Audit logs middleware
Rate limiting
Grafana dashboards

BACKEND.md 10.0 KB History Raw