From c2d7ce5bdcd1b68c4dcdc157fc90fd4331d96392 Mon Sep 17 00:00:00 2001 From: Artem Kokos Date: Mon, 27 Apr 2026 22:52:24 +0700 Subject: [PATCH] docs: refresh README for current architecture --- README.md | 96 ++++++++++++++++++++++++------------------------------- 1 file changed, 41 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index 3539256..f422d53 100644 --- a/README.md +++ b/README.md @@ -11,12 +11,13 @@ - Яркость 10--100% с шагом 10% - Цветовая температура 2700--6500K с шагом 100K - RGB-цвет через HSV-пикер - - Сцены (загружаются с сервера) + - Сцены (загружаются с сервера, отображаются с человекочитаемыми названиями) - Таймер "включить на 4 часа" - **Расписания** -- одноразовые таймеры и cron-задачи с выбором дней недели. Просмотр и отмена активных задач. - **API-ключи** -- просмотр, создание, отзыв и повторная активация гостевых ключей для администраторов. - **Статистика и лог событий** -- просмотр сводки по группам и последних событий сервера. - **Геофенс** -- опциональное автовыключение света при уходе от дома. +- **Устойчивость к ошибкам** -- гранулярные состояния загрузки (`LoadState`), централизованная обработка сетевых сбоев, soft-ошибки при управлении ползунками без спама в UI. ## Стек @@ -31,32 +32,45 @@ ## Структура проекта -``` +```text lib/ ├── app/ -│ └── app_bootstrap.dart -- bootstrap приложения и стартовые состояния +│ ├── app_bootstrap.dart -- bootstrap приложения и навигация +│ ├── build_info.dart -- метаданные сборки (дата, git hash) +│ ├── error_message.dart -- форматирование ошибок API и сети +│ └── load_state.dart -- универсальный стейт загрузки (idle/loading/data/error) ├── main.dart -- точка входа, тема, роутер ├── models/ -│ └── home_config.dart -- несекретная модель "дома" (сервер) +│ ├── api_key_info.dart -- типизированная модель API-ключа +│ ├── auth_info.dart -- информация об авторизации +│ ├── event_log_item.dart -- лог событий +│ ├── home_config.dart -- несекретная конфигурация сервера +│ ├── ignis_device.dart -- устройство умного дома +│ ├── ignis_group.dart -- группа устройств и её состояние +│ ├── ignis_scene.dart -- сцена освещения +│ ├── schedule_task.dart -- задача расписания +│ └── stats_summary.dart -- статистика ├── services/ -│ ├── api_client.dart -- обёртка Dio для Ignis API -│ ├── credentials_storage.dart -- безопасное хранение API-ключей -│ ├── geofence_worker.dart -- фоновая проверка геофенса -│ └── settings_service.dart -- хранение домов и миграция ключей +│ ├── api_client.dart -- HTTP-клиент к Ignis Core API +│ ├── credentials_storage.dart -- безопасное хранение ключей +│ ├── geofence_worker.dart -- фоновая логика геофенса +│ └── settings_service.dart -- хранение списка "домов" ├── providers/ -│ └── providers.dart -- Riverpod-провайдеры +│ └── providers.dart -- Riverpod-провайдеры (god object, подлежит распилу) ├── 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 -- статистика +│ ├── api_keys_screen.dart +│ ├── 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-пикер цвета + ├── build_info_text.dart -- лейбл с версией сборки + ├── group_card.dart + ├── load_error_view.dart -- универсальный виджет ошибок и retry + └── color_picker.dart ``` ## Сборка @@ -68,8 +82,8 @@ flutter pub get # Debug-запуск flutter run -# Release APK -flutter build apk --release +# Release APK (с пробросом build info) +flutter build apk --release --dart-define=IGNIS_BUILD_DATE="$(date -u +'%Y-%m-%dT%H:%M:%SZ')" --dart-define=IGNIS_GIT_SHA="$(git rev-parse --short HEAD)" ``` APK: `build/app/outputs/flutter-apk/app-release.apk` @@ -83,12 +97,7 @@ flutter analyze flutter test ``` -Текущий baseline зелёный: анализатор без issues, тесты проходят. Перед установкой на телефон дополнительно проверялась сборка: - -```bash -flutter build apk --debug -flutter build apk --release -``` +Текущий baseline зелёный: анализатор без issues, юнит-тесты на парсинг домена и состояния проходят штатно. ## Настройка @@ -96,42 +105,19 @@ flutter build apk --release Для добавления второго дома: кнопка "домик" в левом верхнем углу пульта -> экран домов -> кнопка "+". -API-ключи хранятся отдельно от конфигурации домов в `flutter_secure_storage`. Старые ключи, сохранённые прежними версиями приложения в `SharedPreferences`, автоматически мигрируются при запуске. +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`. +Приложение работает с [Ignis Core API](https://git.akokos.ru) -- self-hosted бэкенд на FastAPI (контракт OpenAPI 3.1.0). +Авторизация происходит через заголовок `X-API-Key`. +Доменный слой на стороне клиента полностью типизирован. ## Текущие ограничения - Целевая платформа сейчас Android. - Release APK пока подписывается debug-ключом из Flutter-шаблона. -- Архитектура всё ещё содержит крупный `providers.dart` и много сырых `Map`. -- Обработка ошибок стала лучше на bootstrap/polling, но ещё не унифицирована по всем экранам. +- Архитектура всё ещё содержит крупный `providers.dart`, который подлежит разделению на feature-oriented модули в рамках грядущих рефакторингов. ## Лицензия