180 lines
4.7 KiB
Markdown
180 lines
4.7 KiB
Markdown
# Ignis Core
|
|
|
|
Локальный FastAPI-сервер для управления лампами WiZ.
|
|
|
|
## Что есть
|
|
|
|
- discovery устройств в локальной сети
|
|
- группы устройств
|
|
- команды для device/group
|
|
- one-shot и cron расписания
|
|
- guest/admin/master API-ключи
|
|
- event log и базовая статистика
|
|
- встроенный UI в `static/index.html`
|
|
|
|
## Запуск
|
|
|
|
```bash
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -r requirements.txt
|
|
cp .env.example .env
|
|
uvicorn main:app --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
UI: `http://<host>:8000/`
|
|
|
|
## Конфигурация
|
|
|
|
Минимум:
|
|
|
|
```env
|
|
IGNIS_API_KEY=change-me
|
|
APP_TIMEZONE=Asia/Novosibirsk
|
|
SCAN_NETWORK=
|
|
LOG_LEVEL=INFO
|
|
EVENT_LOG_RETENTION_DAYS=30
|
|
```
|
|
|
|
БД:
|
|
|
|
```env
|
|
IGNIS_DATABASE_URL=sqlite+aiosqlite:///./ignis.db
|
|
IGNIS_SYNC_DATABASE_URL=sqlite:///./ignis.db
|
|
```
|
|
|
|
Замечание по discovery:
|
|
|
|
- если на хосте есть VPN или несколько интерфейсов, лучше явно задать `SCAN_NETWORK`
|
|
- формат: `192.168.0.0/24` или список через запятую
|
|
|
|
## Авторизация
|
|
|
|
Заголовок: `X-API-Key`
|
|
|
|
Роли:
|
|
|
|
- `master`: значение из `IGNIS_API_KEY`, полный доступ
|
|
- `admin`: ключ из БД, доступ к группам, расписаниям, stats и rescan
|
|
- `guest`: обычное управление и чтение
|
|
|
|
Сервер работает в `fail-closed`: если `IGNIS_API_KEY` не задан, защищённые маршруты недоступны.
|
|
|
|
## API
|
|
|
|
Основные маршруты:
|
|
|
|
- `GET /devices`
|
|
- `GET /devices/groups`
|
|
- `GET /devices/scenes`
|
|
- `POST /devices/groups`
|
|
- `DELETE /devices/groups/{group_id}`
|
|
- `POST /devices/rescan`
|
|
- `POST /control/device/{device_id}`
|
|
- `POST /control/group/{group_id}`
|
|
- `POST /control/device/{device_id}/blink`
|
|
- `GET /control/device/{device_id}/status`
|
|
- `GET /control/group/{group_id}/status`
|
|
- `POST /schedules/once`
|
|
- `POST /schedules/cron`
|
|
- `GET /schedules/tasks`
|
|
- `DELETE /schedules/{job_id}`
|
|
- `GET /api-keys`
|
|
- `POST /api-keys`
|
|
- `POST /api-keys/revoke`
|
|
- `POST /api-keys/activate`
|
|
- `GET /stats/summary`
|
|
- `GET /stats/log`
|
|
- `GET /auth/me`
|
|
|
|
`control` и `schedules` принимают JSON body.
|
|
|
|
Поддерживаемые параметры команд:
|
|
|
|
- `state`
|
|
- `brightness`
|
|
- `scene`
|
|
- `temp`
|
|
- `r`, `g`, `b`
|
|
|
|
Примеры:
|
|
|
|
```bash
|
|
curl -X POST 'http://localhost:8000/control/device/dev-1' \
|
|
-H 'X-API-Key: change-me' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"temp": 4200}'
|
|
```
|
|
|
|
```bash
|
|
curl -X POST 'http://localhost:8000/schedules/once' \
|
|
-H 'X-API-Key: change-me' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"target_id":"bedroom","hours_from_now":2,"is_group":true,"temp":3200}'
|
|
```
|
|
|
|
Валидация:
|
|
|
|
- `brightness`: `10..100`
|
|
- `temp`: `2200..6500`
|
|
- `r/g/b`: `0..255`
|
|
- `scene`, `temp` и `rgb` взаимоисключаемы
|
|
- `r`, `g`, `b` нужно передавать только полной тройкой
|
|
- для `schedules/once` нужно передать ровно одно из `run_at` или `hours_from_now`
|
|
|
|
## API keys
|
|
|
|
- список ключей возвращает публичный `key` / `key_id`
|
|
- полный секрет возвращается только при создании
|
|
- маршруты `/api-keys/*` доступны только `master`
|
|
|
|
## Хранилище
|
|
|
|
Основные таблицы:
|
|
|
|
- `groups`
|
|
- `api_keys`
|
|
- `event_log`
|
|
- `schedules`
|
|
- `apscheduler_jobs`
|
|
|
|
## OpenAPI
|
|
|
|
Актуальная схема лежит в `openapi.json`.
|
|
|
|
Перегенерация:
|
|
|
|
```bash
|
|
.venv/bin/python -c 'import json, os, pathlib; os.environ.setdefault("IGNIS_API_KEY", "openapi-export"); from main import app; pathlib.Path("openapi.json").write_text(json.dumps(app.openapi(), ensure_ascii=False, indent=2) + "\n", encoding="utf-8")'
|
|
```
|
|
|
|
## Тесты
|
|
|
|
Проверка синтаксиса:
|
|
|
|
```bash
|
|
.venv/bin/python -m compileall app tests main.py
|
|
```
|
|
|
|
Полный прогон:
|
|
|
|
```bash
|
|
timeout 120s .venv/bin/python -m unittest discover -s tests -v
|
|
```
|
|
|
|
Сейчас есть 17 тестов. Покрыты:
|
|
|
|
- auth и роли
|
|
- lifecycle API-ключей
|
|
- control/status ошибки и partial success
|
|
- валидация scene
|
|
- one-shot и cron расписания
|
|
- миграция legacy jobs
|
|
- агрегация stats без двойного счёта `*_requested`
|
|
|
|
## Ограничения
|
|
|
|
- discovery всё ещё основан на переборе IP по подсетям
|
|
- UI остаётся монолитным файлом
|
|
- stats пока простые и не заменяют нормальную аналитику
|