Update docs and drop AI workspace docs

2026-05-16 15:50:40 +07:00
parent 0fd64307b7
commit 85c840ba1b
2 changed files with 122 additions and 113 deletions
--- a/README.md
+++ b/README.md
@@ -1,84 +1,98 @@
 # Ignis Core

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

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

- discovery устройств в локальной сети
- группы устройств
- команды для device/group
- one-shot и cron расписания
- guest/admin/master API-ключи
- event log и базовая статистика
- встроенный UI в `static/index.html`
- встроенный UI без внешних CDN
+- 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`.

-## Запуск
+## Архитектура
+
+- `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.
+
+## Запуск локально

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

 UI: `http://<host>:8000/`

-Готовые deployment-файлы для `systemd`: [deploy/README.md](/home/kokos/workspace/ignis/ignis-core/deploy/README.md:1)
+Готовые файлы для `systemd`: `deploy/README.md`

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

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

 ```env
 IGNIS_API_KEY=change-me
 APP_TIMEZONE=Asia/Novosibirsk
-SCAN_NETWORK=
-DISCOVERY_INTERVAL_SECONDS=600
-DISCOVERY_BACKGROUND_MISSING_THRESHOLD=2
 LOG_LEVEL=INFO
-EVENT_LOG_RETENTION_DAYS=30
-```
-
-БД:
-
-```env
 IGNIS_DATABASE_URL=sqlite+aiosqlite:///./ignis.db
 IGNIS_SYNC_DATABASE_URL=sqlite:///./ignis.db
 ```

-Замечание по discovery:
+Параметры discovery:

- если `SCAN_NETWORK` не задан, сервер сам выбирает private IPv4-подсети обычных интерфейсов и старается не сканировать VPN / docker / tunnel-интерфейсы
- если на хосте есть VPN или несколько интерфейсов, всё равно лучше явно задать `SCAN_NETWORK`
- формат: `192.168.0.0/24` или список через запятую
- startup scan выполняется до старта фонового цикла
- background refresh по умолчанию удаляет устройство только после двух подряд промахов discovery
- manual `POST /devices/rescan` удаляет оффлайн-устройства сразу и возвращает summary (`found`, `added`, `updated`, `removed_offline`, `pending_removal`, `online`)
+```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
+```

