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

1. **superadmin** - полный доступ ко всем организациям и устройствам
2. **owner** - управление своей организацией (создание/удаление пользователей, устройств)
3. **admin** - управление пользователями в организации
4. **manager** - просмотр и частичное управление
5. **operator** - только просмотр устройств
6. **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)
```sql
id, email, hashed_password, full_name, phone,
role, status, organization_id, email_verified,
last_login_at, created_at
```

**organizations** - Организации (клиенты)
```sql
id, name, contact_email, contact_phone,
wifi_enabled, ble_enabled, status, notes, created_at
```

**devices** - Устройства (receivers)
```sql
id, simple_id, mac_address, organization_id,
device_token, device_password, status, last_seen_at,
config (JSONB), created_at
```

**settings** - Системные настройки
```sql
id, key, value (JSONB), updated_at
```

**refresh_tokens** - JWT refresh tokens
```sql
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

### Установка

```bash
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:**
```bash
poetry run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

**Production:**
```bash
poetry run uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
```

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

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

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

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

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

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

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

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

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

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