Выбрать ветку (тег)
Найти файл
Клонировать
README.md

README.md

Agura-Alarm

Система оперативного децентрализованного оповещения.

Agura-Alarm

Agura-Alarm — это комплекс для экстренного оповещения групп людей. Система построена на принципах автономности и отказоустойчивости: для доставки сигналов используется локальная Wi-Fi сеть (Unicast Mesh) и, как резервный канал, облачный PHP-сервер (REST API).

Демонстрация Agura-Alarm

Ключевые принципы

  1. Два контура доставки: Мгновенный локальный (Unicast Mesh) и резервный облачный (REST API). Локальный контур работает автономно без доступа в интернет.
  2. Распределенная лента сообщений: Не существует единого источника истины. Сервер и каждое клиентское устройство хранят свою копию 24-часовой ленты и обмениваются ею целиком.
  3. Изоляция конфигураций от ленты: Настройки синхронизируются напрямую с сервером по REST API (/packages) либо переносятся локально в файлах .agacfg и QR-кодом подключения (компактный формат AGACFG1|...: код группы, ключ, адрес сервера, порт) — подключиться к группе можно прямо в мастере первого запуска. Конфигурации никогда не передаются в оперативной ленте сообщений и не рассылаются через P2P-пакеты.
  4. Централизованные источники: Внешние каналы (VK/RSS/MAX) опрашиваются только сервером. Клиенты не имеют прямого доступа к сторонним API.
  5. Единая модель контактов (ContactPeer): Все узлы (локальные UDP-устройства и сервер) представляются единой сущностью контакта с отслеживанием онлайн-статуса и телеметрии.
  6. Только скрипты и никаких баз данных и демонов на сервере Только ленивый запуск процессов и хранение данных в файлах. Сервер переносится копированием папки.

Скриншоты

Спокойный режим Угроза Тревога
Спокойный режим Угроза Тревога
Настройки Каналы источников
Настройки Каналы источников

Связь в локальной сети (Unicast Mesh) — кратко

Мгновенная пересылка. Устройство, получившее новое сообщение от другого устройства или от сервера, немедленно передает его в составе своей ленты остальным устройствам локальной сети. Абоненты получают сообщение сразу — в том числе в режиме «Не беспокоить»: звук тревоги воспроизводится через системный канал будильника и не глушится телефонными режимами.

Локальная сеть = одна подсеть. Устройства считаются соседями, если их IP-адреса отличаются только последним октетом (общая часть X.X.X, например 192.168.2.*), и они входят в одну группу. Обмен идет по Wi-Fi/Ethernet и не требует доступа в интернет.

Как работает Unicast Mesh. Никакого broadcast/multicast:

  1. При старте приложение сканирует свою подсеть и знакомится с соседями (пакеты HELLO / HELLO_ACK).
  2. Адреса всех знакомых узлов хранятся в списке контактов; дальше обмен идет только точечными (unicast) UDP-пакетами.
  3. Узлы обмениваются лентой целиком (24-часовая лента), новые записи сливаются идемпотентно — дубликаты отсекаются по global_source_id.
  4. Каждый узел, получивший новое сообщение, сам становится его источником для остальных — доставка «волной» гарантируется даже при нестабильной связи.

Подробности — в docs/LOCAL_PROTOCOL.md.

Проверено на практике: обкатано на устройствах Android, Huawei и Honor.

Приватность. Приложение не получает местоположение устройства и не использует GPS. Персональные данные устройства (геолокация, контакты, файлы) не собираются и никуда не передаются: сообщения ленты уходят только устройствам своей группы и на сервер своей группы.

Навигация по документации

Документ Описание
docs/ARCHITECTURE.md Целевая архитектура, бизнес-логика, модель данных и правила работы системы. Основной документ.
docs/LOCAL_PROTOCOL.md Спецификация протокола локальной сети (Unicast Mesh).
docs/API_SPEC.md Спецификация REST API сервера.
docs/TESTING.md Инструкции по сборке, тестированию и ручной проверке.
docs/TROUBLESHOOTING.md Диагностика проблем: симптомы → причина → решение.
docs/SECRETS.md Безопасность и управление секретами/ключами.
docs/BACKLOG.md Бэклог развития: задачи P3 и последующих этапов.
docs/manuals/ Руководства: краткая и полная презентации, инструкция пользователя, руководство администратора.
server/README.md Обзор серверной части: назначение, структура папок, ленивое обслуживание без системного cron.
LICENSE.md Лицензия на программное обеспечение (некоммерческое использование).
LICENSE-DOCS.md Лицензия на документацию (CC BY-NC 4.0).
.clinerules/agura-alarm-workflow.md Правила и ограничения для работы в этом проекте.

