139 lines
8.1 KiB
Markdown
139 lines
8.1 KiB
Markdown
# Ignis App
|
||
|
||
Мобильное приложение для управления умными лампами WiZ через self-hosted сервер [Ignis Core](https://git.akokos.ru).
|
||
|
||
## Возможности
|
||
|
||
- **Мульти-дом** -- поддержка нескольких серверов Ignis (квартира, дача, друзья). Каждый дом -- отдельный сервер со своим URL и API-ключом.
|
||
- **Группы ламп** -- создание, удаление, управление. При создании группы можно выбрать нужные лампы из списка обнаруженных устройств, пересканировать сеть.
|
||
- **Управление освещением:**
|
||
- Включение/выключение
|
||
- Яркость 10--100% с шагом 10%
|
||
- Цветовая температура 2700--6500K с шагом 100K
|
||
- RGB-цвет через HSV-пикер
|
||
- Сцены (загружаются с сервера)
|
||
- Таймер "включить на 4 часа"
|
||
- **Расписания** -- одноразовые таймеры и cron-задачи с выбором дней недели. Просмотр и отмена активных задач.
|
||
- **API-ключи** -- просмотр, создание, отзыв и повторная активация гостевых ключей для администраторов.
|
||
- **Статистика и лог событий** -- просмотр сводки по группам и последних событий сервера.
|
||
- **Геофенс** -- опциональное автовыключение света при уходе от дома.
|
||
|
||
## Стек
|
||
|
||
- Flutter 3.x / Dart
|
||
- Riverpod -- управление состоянием
|
||
- Dio -- HTTP-клиент
|
||
- SharedPreferences -- локальное хранение несекретных настроек
|
||
- Flutter Secure Storage -- безопасное хранение API-ключей
|
||
- Geolocator -- геолокация
|
||
- Workmanager -- периодические фоновые задачи
|
||
- Flutter Local Notifications -- локальные уведомления
|
||
|
||
## Структура проекта
|
||
|
||
```
|
||
lib/
|
||
├── app/
|
||
│ └── app_bootstrap.dart -- bootstrap приложения и стартовые состояния
|
||
├── main.dart -- точка входа, тема, роутер
|
||
├── models/
|
||
│ └── home_config.dart -- несекретная модель "дома" (сервер)
|
||
├── services/
|
||
│ ├── api_client.dart -- обёртка Dio для Ignis API
|
||
│ ├── credentials_storage.dart -- безопасное хранение API-ключей
|
||
│ ├── geofence_worker.dart -- фоновая проверка геофенса
|
||
│ └── settings_service.dart -- хранение домов и миграция ключей
|
||
├── providers/
|
||
│ └── providers.dart -- Riverpod-провайдеры
|
||
├── screens/
|
||
│ ├── api_keys_screen.dart -- управление API-ключами
|
||
│ ├── event_log_screen.dart -- лог событий
|
||
│ ├── homes_screen.dart -- список домов
|
||
│ ├── home_edit_screen.dart -- добавление/редактирование дома
|
||
│ ├── remote_screen.dart -- пульт управления группами
|
||
│ ├── group_edit_screen.dart -- создание группы
|
||
│ ├── schedules_screen.dart -- расписания
|
||
│ └── stats_screen.dart -- статистика
|
||
└── widgets/
|
||
├── group_card.dart -- карточка группы с управлением
|
||
└── color_picker.dart -- HSV-пикер цвета
|
||
```
|
||
|
||
## Сборка
|
||
|
||
```bash
|
||
# Зависимости
|
||
flutter pub get
|
||
|
||
# Debug-запуск
|
||
flutter run
|
||
|
||
# Release APK
|
||
flutter build apk --release
|
||
```
|
||
|
||
APK: `build/app/outputs/flutter-apk/app-release.apk`
|
||
|
||
> Сейчас release APK подписывается debug-ключом из Flutter-шаблона. Для личной установки на телефон этого достаточно, для настоящего релиза подпись нужно заменить.
|
||
|
||
## Проверки
|
||
|
||
```bash
|
||
flutter analyze
|
||
flutter test
|
||
```
|
||
|
||
Текущий baseline зелёный: анализатор без issues, тесты проходят. Перед установкой на телефон дополнительно проверялась сборка:
|
||
|
||
```bash
|
||
flutter build apk --debug
|
||
flutter build apk --release
|
||
```
|
||
|
||
## Настройка
|
||
|
||
При первом запуске приложение попросит добавить "дом" -- указать адрес сервера Ignis и API-ключ. После этого откроется пульт управления группами.
|
||
|
||
Для добавления второго дома: кнопка "домик" в левом верхнем углу пульта -> экран домов -> кнопка "+".
|
||
|
||
API-ключи хранятся отдельно от конфигурации домов в `flutter_secure_storage`. Старые ключи, сохранённые прежними версиями приложения в `SharedPreferences`, автоматически мигрируются при запуске.
|
||
|
||
## API
|
||
|
||
Приложение работает с [Ignis Core API](https://git.akokos.ru) -- self-hosted бэкенд на FastAPI для управления лампами WiZ по локальной сети. Используемые эндпоинты:
|
||
|
||
| Метод | Путь | Назначение |
|
||
|--------|-----------------------------------|-----------------------------|
|
||
| GET | `/devices` | Список ламп |
|
||
| GET | `/devices/groups` | Список групп |
|
||
| GET | `/devices/scenes` | Доступные сцены |
|
||
| POST | `/devices/groups` | Создать группу |
|
||
| DELETE | `/devices/groups/{id}` | Удалить группу |
|
||
| POST | `/devices/rescan` | Пересканировать сеть |
|
||
| POST | `/control/group/{id}` | Управление группой |
|
||
| GET | `/control/group/{id}/status` | Статус группы |
|
||
| POST | `/schedules/once` | Одноразовый таймер |
|
||
| POST | `/schedules/cron` | Cron-расписание |
|
||
| GET | `/schedules/tasks` | Список задач |
|
||
| DELETE | `/schedules/{job_id}` | Отменить задачу |
|
||
| GET | `/auth/me` | Информация о текущем ключе |
|
||
| GET | `/api-keys` | Список гостевых ключей |
|
||
| POST | `/api-keys` | Создать гостевой ключ |
|
||
| POST | `/api-keys/revoke` | Отозвать ключ |
|
||
| POST | `/api-keys/activate` | Активировать ключ |
|
||
| GET | `/stats/summary` | Сводная статистика |
|
||
| GET | `/stats/log` | Лог событий |
|
||
|
||
Авторизация: заголовок `X-API-Key`.
|
||
|
||
## Текущие ограничения
|
||
|
||
- Целевая платформа сейчас Android.
|
||
- Release APK пока подписывается debug-ключом из Flutter-шаблона.
|
||
- Архитектура всё ещё содержит крупный `providers.dart` и много сырых `Map<String, dynamic>`.
|
||
- Обработка ошибок стала лучше на bootstrap/polling, но ещё не унифицирована по всем экранам.
|
||
|
||
## Лицензия
|
||
|
||
Частный проект.
|