Описал архитектуру уведомлений Pulse

docs/PUSH_NOTIFICATIONS.md

@@ -0,0 +1,114 @@
+# Pulse Push Notifications
+
+Дата: 2026-05-09
+Репозиторий: viktor138irk/SWChat
+Связанный клиент: viktor138irk/SWChat-App
+
+## Цель
+
+Добавить уведомления Pulse так, чтобы пользователь получал push на Android при новых сообщениях, но сервер Matrix/Synapse не зависел напрямую от клиентского UI.
+
+## Важное решение
+
+Уведомления делаем через отдельный серверный Push Gateway.
+
+Схема:
+
+```text
+Synapse / Matrix
+    ↓ Matrix push rules / pusher
+Pulse Push Gateway
+    ↓ FCM / Android push
+Pulse Android App
+```
+
+Push Gateway должен жить в серверном репозитории `SWChat`, а клиентские настройки и регистрация pusher — в `SWChat-App`.
+
+## Почему нужен Push Gateway
+
+Matrix-клиент не получает push напрямую из Synapse в Firebase. Synapse отправляет push на gateway, а gateway уже отправляет уведомление в Firebase Cloud Messaging.
+
+Это позволяет:
+- не хранить Firebase-логику в Synapse;
+- централизованно управлять push;
+- позже добавить web push, desktop push, Telegram/dev alerts;
+- контролировать payload и приватность;
+- отключать/включать уведомления пользователям.
+
+## MVP Push Gateway
+
+Минимальные функции:
+
+1. Endpoint приёма push от Synapse:
+
+```text
+POST /_matrix/push/v1/notify
+```
+
+2. Проверка входящего payload.
+3. Извлечение event/user/room/pusher данных.
+4. Отправка уведомления в FCM.
+5. Логи отправки.
+6. Healthcheck endpoint:
+
+```text
+GET /health
+```
+
+7. Конфигурация через `.env`.
+8. Отдельный контейнер в `docker-compose.yml`.
+
+## Предварительные домены
+
+Рекомендуемый домен:
+
+```text
+push.stackworks.ru
+```
+
+Альтернатива внутри API:
+
+```text
+api-chat.stackworks.ru/push
+```
+
+На MVP лучше отдельный поддомен `push.stackworks.ru`, чтобы не мешать будущему backend API.
+
+## Требования к Android-клиенту
+
+В `SWChat-App` нужно:
+
+- проверить наличие `google-services.json` под package `ru.stackworks.pulse`;
+- проверить Firebase project;
+- включить FCM token registration;
+- убедиться, что `pushNotificationsAppId = ru.stackworks.pulse`;
+- настроить pusher URL на Pulse Push Gateway;
+- проверить уведомления на debug APK;
+- проверить уведомления на release APK.
+
+## Безопасность
+
+Push Gateway не должен раскрывать текст сообщений без необходимости.
+
+На MVP можно отправлять:
+
+```text
+Новое сообщение
+```
+
+или:
+
+```text
+Новое сообщение в Pulse
+```
+
+Без тела сообщения, пока не будет понятна политика приватности и E2EE.
+
+## Следующий шаг
+
+1. Проверить Android/Firebase config.
+2. Создать каркас `push-gateway` в серверном репозитории.
+3. Добавить сервис в `docker-compose.yml`.
+4. Добавить `.env.example` переменные.
+5. Настроить Synapse pusher/client pusher registration.
+6. Проверить push на тестовом аккаунте.