Fix API regressions and refresh project docs

2026-05-15 23:12:28 +07:00
parent 654f64bb90
commit 13fba2fa44
19 changed files with 3258 additions and 964 deletions
--- a/README.md
+++ b/README.md
@@ -1,139 +1,167 @@
 # Ignis Core

-Self-hosted сервер для управления умными лампами WiZ по локальной сети. FastAPI бэкенд с веб-интерфейсом, планировщиком расписаний и REST API для мобильного приложения.
+Локальный FastAPI-сервер для управления лампами WiZ.

-## Возможности
+## Что есть

- **Discovery** -- автоматическое обнаружение ламп WiZ в локальной сети (UDP broadcast). Поддержка нескольких подсетей через `SCAN_NETWORK`.
- **Группы** -- объединение ламп в именованные группы (спальня, кухня, ...). Хранение в SQLite.
- **Управление** -- включение/выключение, яркость, цветовая температура, RGB-цвет, 35+ встроенных сцен.
- **Расписания** -- одноразовые таймеры и cron-задачи через APScheduler с персистентным хранилищем.
- **Веб-интерфейс** -- SPA на Vue 3 + Tailwind, встроен в сервер как статика.
- **API** -- REST API с авторизацией по API-ключу для мобильных клиентов.
+- discovery устройств в локальной сети
+- группы устройств
+- команды для device/group
+- one-shot и cron расписания
+- guest/admin/master API-ключи
+- event log и базовая статистика
+- встроенный UI в `static/index.html`

-## Быстрый старт
+## Запуск

 ```bash
-# Клонировать
-git clone https://git.akokos.ru/artem.kokos/ignis-core.git
-cd ignis-core
-
-# Виртуальное окружение
 python3 -m venv .venv
 source .venv/bin/activate
-
-# Зависимости
 pip install -r requirements.txt
-
-# Конфигурация
 cp .env.example .env
-# Отредактировать .env -- указать API-ключ и таймзону
-
-# Запуск
 uvicorn main:app --host 0.0.0.0 --port 8000
 ```

-Сервер будет доступен на `http://<ip>:8000`. Веб-интерфейс -- на корневом URL.
+UI: `http://<host>:8000/`

-## Конфигурация (.env)
+## Конфигурация
+
+Минимум:

 ```env
-# API-ключ для авторизации (если не задан -- авторизация отключена)
-IGNIS_API_KEY=your-secret-key
-
-# Таймзона для расписаний (по умолчанию Asia/Novosibirsk)
-APP_TIMEZONE=Asia/Almaty
-
-# Подсети для сканирования (через запятую, по умолчанию -- автоопределение)
-SCAN_NETWORK=192.168.1.0/24
-
-# Уровень логирования
+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
 ```
-ignis-core/
-├── main.py                      -- точка входа FastAPI, lifespan
-├── requirements.txt             -- зависимости
-├── .env                         -- конфигурация (не в git)
-├── static/
-│   └── index.html               -- веб-интерфейс (Vue 3 SPA)
-├── app/
-│   ├── core/
-│   │   ├── database.py          -- async SQLAlchemy, SQLite
-│   │   ├── discovery.py         -- UDP-сканирование сети WiZ
-│   │   ├── scheduler.py         -- APScheduler + jobstore
-│   │   └── state.py             -- in-memory состояние (устройства, группы)
-│   ├── models/
-│   │   ├── device.py            -- модели Device, Group (SQLAlchemy + Pydantic)
-│   │   └── schedule.py          -- модель ScheduleTask
-│   ├── drivers/
-│   │   └── wiz.py               -- UDP-драйвер протокола WiZ
-│   └── api/
-│       ├── deps.py              -- авторизация (X-API-Key)
-│       └── routes/
-│           ├── devices.py       -- CRUD устройств и групп
-│           ├── control.py       -- управление лампами
-│           └── schedules.py     -- расписания (once, cron)
-└── ignis.db                     -- SQLite база (создаётся автоматически)
-```
+
+Замечание по 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

-Авторизация: заголовок `X-API-Key`.
+Основные маршруты:

-### Устройства и группы
+- `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`

-| Метод  | Путь                     | Описание                     |
-|--------|--------------------------|------------------------------|
-| GET    | `/devices`               | Все обнаруженные лампы       |
-| GET    | `/devices/groups`        | Все группы                   |
-| GET    | `/devices/scenes`        | Доступные сцены WiZ          |
-| POST   | `/devices/groups`        | Создать группу               |
-| DELETE | `/devices/groups/{id}`   | Удалить группу               |
-| POST   | `/devices/rescan`        | Пересканировать сеть         |
+Текущий контракт для `control` и `schedules` использует query-параметры.

-Создание группы (JSON body):
-```json
-{"id": "bedroom", "name": "Спальня", "macs": ["a8bb50aabbcc", "a8bb50ddeeff"]}
+Поддерживаемые параметры команд:
+
+- `state`
+- `brightness`
+- `scene`
+- `temp`
+- `r`, `g`, `b`
+
+Примеры:
+
+```bash
+curl -X POST 'http://localhost:8000/control/device/dev-1?temp=4200' \
+  -H 'X-API-Key: change-me'
 ```

-### Управление
+```bash
+curl -X POST 'http://localhost:8000/schedules/once?target_id=bedroom&hours_from_now=2&is_group=true&temp=3200' \
+  -H 'X-API-Key: change-me'
+```

-| Метод | Путь                             | Описание               |
-|-------|----------------------------------|------------------------|
-| POST  | `/control/device/{id}`           | Управление лампой      |
-| POST  | `/control/group/{id}`            | Управление группой     |
-| POST  | `/control/device/{id}/blink`     | Мигнуть лампой         |
-| GET   | `/control/device/{id}/status`    | Статус лампы           |
-| GET   | `/control/group/{id}/status`     | Статус группы          |
+## API keys

-Query-параметры управления: `state` (bool), `brightness` (int, 10--100), `temp` (int, 2700--6500), `scene` (string), `r`/`g`/`b` (int, 0--255).
+- список ключей возвращает публичный `key` / `key_id`
+- полный секрет возвращается только при создании
+- маршруты `/api-keys/*` доступны только `master`

-### Расписания
+## Хранилище

-| Метод  | Путь                  | Описание                |
-|--------|-----------------------|-------------------------|
-| POST   | `/schedules/once`     | Одноразовый таймер      |
-| POST   | `/schedules/cron`     | Повторяющаяся задача    |
-| GET    | `/schedules/tasks`    | Все активные задачи     |
-| DELETE | `/schedules/{job_id}` | Отменить задачу         |
+Основные таблицы:

-## Стек
+- `groups`
+- `api_keys`
+- `event_log`
+- `schedules`
+- `apscheduler_jobs`

- **FastAPI** -- async HTTP-сервер
- **SQLAlchemy 2.0** -- async ORM, SQLite через aiosqlite
- **APScheduler** -- планировщик с персистентным хранилищем
- **WiZ Protocol** -- UDP-управление лампами (порт 38899)
- **Vue 3 + Tailwind** -- встроенный веб-интерфейс
+## OpenAPI

-## Клиенты
+Актуальная схема лежит в `openapi.json`.

- Веб-интерфейс -- встроен в сервер (`static/index.html`)
- [Ignis App](https://git.akokos.ru/artem.kokos/ignis_app) -- мобильное приложение (Flutter)
+Перегенерация:

-## Лицензия
+```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 остаётся монолитным файлом
+- `control` и `schedules` ещё не переведены на JSON body
+- stats пока простые и не заменяют нормальную аналитику