# 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")

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

```bash
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`

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

### Подготовка

1. **Зарегистрировать устройство** через superadmin API:
   ```bash
   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
     }'
   ```

2. **Обновить MAC-адрес** в демо-скрипте:
   ```bash
   nano /tmp/demo_hardware.sh
   # Изменить DEVICE_MAC на реальный MAC устройства
   ```

3. **Запустить демо** на железке (192.168.5.244):
   ```bash
   # Скопировать скрипт на железку
   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

Запуск демона на железке:
```bash
ssh root@192.168.5.244 '/etc/init.d/S98mybeacon start'
```

Проверка логов:
```bash
ssh root@192.168.5.244 'tail -f /var/log/mybeacon.log'
```

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

### 1. Полное тестирование Client API
```bash
bash /tmp/test_client.sh
```

### 2. Полное тестирование Device API
```bash
bash /tmp/test_device_api.sh
```

### 3. Демонстрация интеграции с железом
```bash
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