Vibecoded fixes & readme

2026-03-28 20:11:23 +07:00
parent 62af4e46af
commit d024ba78ab
7 changed files with 631 additions and 259 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,139 @@
+# Ignis Core
+
+Self-hosted сервер для управления умными лампами WiZ по локальной сети. FastAPI бэкенд с веб-интерфейсом, планировщиком расписаний и REST API для мобильного приложения.
+
+## Возможности
+
+- **Discovery** -- автоматическое обнаружение ламп WiZ в локальной сети (UDP broadcast). Поддержка нескольких подсетей через `SCAN_NETWORK`.
+- **Группы** -- объединение ламп в именованные группы (спальня, кухня, ...). Хранение в SQLite.
+- **Управление** -- включение/выключение, яркость, цветовая температура, RGB-цвет, 35+ встроенных сцен.
+- **Расписания** -- одноразовые таймеры и cron-задачи через APScheduler с персистентным хранилищем.
+- **Веб-интерфейс** -- SPA на Vue 3 + Tailwind, встроен в сервер как статика.
+- **API** -- REST API с авторизацией по API-ключу для мобильных клиентов.
+
+## Быстрый старт
+
+```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.
+
+## Конфигурация (.env)
+
+```env
+# API-ключ для авторизации (если не задан -- авторизация отключена)
+IGNIS_API_KEY=your-secret-key
+
+# Таймзона для расписаний (по умолчанию Asia/Novosibirsk)
+APP_TIMEZONE=Asia/Almaty
+
+# Подсети для сканирования (через запятую, по умолчанию -- автоопределение)
+SCAN_NETWORK=192.168.1.0/24
+
+# Уровень логирования
+LOG_LEVEL=INFO
+```
+
+## Структура проекта
+
+```
+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 база (создаётся автоматически)
+```
+
+## API
+
+Авторизация: заголовок `X-API-Key`.
+
+### Устройства и группы
+
+| Метод  | Путь                     | Описание                     |
+|--------|--------------------------|------------------------------|
+| GET    | `/devices`               | Все обнаруженные лампы       |
+| GET    | `/devices/groups`        | Все группы                   |
+| GET    | `/devices/scenes`        | Доступные сцены WiZ          |
+| POST   | `/devices/groups`        | Создать группу               |
+| DELETE | `/devices/groups/{id}`   | Удалить группу               |
+| POST   | `/devices/rescan`        | Пересканировать сеть         |
+
+Создание группы (JSON body):
+```json
+{"id": "bedroom", "name": "Спальня", "macs": ["a8bb50aabbcc", "a8bb50ddeeff"]}
+```
+
+### Управление
+
+| Метод | Путь                             | Описание               |
+|-------|----------------------------------|------------------------|
+| POST  | `/control/device/{id}`           | Управление лампой      |
+| POST  | `/control/group/{id}`            | Управление группой     |
+| POST  | `/control/device/{id}/blink`     | Мигнуть лампой         |
+| GET   | `/control/device/{id}/status`    | Статус лампы           |
+| GET   | `/control/group/{id}/status`     | Статус группы          |
+
+Query-параметры управления: `state` (bool), `brightness` (int, 10--100), `temp` (int, 2700--6500), `scene` (string), `r`/`g`/`b` (int, 0--255).
+
+### Расписания
+
+| Метод  | Путь                  | Описание                |
+|--------|-----------------------|-------------------------|
+| POST   | `/schedules/once`     | Одноразовый таймер      |
+| POST   | `/schedules/cron`     | Повторяющаяся задача    |
+| GET    | `/schedules/tasks`    | Все активные задачи     |
+| DELETE | `/schedules/{job_id}` | Отменить задачу         |
+
+## Стек
+
+- **FastAPI** -- async HTTP-сервер
+- **SQLAlchemy 2.0** -- async ORM, SQLite через aiosqlite
+- **APScheduler** -- планировщик с персистентным хранилищем
+- **WiZ Protocol** -- UDP-управление лампами (порт 38899)
+- **Vue 3 + Tailwind** -- встроенный веб-интерфейс
+
+## Клиенты
+
+- Веб-интерфейс -- встроен в сервер (`static/index.html`)
+- [Ignis App](https://git.akokos.ru/artem.kokos/ignis_app) -- мобильное приложение (Flutter)
+
+## Лицензия
+
+Частный проект.