MyBeacon Backend MVP - Ready for Testing

Статус реализации

✅ MVP ЗАВЕРШЕН - Backend готов к тестированию на реальном железе!

Что реализовано

1. Authentication & Authorization

✅ JWT authentication (access + refresh tokens)
✅ User registration/login
✅ Role-based access control (RBAC)
✅ 6 ролей: superadmin, owner, admin, manager, operator, viewer

2. Multi-tenant Architecture

✅ Organization isolation
✅ Users belong to organizations
✅ Devices assigned to organizations
✅ Cross-organization access denied

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

✅ Organizations CRUD
✅ Users management (all organizations)
✅ Devices management (all organizations)
✅ Product flags (wifi_enabled, ble_enabled)

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

✅ View own organization
✅ Manage users in own organization (owner/admin only)
✅ View devices in own organization
✅ Multi-tenant isolation enforced

5. Device API (`/api/v1/device/*`)

✅ Device authentication by MAC address
✅ Get device configuration
✅ Send heartbeat with metadata
✅ Send events batch (WiFi/BLE)

6. Database

✅ PostgreSQL 16 with async SQLAlchemy
✅ Alembic migrations
✅ Device simple_id auto-increment (Receiver #1, #2, #3...)
✅ Audit logs table (ready for middleware)

API Endpoints

Authentication

POST /api/v1/auth/register      - User registration
POST /api/v1/auth/login         - Login (returns JWT tokens)
POST /api/v1/auth/refresh       - Refresh access token
GET  /api/v1/auth/me            - Get current user info

Superadmin (requires superadmin role)

GET    /api/v1/superadmin/organizations        - List all organizations
POST   /api/v1/superadmin/organizations        - Create organization
GET    /api/v1/superadmin/organizations/:id    - Get organization
PATCH  /api/v1/superadmin/organizations/:id    - Update organization
DELETE /api/v1/superadmin/organizations/:id    - Delete organization

GET    /api/v1/superadmin/users                - List all users
POST   /api/v1/superadmin/users                - Create user
GET    /api/v1/superadmin/users/:id            - Get user
PATCH  /api/v1/superadmin/users/:id            - Update user
DELETE /api/v1/superadmin/users/:id            - Delete user
POST   /api/v1/superadmin/users/:id/change-password - Change user password

GET    /api/v1/superadmin/devices              - List all devices
POST   /api/v1/superadmin/devices              - Register device
GET    /api/v1/superadmin/devices/:id          - Get device
PATCH  /api/v1/superadmin/devices/:id          - Update device
DELETE /api/v1/superadmin/devices/:id          - Delete device

Client (requires owner/admin for write operations)

GET    /api/v1/client/organization/me          - Get own organization
GET    /api/v1/client/users                    - List users in own org
POST   /api/v1/client/users                    - Create user in own org (owner/admin only)
GET    /api/v1/client/users/:id                - Get user from own org
PATCH  /api/v1/client/users/:id                - Update user in own org (owner/admin only)
DELETE /api/v1/client/users/:id                - Delete user from own org (owner/admin only)
POST   /api/v1/client/users/:id/change-password - Change password (owner/admin only)

GET    /api/v1/client/devices                  - List devices in own org
GET    /api/v1/client/devices/:id              - Get device from own org

Device API (for hardware devices)

POST /api/v1/device/auth         - Authenticate device by MAC address
GET  /api/v1/device/config       - Get device configuration (requires device token)
POST /api/v1/device/heartbeat    - Send heartbeat with metadata (requires device token)
POST /api/v1/device/events       - Send events batch (requires device token)

Тестовые данные

Пользователи в базе

Superadmin:

Email: superadmin@mybeacon.com
Password: Admin123!
Role: superadmin

Organization Owner:

Email: admin@mybeacon.com
Password: Admin123!
Role: owner
Organization: MyBeacon Admin (ID: 4)

Operator (только что создан):

Email: operator@mybeacon.com
Password: Operator123!
Role: operator
Organization: MyBeacon Admin (ID: 4)

Устройства

Device #5 (Receiver #2):

MAC: AA:BB:CC:DD:EE:02
Organization: MyBeacon Admin (ID: 4)
Status: online
Simple ID: 2 (отображается как "Receiver #2")

Запуск сервера

cd /home/user/work/luckfox/alpine/mybeacon-backend/backend
poetry run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Сервер доступен по адресу: http://192.168.5.4:8000

API документация (Swagger): http://192.168.5.4:8000/docs

Тестирование на реальном железе

Подготовка

Зарегистрировать устройство через superadmin API:

curl -X POST http://192.168.5.4:8000/api/v1/superadmin/devices \
 -H "Authorization: Bearer YOUR_SUPERADMIN_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mac_address": "REAL_DEVICE_MAC",
   "organization_id": 4
 }'

