# Ignis Core Roadmap

Этот roadmap собран по итогам полного обзора текущего состояния `ignis-core`.
Он нужен как рабочий план, а не как абстрактный wishlist.

## Цели проекта

1. Сделать сервер безопасным по умолчанию.
2. Убрать ложные успехи и хрупкое поведение при работе с лампами и сетью.
3. Привести API, UI и документацию к одному контракту.
4. Подготовить кодовую базу к развитию без накопления хаоса.
5. Довести продукт до состояния "можно спокойно жить в проде дома".

## Текущее состояние в двух словах

- Бэкенд маленький и понятный, но уже накопил архитектурный долг.
- Основная логика работает на in-memory state и прямых вызовах драйвера.
- Безопасность и роли реализованы опасно и неполно.
- Фронтенд функциональный, но монолитный и плохо масштабируется.
- Тестовой, миграционной и операционной инфраструктуры почти нет.

## P0: Критично исправить прежде всего

### P0.1 Безопасность по умолчанию

Проблемы:

- При пустом `IGNIS_API_KEY` сервер открывает полный доступ всем.
- Любой `admin`-ключ может управлять всеми гостевыми ключами.
- Полные API-ключи возвращаются из списка ключей.
- Текущий ключ хранится в `localStorage`.
- UI зависит от внешних CDN, что плохо и для безопасности, и для офлайна.

Что сделать:

1. Перевести авторизацию в `fail-closed`.
2. Явно разделить роли `master`, `admin`, `guest`.
3. Разрешить управление API-ключами только мастер-доступу.
4. Перестать возвращать полные ключи из `GET /api-keys`.
5. Возвращать полный токен только в момент создания.
6. Продумать более безопасное хранение ключа в браузере.
7. По возможности убрать CDN-зависимости или хотя бы сделать локальный fallback.

Критерий готовности:

- Сервер без мастер-ключа не выдаёт админ-доступ.
- Гостевой `admin` не может создавать или отзывать другие ключи.
- Повторный запрос списка ключей не раскрывает секреты.

### P0.2 Надёжность команд и статусов

Проблемы:

- Таймауты WiZ дают `None`, а код затем вызывает `.get(...)`.
- Групповое управление отвечает `ok`, даже если отправка провалилась.
- Логирование фиксирует действие без подтверждения результата.
- Ошибка одной лампы может сломать групповой status endpoint.

Что сделать:

1. Нормализовать ответ драйвера: success, timeout, error, payload.
2. Привести все control/status endpoints к одному формату ошибок.
3. Возвращать частичный результат по группам, а не фальшивый успех.
4. Логировать отдельно intent и фактический outcome.
5. Развести ошибки сети, таймауты, офлайн и ошибки протокола.

Критерий готовности:

- Один timeout не валит весь запрос.
- API честно сообщает, сколько устройств обработано успешно.
- Логи не врут о выполнении команды.

### P0.3 Исправление расписаний

Проблемы:

- `cron`-задачи могут затирать друг друга из-за конфликтующих `job_id`.
- Расписания умеют почти только `on/off`.
- Отсутствует нормальная модель хранения пользовательских задач.
- В коде есть мёртвая модель `ScheduleTask`, не совпадающая с реальностью.

Что сделать:

1. Исправить формирование `job_id`.
2. Ввести явную доменную модель расписания.
3. Решить, где источник истины: APScheduler jobstore, своя таблица или оба слоя.
4. Добавить payload для brightness, temp, scene, color.
5. Добавить валидацию cron/once запросов.
6. Сделать idempotent CRUD для задач.

Критерий готовности:

- Разные задачи не затирают друг друга.
- Пользователь может создавать и редактировать полезные сценарии, а не только toggle.
- В модели и БД нет мёртвых или вводящих в заблуждение сущностей.

## P1: Высокий приоритет

### P1.1 Привести API к нормальному контракту

Проблемы:

- Почти все POST-эндпоинты принимают query-параметры.
- Нет явных request/response schemas.
- Нет нормальной валидации диапазонов и конфликтов полей.
- `openapi.json`, код и README расходятся.

Что сделать:

1. Перевести команды управления и расписаний на JSON body.
2. Описать Pydantic-модели для всех запросов и ответов.
3. Добавить строгую валидацию:
   - brightness range
   - temp range
   - RGB range
   - допустимые комбинации scene/temp/rgb
4. Нормализовать коды ошибок и detail messages.
5. Генерировать `openapi.json` из кода и перестать хранить его как случайный артефакт.
6. Обновить README под фактический API.

Критерий готовности:

- Фронт, бэк и OpenAPI описывают одно и то же.
- Внешнему клиенту не нужно угадывать, что именно принимает endpoint.

### P1.2 Починить и переосмыслить discovery

Проблемы:

- README обещает broadcast, а код делает unicast по всей подсети.
- Фоновый discovery не удаляет офлайн-устройства.
- Автоопределение сети упрощённое и часто неверное.
- Большие подсети молча режутся.

Что сделать:

1. Определиться с настоящей стратегией discovery.
2. Привести README к реальной реализации.
3. Добавить понятную стратегию offline detection.
4. Развести initial scan, manual rescan и background refresh.
5. Сохранять полезные метаданные устройства, если они доступны.
6. Логировать сканирование структурированно, а не только строками.

Критерий готовности:

- Список устройств стабилен и предсказуем.
- Пользователь понимает, что именно сканируется и почему устройство исчезло.

### P1.3 Привести event log и stats к реальности

Проблемы:

- Логируются почти только `toggle_on/off`.
- UI уже показывает аналитику по scene/color/brightness/temp, но backend её не считает.
- Оценка часов работы грубая и легко искажается.

Что сделать:

1. Сделать нормальную модель событий:
   - command_requested
   - command_applied
   - command_failed
   - schedule_triggered
2. Хранить полезные параметры структурированно.
3. Переписать stats на основе реальных типов событий.
4. Либо убрать из UI несуществующие метрики, либо реально их реализовать.

Критерий готовности:

- Статистика отражает то, что реально происходило.
- UI не обещает данные, которых нет.

## P2: Поддерживаемость и развитие

### P2.1 Разобрать архитектурный долг

Проблемы:

- В одном месте SQLAlchemy-модели, в другом in-memory state, в третьем прямые драйверные вызовы.
- Есть мёртвые модели и недоведённый дизайн.
- Границы между доменной логикой, API и интеграцией размыты.

Что сделать:

1. Ввести сервисный слой:
   - auth service
   - device service
   - group service
   - control service
   - schedule service
   - stats service
2. Отделить transport layer от доменной логики.
3. Удалить или довести до конца мёртвые сущности.
4. Вынести общие DTO и контракты.
5. Перестать хранить SQLAlchemy-объекты прямо в `state_manager`.

Критерий готовности:

- Роуты тонкие.
- Бизнес-логика тестируется без HTTP.
- Структура проекта подсказывает, где что живёт.

### P2.2 Нормальный фронтенд-контур

Проблемы:

- Весь UI живёт в одном `static/index.html`.
- Нет компонентности, тестов, сборки и типизации.
- Интерфейс уже перерос формат одного файла.

Что сделать:

1. Решить, остаётся ли UI встроенным SPA или выносится в отдельный frontend package.
2. Если остаётся встроенным:
   - разбить на компоненты
   - завести build pipeline
   - локализовать ассеты
3. Если выносится:
   - описать стабильный API-контракт
   - организовать сборку и публикацию статики
4. Добавить базовые UI-тесты хотя бы на критические потоки.

Критерий готовности:

- Добавление новой вкладки или формы не требует править гигантский HTML-файл.

### P2.3 Тесты и инженерная обвязка

Сейчас не хватает:

- unit tests
- integration tests
- API smoke tests
- linting
- CI
- миграций
- health endpoint
- backup/restore стратегии
- нормальной операционной документации

Что сделать:

1. Добавить `pytest`.
2. Покрыть минимум:
   - auth
   - api keys permissions
   - control param validation
   - schedules
   - stats aggregation
3. Добавить миграции, вероятнее всего через Alembic.
4. Добавить `/health` и `/ready`.
5. Добавить базовый CI pipeline.
6. Описать развёртывание и обновление без потери данных.

Критерий готовности:

- Любое опасное изменение ловится до ручной проверки на живых лампах.

## P3: Продуктовые улучшения

### Фичи, которых явно не хватает

1. Редактирование групп, а не только создание и удаление.
2. Нормальные имена устройств и комнат.
3. Управление отдельными устройствами из UI.
4. Расписания с payload, а не только `on/off`.
5. Шаблоны сценариев:
   - bedtime
   - morning
   - away mode
   - timer presets
6. История действий и журнал ошибок в UI.
7. Понятный onboarding при первом запуске.
8. Индикация реального статуса подключения и последнего ответа лампы.
9. Импорт/экспорт конфигурации групп и ключей.
10. Более точное разграничение прав между домашними ролями.

## Рекомендуемый порядок выполнения

### Этап 1

- P0.1 Безопасность по умолчанию
- P0.2 Надёжность команд и статусов

### Этап 2

- P0.3 Расписания
- P1.1 Контракт API

### Этап 3

- P1.2 Discovery
- P1.3 Event log и stats

### Этап 4

- P2.1 Архитектурная чистка
- P2.3 Тесты и инфраструктура

### Этап 5

- P2.2 Фронтенд-контур
- P3 Продуктовые улучшения

## Анти-цели

Пока не стоит:

- Бездумно наращивать фичи поверх текущих проблем безопасности.
- Делать косметический рефакторинг без закрытия P0.
- Добавлять новый клиентский функционал без фикса API-контракта.
- Трогать много слоёв сразу без тестового контура.

## Definition of Done для проекта

Проект можно считать приведённым в сильное состояние, когда:

1. Нет полного доступа без явной конфигурации безопасности.
2. Команды и расписания честно отражают результат выполнения.
3. API, фронтенд и документация синхронизированы.
4. Есть тестовый минимум на критические сценарии.
5. Нет мёртвых моделей и двусмысленных источников истины.
6. UI и backend можно развивать без страха всё сломать.