Refresh project documentation

2026-05-21 22:19:29 +07:00
parent 928e4c71b7
commit e4e7d9029f
3 changed files with 185 additions and 132 deletions
--- a/README.md
+++ b/README.md
@@ -1,112 +1,95 @@
 # Ignis Core

-`ignis-core` — локальный FastAPI-сервер для WiZ-ламп и домашней автоматики вокруг них.
+Локальный FastAPI-сервер для WiZ-ламп: discovery, управление, группы, расписания, API-ключи, аудит и встроенная веб-морда.

-## Что есть сейчас
+## Что умеет

- discovery ламп по локальной сети с `startup`, `manual` и background refresh;
- управление отдельной лампой и группой;
- реальные `status`-опросы и `blink` для идентификации;
- группы в SQLite;
- one-shot и cron-расписания;
- persisted metadata расписаний поверх APScheduler;
- роли `master`, `admin`, `guest`;
- гостевые API-ключи с revoke/activate;
- event log и простая stats summary;
- встроенный локальный UI из `static/`;
- OpenAPI-экспорт в `openapi.json`.
+- искать лампы в локальной сети при старте, вручную и в фоне;
+- управлять лампой или группой;
+- мигать лампой (`blink`) и читать живой статус;
+- хранить группы, ключи, события и расписания в SQLite;
+- выполнять `one-shot` и `cron`-задачи через APScheduler;
+- разделять доступ на `master`, `admin`, `guest`;
+- отдавать встроенный web UI из `static/`;
+- публиковать OpenAPI.

-## Архитектура
+## Структура

- `main.py` — инициализация FastAPI, security headers, router wiring, startup lifecycle.
- `app/api/routes/*` — HTTP-маршруты.
- `app/core/discovery.py` — выбор подсетей и UDP discovery WiZ.
- `app/core/state.py` — in-memory runtime-state устройств и групп.
- `app/core/scheduler.py` — APScheduler, reconciliation и cleanup old events.
- `app/models/*` — SQLAlchemy-модели и Pydantic-схемы.
- `static/` — встроенный web UI без внешних CDN.
+- `main.py` — FastAPI, middleware, lifecycle, статика.
+- `app/api/routes/` — HTTP API.
+- `app/core/discovery.py` — discovery и выбор подсетей.
+- `app/core/scheduler.py` — расписания и reconciliation.
+- `app/core/state.py` — runtime-state устройств и групп.
+- `app/models/` — SQLAlchemy и схемы данных.
+- `static/` — встроенный UI.
+- `deploy/` — `systemd`-деплой и пример env.

-## Запуск локально
+## Быстрый старт

 ```bash
 python3 -m venv .venv
 source .venv/bin/activate
 pip install -r requirements.txt
 cp deploy/ignis-core.env.example .env
-uvicorn main:app --host 0.0.0.0 --port 8000
+.venv/bin/python -m uvicorn main:app --host 0.0.0.0 --port 8000
 ```

-UI: `http://<host>:8000/`
+- UI: `http://127.0.0.1:8000/`
+- OpenAPI runtime: `http://127.0.0.1:8000/openapi.json`
+- Коммитнутый экспорт: [openapi.json](openapi.json)

-Готовые файлы для `systemd`: `deploy/README.md`
+`python-dotenv` подхватывает `.env` автоматически.

-## Конфигурация
+## Конфиг

-Минимальный набор:
+Минимум:

 ```env
 IGNIS_API_KEY=change-me
 IGNIS_INSTANCE_NAME=Home
 APP_TIMEZONE=Asia/Novosibirsk
-LOG_LEVEL=INFO
+SCAN_NETWORK=192.168.0.0/24
 IGNIS_DATABASE_URL=sqlite+aiosqlite:///./ignis.db
 IGNIS_SYNC_DATABASE_URL=sqlite:///./ignis.db
 ```

-Параметры server metadata / versioning:
+Основные переменные:

-```env
-IGNIS_PUBLIC_BASE_URL=https://ignis.example.local
-IGNIS_BUILD_VERSION=1.0.0
-IGNIS_BUILD_DATE=2026-05-21T12:00:00Z
-IGNIS_GIT_SHA=abc1234def56
-```
+- `IGNIS_API_KEY` — мастер-ключ. Без него сервер работает в `fail-closed` и защищённые маршруты отвечают `503`.
+- `IGNIS_INSTANCE_NAME` — имя инстанса в UI и `GET /system/info`.
+- `APP_TIMEZONE` — таймзона расписаний.
+- `SCAN_NETWORK` — подсеть или список подсетей для discovery. На хостах с VPN или несколькими NIC лучше задавать явно.
+- `DISCOVERY_INTERVAL_SECONDS` — период фонового refresh.
+- `DISCOVERY_BACKGROUND_MISSING_THRESHOLD` — сколько циклов подряд лампа может не отвечать до удаления.
+- `DISCOVERY_ENV_MIN_PREFIX_LEN` — минимально допустимая маска для `SCAN_NETWORK`.
+- `DISCOVERY_AUTO_MIN_PREFIX_LEN` — минимально допустимая маска для auto-discovery.
+- `EVENT_LOG_RETENTION_DAYS` — срок хранения event log.
+- `IGNIS_PUBLIC_BASE_URL` — внешний URL, если сервер стоит за reverse proxy.
+- `IGNIS_BUILD_VERSION`, `IGNIS_BUILD_DATE`, `IGNIS_GIT_SHA` — build metadata для диагностики.