Для пользователей

Материал Описание
Инструкция пользователя Как установить, настроить и пользоваться приложением.
Руководство администратора Создание группы, ключи, внешние источники, сервер.
Краткая презентация (PDF) О системе в двух словах.
Полная презентация Подробное устройство системы.
Релизы и загрузки APK Готовые сборки для установки.

Структура репозитория

.
├── .clinerules/            # Правила и регламент разработки
├── app/                    # Android-приложение (Kotlin, Jetpack Compose)
│   └── src/main/java/com/agura/alarm/   # Исходный код
│       ├── data/           # Слой данных (модели, репозитории, сеть)
│       ├── domain/         # Бизнес-логика (use cases, политики, матчинг, sync)
│       │   └── sync/       # Декомпозиция mergeFeed: чистые решатели (этап P2c)
│       ├── service/        # Фоновые сервисы (WifiListenerService и др.)
│       ├── ui/             # Пользовательский интерфейс (Compose)
│       └── util/           # Утилиты (ConnectionChecker, IpResolver, LogManager и др.)
├── server/                 # Серверная часть (PHP 8.1 REST API, только ленивые скрипты)
│   ├── config/             # Конфигурация (в репо только example, реальный файл — секрет)
│   ├── data/               # Хранилище данных (группы, источники)
│   ├── index.php           # Маршрутизатор REST API и ленивый опрос источников
│   ├── public/             # Точка входа веб-сервера (index.php — прокси)
│   ├── src/                # PHP-модули (vk_gateway, source_gateway, cleanup, …)
│   ├── tests/              # Серверные тесты (запускаются вручную)
│   └── README.md           # Обзор серверной части
├── gateway/                # Python-шлюз MAX (UDP-мост между PHP-сервером и мессенджером MAX)
├── gradle/                 # Обёртка Gradle (wrapper)
├── docs/                   # Документация проекта
│   ├── ARCHITECTURE.md     # Архитектура и бизнес-логика
│   ├── LOCAL_PROTOCOL.md   # Протокол Unicast Mesh
│   ├── API_SPEC.md         # Детальная спецификация REST API
│   ├── TESTING.md          # Инструкции по тестированию
│   ├── TROUBLESHOOTING.md  # Диагностика проблем
│   ├── SECRETS.md          # Работа с секретами и ключами
│   ├── BACKLOG.md          # Бэклог развития
│   ├── manuals/            # Руководства (презентации, пользователь, админ)
│   ├── examples/           # Примеры (channels_example.toml)
│   ├── images/             # Графика (логотип, скриншоты, соц-превью)
│   └── videos/             # Демонстрационное видео
├── LICENSE.md              # Лицензия на ПО (некоммерческое использование)
├── LICENSE-DOCS.md         # Лицензия на документацию (CC BY-NC 4.0)
└── README.md               # Обзор проекта и навигация

domain/sync/ — декомпозиция mergeFeed на чистые решатели (этап P2c), координатор — AlarmRepositoryImpl:

  • MessageMerger — слияние и дедупликация ленты;
  • CancelApplier — отмены (CANCEL-карточки) и авто-снятие;
  • ReactionEmitter — выбор события для эмиссии;
  • RebroadcastDecider — решение о волновой досылке.

Быстрый старт для разработчика

  1. Ознакомьтесь с docs/ARCHITECTURE.md, чтобы понять ключевые принципы системы.
  2. Изучите .clinerules/agura-alarm-workflow.md перед началом работы с кодом.
  3. Для запуска тестов используйте команду: .\gradlew testDebugUnitTest (на Windows).
  4. Для сборки APK используйте команду: .\gradlew assembleDebug (результат — app/build/outputs/apk/debug/).
  5. Секреты (.env, server/config/server_config.json, доступы к серверу) в репозиторий не входят — получите их у владельца проекта по защищённому каналу, порядок работы описан в docs/SECRETS.md.

Лицензия

  • Программное обеспечение (приложение, сервер, шлюз) — некоммерческая лицензия: LICENSE.md.
  • Документация (README.md, docs/, презентации, руководства) — Creative Commons BY-NC 4.0: LICENSE-DOCS.md.