Обновить MAC-адрес в демо-скрипте:

nano /tmp/demo_hardware.sh
# Изменить DEVICE_MAC на реальный MAC устройства

Запустить демо на железке (192.168.5.244):

# Скопировать скрипт на железку
scp /tmp/demo_hardware.sh root@192.168.5.244:/tmp/

# Запустить на железке
ssh root@192.168.5.244 'bash /tmp/demo_hardware.sh'

Проверка работы демона

Демон настроен в /home/user/work/luckfox/alpine/overlay/etc/init.d/S98mybeacon:

Сервер: http://192.168.5.4:8000 ✅ (обновлен)
Heartbeat: каждые 60 секунд
События: WiFi probes и BLE scans

Запуск демона на железке:

ssh root@192.168.5.244 '/etc/init.d/S98mybeacon start'

Проверка логов:

ssh root@192.168.5.244 'tail -f /var/log/mybeacon.log'

Тестовые скрипты

1. Полное тестирование Client API

bash /tmp/test_client.sh

2. Полное тестирование Device API

bash /tmp/test_device_api.sh

3. Демонстрация интеграции с железом

bash /tmp/demo_hardware.sh

Результаты тестирования

✅ Authentication

Register: работает
Login: работает (access + refresh tokens)
/me: работает
Refresh token: работает

✅ Superadmin API

Organizations CRUD: все endpoints работают
Users CRUD: все endpoints работают
Devices CRUD: все endpoints работают
RBAC: обычные пользователи получают 403

✅ Client API

Organization info: работает
User management: работает
Device viewing: работает
Multi-tenant isolation: работает (403 при попытке доступа к другой организации)

✅ Device API

Authentication: работает (JWT токен с type="device")
Get config: работает
Heartbeat: обновляет last_seen_at и metadata
Events: принимает WiFi/BLE события
Metadata в config: uptime, load_avg, memory_free, cpu_temp

Следующие шаги (Post-MVP)

1. Audit Logging (Приоритет 1)

Middleware для автоматического логирования всех действий
Endpoints для просмотра audit logs

2. ClickHouse Integration (Приоритет 2)

Хранение WiFi/BLE событий в ClickHouse
Аналитика по событиям
Графики и статистика

3. WebSocket для BLE Map (Приоритет 3)

Real-time обновления позиций BLE-устройств
WebSocket endpoints
Frontend карта с локациями

4. Frontend (Приоритет 4)

Vue 3 + Vite
Login/Register страницы
Dashboard для superadmin
Dashboard для client (organization view)
Device management UI

5. Production Deployment

systemd service для backend
nginx reverse proxy
SSL certificates
Environment-specific configs

Технологический стек

Backend: Python 3.11, FastAPI, SQLAlchemy (async)
Database: PostgreSQL 16
Cache: Redis (готов к использованию)
Authentication: JWT (python-jose)
Password hashing: bcrypt
Migrations: Alembic
Development: Poetry, uvicorn --reload

API Security

JWT tokens с expiration
Device tokens с type="device"
RBAC на уровне endpoints
Multi-tenant isolation в queries
Password hashing с bcrypt
HTTPS ready (nginx будет терминировать SSL)

Known Issues & Improvements

Исправлено:

✅ JWT "Subject must be a string" - исправлено (конвертация в string)
✅ Device simple_id NULL - исправлено (server_default)
✅ Bcrypt/passlib compatibility - исправлено (прямой bcrypt)
✅ Device token type verification - исправлено (type="device" support)

TODO:

Email verification (сейчас заглушка)
Password reset flow
Rate limiting на login endpoint
Audit logging middleware
WebSocket для real-time updates
ClickHouse для event storage

Contact

Разработчик: Claude Sonnet 4.5 Проект: MyBeacon Backend MVP Дата: 2025-12-27

BACKEND_MVP_READY.md 9.8 KB History Raw