- `IGNIS_INSTANCE_NAME` — человекочитаемое имя инстанса, которое видно в UI и `GET /system/info`.
- `IGNIS_PUBLIC_BASE_URL` — внешний URL сервера, если он стоит за reverse proxy или доступен по доменному имени.
- `IGNIS_BUILD_VERSION`, `IGNIS_BUILD_DATE`, `IGNIS_GIT_SHA` — build metadata установленного сервера для диагностики и сверки версий.
+Полный пример: [deploy/ignis-core.env.example](deploy/ignis-core.env.example)

-Параметры discovery:
+## Discovery

-```env
-SCAN_NETWORK=192.168.0.0/24
-DISCOVERY_INTERVAL_SECONDS=600
-DISCOVERY_BACKGROUND_MISSING_THRESHOLD=2
-DISCOVERY_ENV_MIN_PREFIX_LEN=16
-DISCOVERY_AUTO_MIN_PREFIX_LEN=24
-```
+- при старте выполняется `startup_refresh()`;
+- `POST /devices/rescan` делает ручной refresh и сразу убирает оффлайн-устройства;
+- фоновый refresh удаляет устройство только после `DISCOVERY_BACKGROUND_MISSING_THRESHOLD` подряд промахов;
+- если `SCAN_NETWORK` пуст, сервер сам выбирает private IPv4 подсети и старается не лезть в `docker`, `tun`, `wg`, `tailscale` и похожие интерфейсы.

-Параметры retention:
+## Роли

-```env
-EVENT_LOG_RETENTION_DAYS=30
-```
-
-## Как работает discovery
-
- Если `SCAN_NETWORK` задан, сервер сканирует только указанные подсети.
- Если `SCAN_NETWORK` пуст, `DiscoveryService` пытается выбрать private IPv4-сегменты обычных интерфейсов и избегает `docker`, `tun`, `wg`, `tailscale` и похожих интерфейсов.
- При старте выполняется `startup_refresh()`.
- `POST /devices/rescan` делает ручной refresh и сразу удаляет оффлайн-устройства.
- Background refresh работает циклически и удаляет устройство только после `DISCOVERY_BACKGROUND_MISSING_THRESHOLD` подряд пропусков.
-
-Для хостов с VPN, несколькими NIC или нетипичной маршрутизацией `SCAN_NETWORK` лучше задавать явно.
-
-## Авторизация и роли
-
-Заголовок: `X-API-Key`
+Заголовок авторизации: `X-API-Key`

 - `master` — значение `IGNIS_API_KEY`, полный доступ.
- `admin` — ключ из БД, доступ к группам, расписаниям, stats и `rescan`.
- `guest` — чтение и обычное управление светом.
+- `admin` — ключ из БД с `is_admin=true`, доступ к группам, рескану, расписаниям, stats и расширенному `system/info`.
+- `guest` — управление светом и чтение безопасной части API.

-Сервер работает в `fail-closed`: если `IGNIS_API_KEY` не задан, защищённые маршруты отвечают `503`.
+`GET /auth/me` возвращает текущую роль и имя ключа.

 ## HTTP API

-Основные маршруты:
+Основные группы маршрутов:

- `GET /auth/me`
 - `GET /devices`
 - `GET /devices/groups`
 - `GET /devices/scenes`
@@ -130,42 +113,83 @@ EVENT_LOG_RETENTION_DAYS=30
 - `GET /stats/log`
 - `GET /system/info`

-`control/*` и `schedules/*` принимают JSON body.
+Ролевые ограничения:

-Поддерживаемые параметры команды:
+- `guest`: чтение устройств/групп/сцен, управление светом, `status`, `blink`, безопасный `system/info`.
+- `admin`: всё выше плюс создание/удаление групп, `rescan`, расписания, stats/log, расширенный `system/info`.
+- `master`: всё выше плюс управление API-ключами.