-## Авторизация
+Параметры 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`

-Роли:
+- `master` — значение `IGNIS_API_KEY`, полный доступ.
+- `admin` — ключ из БД, доступ к группам, расписаниям, stats и `rescan`.
+- `guest` — чтение и обычное управление светом.

- `master`: значение из `IGNIS_API_KEY`, полный доступ
- `admin`: ключ из БД, доступ к группам, расписаниям, stats и rescan
- `guest`: обычное управление и чтение
+Сервер работает в `fail-closed`: если `IGNIS_API_KEY` не задан, защищённые маршруты отвечают `503`.

-Сервер работает в `fail-closed`: если `IGNIS_API_KEY` не задан, защищённые маршруты недоступны.
-
-Встроенный UI:
-
- использует только локальные статические ассеты
- по умолчанию не сохраняет API-ключ между перезагрузками
- может запомнить ключ только в рамках текущей вкладки браузера
-
-## API
+## HTTP API

 Основные маршруты:

+- `GET /auth/me`
 - `GET /devices`
 - `GET /devices/groups`
 - `GET /devices/scenes`
@@ -100,11 +114,10 @@ IGNIS_SYNC_DATABASE_URL=sqlite:///./ignis.db
 - `POST /api-keys/activate`
 - `GET /stats/summary`
 - `GET /stats/log`
- `GET /auth/me`

-`control` и `schedules` принимают JSON body.
+`control/*` и `schedules/*` принимают JSON body.

-Поддерживаемые параметры команд:
+Поддерживаемые параметры команды:

 - `state`
 - `brightness`
@@ -112,50 +125,48 @@ IGNIS_SYNC_DATABASE_URL=sqlite:///./ignis.db
 - `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` нужно передавать только полной тройкой
+- `r`, `g`, `b` нужно передавать полной тройкой
 - для `schedules/once` нужно передать ровно одно из `run_at` или `hours_from_now`

-## API keys
+Пример:

- список ключей возвращает публичный `key` / `key_id`
- полный секрет возвращается только при создании
- маршруты `/api-keys/*` доступны только `master`
+```bash
+curl -X POST 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}'
+```
+
+## Встроенный UI
+
+- лежит в `static/index.html`, `static/app.js`, `static/ui.css`;
+- использует только локальные ассеты;
+- не использует `localStorage`;
+- может хранить API-ключ только в `sessionStorage` текущей вкладки;
+- умеет базовое управление группами, расписания, API-ключи, stats/log и быстрый таймер на 4 часа.

 ## Хранилище

-Основные таблицы:
+SQLite-таблицы:

 - `groups`
 - `api_keys`
 - `event_log`
 - `schedules`
 - `apscheduler_jobs`
+- `devices`
+
+Важно: реальным runtime-источником истины для онлайн-устройств остаётся in-memory `state_manager.devices`. Таблица `devices` пока не используется как полноценный persistent source of truth.

 ## OpenAPI

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

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

@@ -165,34 +176,33 @@ curl -X POST 'http://localhost:8000/schedules/once' \

 ## Тесты

-Проверка синтаксиса:
+На 2026-05-16 в `tests/` лежит 27 `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;
+- security headers и локальные UI-ассеты;
+- stats summary без двойного счёта `*_requested`.
+
+Команды:

 ```bash
 .venv/bin/python -m compileall app tests main.py
-```
-
-Полный прогон:
-
-```bash
 timeout 120s .venv/bin/python -m unittest discover -s tests -v
 ```

-Сейчас есть 27 тестов. Покрыты:
+## Известные ограничения

- auth и роли
- lifecycle API-ключей
- control/status ошибки и partial success
- валидация scene
- one-shot и cron расписания
- миграция legacy jobs
- auto-subnet selection для discovery
- background offline cleanup threshold
- manual rescan summary и immediate cleanup
- security headers и локальные UI-ассеты
- агрегация stats без двойного счёта `*_requested`
-
-## Ограничения
-
- discovery всё ещё основан на переборе IP по подсетям
- UI остаётся монолитным файлом
- stats пока простые и не заменяют нормальную аналитику
+- discovery по-прежнему основан на переборе IP в подсетях;
+- миграций схемы БД нет, используется `Base.metadata.create_all()`;
+- runtime-state устройств живёт в памяти процесса;
+- встроенный UI остаётся монолитным файлом без отдельной frontend-сборки;
+- stats — это audit/summary, а не полноценная аналитика.
--- a/deploy/README.md
+++ b/deploy/README.md
@@ -1,30 +1,28 @@
 # Deploy

-Практичный минимум для запуска `ignis-core` как `systemd`-сервиса.
+Минимальный `systemd`-деплой для `ignis-core`.

-В папке:
+В каталоге:

- `ignis-core.service` -- шаблон unit-файла
- `ignis-core.env.example` -- пример переменных окружения
+- `ignis-core.service` — unit-файл;
+- `ignis-core.env.example` — пример env-конфига.

-## Предположения
+## Предполагаемая раскладка

-Ниже используется такая раскладка:
+- код: `/opt/ignis/ignis-core`
+- env: `/etc/ignis-core/ignis-core.env`
+- пользователь: `ignis`
+- SQLite: `/var/lib/ignis-core/ignis.db`

- код проекта: `/opt/ignis/ignis-core`
- env-файл: `/etc/ignis-core/ignis-core.env`
- Unix-пользователь: `ignis`
- SQLite БД: `/var/lib/ignis-core/ignis.db`
+Если у вас другие пути, поправьте unit и env-файл.

-Если у вас другие пути, просто поправьте unit и env-файл.
-
-## 1. Подготовить пользователя
+## 1. Создать системного пользователя

 ```bash
 sudo useradd --system --home /opt/ignis --shell /usr/sbin/nologin ignis
 ```

-## 2. Разложить проект
+## 2. Разложить проект и зависимости

 ```bash
 sudo mkdir -p /opt/ignis
@@ -45,12 +43,12 @@ sudo chmod 640 /etc/ignis-core/ignis-core.env
 sudo chown root:ignis /etc/ignis-core/ignis-core.env
 ```

-Что важно заполнить обязательно:
+Минимум, который надо заполнить руками:

 - `IGNIS_API_KEY`
 - `SCAN_NETWORK`

-Для домашней сети лучше задавать `SCAN_NETWORK` явно, особенно если на хосте есть VPN или несколько интерфейсов.
+Для машин с VPN или несколькими интерфейсами `SCAN_NETWORK` лучше задавать явно.

 ## 4. Установить unit

@@ -60,7 +58,7 @@ sudo systemctl daemon-reload
 sudo systemctl enable --now ignis-core.service
 ```

-## 5. Проверка
+## 5. Проверить запуск

 ```bash
 sudo systemctl status ignis-core.service
@@ -79,6 +77,7 @@ sudo systemctl restart ignis-core.service

 ## Замечания

- `StateDirectory=ignis-core` в unit создаёт `/var/lib/ignis-core` автоматически.
+- `StateDirectory=ignis-core` в unit создаёт `/var/lib/ignis-core`.
 - По умолчанию сервис слушает `0.0.0.0:8000`.
- Если нужен reverse proxy, его проще ставить перед `ignis-core`, а сам сервис оставить на локальном порту.
+- Reverse proxy проще ставить перед сервисом, а не внутрь него.
+- Перед обновлением backend-контракта полезно перегенерировать `openapi.json` и прогнать `unittest`.