- `state`
- `brightness`
- `scene`
- `temp`
- `r`, `g`, `b`
+Формат основных тел:
+
+```json
+{"state": true}
+```
+
+```json
+{"brightness": 60}
+```
+
+```json
+{"temp": 3200}
+```
+
+```json
+{"r": 255, "g": 180, "b": 120}
+```
+
+```json
+{"scene": "Cozy"}
+```

 Валидация:

 - `brightness`: `10..100`
 - `temp`: `2200..6500`
 - `r/g/b`: `0..255`
- `scene`, `temp` и `rgb` взаимоисключаемы
- `r`, `g`, `b` нужно передавать полной тройкой
- для `schedules/once` нужно передать ровно одно из `run_at` или `hours_from_now`
+- можно передать только один режим из `scene`, `temp` или `rgb`
+- `r/g/b` нужно передавать полной тройкой
+- для `POST /schedules/once` нужно передать ровно одно из `run_at` или `hours_from_now`

-Пример:
+Примеры:

 ```bash
-curl -X POST http://127.0.0.1:8000/control/group/bedroom \
+curl -sS http://127.0.0.1:8000/control/group/bedroom \
  -H 'X-API-Key: change-me' \
  -H 'Content-Type: application/json' \
  -d '{"state":true,"brightness":60}'
 ```

+```bash
+curl -sS http://127.0.0.1:8000/api-keys \
+  -H 'X-API-Key: change-me'
+```
+
+Замечания по ключам:
+
+- `GET /api-keys` возвращает публичные `key_id`, а не полный секрет;
+- `POST /api-keys` показывает полный секрет только один раз;
+- `POST /api-keys/revoke` и `POST /api-keys/activate` принимают JSON вида `{"key":"<secret-or-public-id>"}`.
+
 ## Встроенный UI

- лежит в `static/index.html`, `static/app.js`, `static/ui.css`;
+UI лежит в `static/` и не требует отдельной сборки.
+
+Что есть сейчас:
+
+- вход по API-ключу;
+- роль-зависимые вкладки;
+- пульт групп со сценами, яркостью, температурой, цветом и таймером на 4 часа;
+- список устройств и сборка групп;
+- one-shot и cron;
+- серверная вкладка с метаданными инстанса;
+- аудит, stats и API-ключи для нужных ролей.
+
+Свойства UI:
+
 - использует только локальные ассеты;
 - не использует `localStorage`;
- может хранить API-ключ только в `sessionStorage` текущей вкладки;
- показывает build/server metadata текущего инстанса;
- умеет базовое управление группами, расписания, API-ключи, stats/log и быстрый таймер на 4 часа.
+- может хранить ключ только в `sessionStorage` текущей вкладки;
+- гость не видит чувствительные поля `system/info`.

 ## Хранилище

@@ -178,11 +202,15 @@ SQLite-таблицы:
 - `apscheduler_jobs`
 - `devices`

-Важно: реальным runtime-источником истины для онлайн-устройств остаётся in-memory `state_manager.devices`. Таблица `devices` пока не используется как полноценный persistent source of truth.
+Важно:
+
+- онлайн-устройства и статусы живут в runtime-памяти процесса;
+- таблица `devices` пока не является полноценным source of truth;
+- миграций схемы нет, используется `Base.metadata.create_all()`.

 ## OpenAPI

-Актуальная схема хранится в `openapi.json`.
+Актуальная схема закоммичена в `openapi.json`.

 Перегенерация:

@@ -192,34 +220,22 @@ SQLite-таблицы:

 ## Тесты

-На 2026-05-21 в `tests/` лежит 29 `unittest`-сценариев.
-
-Покрыто:
-
- fail-closed auth и role checks;
- lifecycle API-ключей;
- control/status error handling и partial success;
- validation для scene, control body и schedules body;
- one-shot и cron-расписания;
- reconciliation и миграция legacy jobs;
- auto subnet selection для discovery;
- background offline cleanup threshold;
- manual rescan summary;
- server metadata endpoint и отсутствие утечки секретов в нём;
- security headers и локальные UI-ассеты;
- stats summary без двойного счёта `*_requested`.
-
-Команды:
+Основная команда:

 ```bash
-.venv/bin/python -m compileall app tests main.py
 timeout 120s .venv/bin/python -m unittest discover -s tests -v
 ```

-## Известные ограничения
+Дополнительно:

- discovery по-прежнему основан на переборе IP в подсетях;
- миграций схемы БД нет, используется `Base.metadata.create_all()`;
+```bash
+.venv/bin/python -m compileall app tests main.py
+node --check static/app.js
+```
+
+## Ограничения
+
+- discovery всё ещё сетевой перебор внутри выбранных подсетей;
 - runtime-state устройств живёт в памяти процесса;
- встроенный UI остаётся монолитным файлом без отдельной frontend-сборки;
- stats — это audit/summary, а не полноценная аналитика.
+- UI монолитный, без отдельного frontend-build step;
+- stats — это аудит и summary, а не полноценная аналитика.