docs: Seaca mobile operator guide and FCM setup

Документация для админа и runbook: коды регистрации, устройства, настройка SAC_FCM на сервере. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-10 15:34:34 +10:00
parent 563b836acc
commit e2b5fb7604
4 changed files with 159 additions and 0 deletions
@@ -15,6 +15,8 @@
 | [ssl-certificate.md](ssl-certificate.md) | Wildcard TLS: формат, scp, пути `/etc/ssl/sac/` |
 | [deployment.md](deployment.md) | Эксплуатация, backup, TLS, `sac-deploy.sh` |
 | [operations-prod-status.md](operations-prod-status.md) | **Статус prod** и следующие шаги |
+| [seaca-mobile.md](seaca-mobile.md) | **Seaca**: коды, устройства, сессия, API |
+| [seaca-fcm.md](seaca-fcm.md) | **Seaca push**: Firebase и `SAC_FCM_*` |
 | [workspace-three-repos.md](workspace-three-repos.md) | Multi-root workspace (три репо) |

 ## Порядок чтения
@@ -18,6 +18,12 @@ curl -sS https://sac.kalinamall.ru/health | jq .

 Ожидается `status: ok`, `database: ok`. При устаревших heartbeat агентов — `status: degraded`, поле `hosts_stale` > 0.

+## Мобильные устройства (Seaca)
+
+См. [seaca-mobile.md](seaca-mobile.md) и [seaca-fcm.md](seaca-fcm.md).
+
+После деплоя 0.9.0+: в веб-SAC включить мобильные устройства, выдать код оператору. Push — после настройки FCM и сборки APK с `google-services.json`.
+
 ## Резервное копирование PostgreSQL

 ```bash
@@ -0,0 +1,49 @@
+# FCM (push) для Seaca
+
+Настраивается **только на сервере SAC** и в **Firebase**; в веб-UI — индикатор и тест push на устройство.
+
+## 1. Firebase
+
+1. [Firebase Console](https://console.firebase.google.com/) → создать проект (или использовать существующий).
+2. Добавить Android-приложение с package name **`ru.kalinamall.seaca`** (как в APK Seaca).
+3. Скачать `google-services.json` — файл для **сборки Seaca**, в git не коммитить.
+4. **Project settings → Service accounts → Generate new private key** — JSON для **сервера SAC**.
+
+## 2. Сервер SAC
+
+```bash
+sudo install -o sac -g sac -m 600 /path/to/firebase-key.json \
+  /etc/security-alert-center/fcm-service-account.json
+```
+
+В `/opt/security-alert-center/config/sac-api.env`:
+
+```ini
+SAC_FCM_ENABLED=true
+SAC_FCM_PROJECT_ID=your-firebase-project-id
+SAC_FCM_SERVICE_ACCOUNT_JSON=/etc/security-alert-center/fcm-service-account.json
+```
+
+Перезапуск API:
+
+```bash
+sudo systemctl restart sac-api
+```
+
+## 3. Политика оповещений
+
+**Настройки → Правило оповещений** → канал **Seaca (push)**.
+
+Действуют те же `min_severity`, cooldown и dedup, что для Telegram/email.
+
+## 4. Проверка
+
+1. Телефон привязан (enroll), в списке устройств **FCM: да**.
+2. **Настройки → Мобильные устройства → Тест push** на строке устройства.
+3. Либо сгенерировать событие с severity выше порога policy.
+
+## 5. Ограничения
+
+- FCM доставляет через инфраструктуру Google; payload формирует SAC (заголовок, id, deep link).
+- Без `SAC_FCM_ENABLED=true` push не отправляется; приложение и REST API работают.
+- `google-services.json` нужен приложению; service account JSON — только серверу.
@@ -0,0 +1,102 @@
+# Seaca — мобильный клиент SAC
+
+Репозиторий приложения: [seaca](https://git.kalinamall.ru/PapaTramp/seaca).  
+Требуется SAC **≥ 0.9.0** с применённой миграцией `014`.
+
+---
+
+## Роли
+
+| Где | Кто |
+|-----|-----|
+| Веб-SAC | Админ: мобильные устройства, коды, отзыв, FCM на сервере |
+| Seaca (Android) | Оператор: обзор, события, проблемы, хосты, отчёты; ack/resolve |
+| Веб-SAC | Пользователи SAC, Telegram/SMTP — **не** в приложении |
+
+---
+
+## Включение мобильных устройств (админ)
+
+1. **Настройки → Мобильные устройства (Seaca)**
+2. Включить **«Разрешать мобильным устройствам подключаться»** → **Сохранить мобильные**
+3. В **Правило оповещений** при необходимости включить канал **Seaca (push)** (для push после настройки FCM)
+
+### «Сохранить мобильные»
+
+Сохраняет в БД:
+
+- разрешение подключения новых устройств;
+- максимум активных устройств на одного пользователя SAC;
+- минимальную версию приложения (опционально).
+
+Не настраивает FCM и не выдаёт коды.
+
+### Коды регистрации
+
+| Поле | Смысл |
+|------|--------|
+| Метка | Произвольная подпись для админа |
+| Пользователь | Если выбран — enroll только для этого пользователя |
+| Способ входа | **Логин и пароль + код** — в приложении нужны учётные данные SAC; **Только код** — пароль не нужен, пользователь должен быть выбран в форме |
+| Срок (часов) | Код перестаёт принимать **новые** привязки; уже подключённые телефоны не отключаются |
+
+Код показывается **один раз** после «Выдать код». Передайте оператору: URL сервера (`https://sac.example.com`), код `sacmob_…`, при режиме password — логин/пароль SAC.
+
+### Подключённые устройства
+
+- **Отключить** — отзыв устройства и refresh-токенов; приложение получит 401 при следующем запросе
+- **Тест push** — только если FCM настроен на сервере и у устройства есть FCM-токен
+
+---
+
+## Сессия после привязки
+
+1. Оператор один раз выполняет enroll (`POST /api/v1/mobile/enroll`).
+2. Приложение хранит **access_token** (JWT, ~24 ч) и **refresh_token** (по умолчанию **90 дней**, `SAC_MOBILE_REFRESH_EXPIRE_DAYS` в `sac-api.env`).
+3. Код регистрации после успешного enroll больше не нужен.
+
+Для долгой работы без повторной привязки увеличьте `SAC_MOBILE_REFRESH_EXPIRE_DAYS` (например `3650`). Отзыв устройства в вебе обнуляет доступ немедленно.
+
+---
+
+## Push (FCM) на сервере
+
+Подробно: [seaca-fcm.md](seaca-fcm.md).
+
+Кратко в `config/sac-api.env`:
+
+```ini
+SAC_FCM_ENABLED=true
+SAC_FCM_PROJECT_ID=ваш-firebase-project-id
+SAC_FCM_SERVICE_ACCOUNT_JSON=/etc/security-alert-center/fcm-service-account.json
+```
+
+После изменений: `sudo systemctl restart sac-api` или `sudo /opt/sac-deploy.sh`.
+
+В UI индикатор **FCM: настроен / не настроен** читает эти переменные; править их через веб нельзя.
+
+---
+
+## API (для разработчиков Seaca)
+
+| Метод | Путь |
+|-------|------|
+| GET | `/health` |
+| POST | `/api/v1/mobile/enroll` |
+| POST | `/api/v1/mobile/auth/refresh` |
+| PUT | `/api/v1/mobile/devices/me/fcm` |
+| GET | `/api/v1/dashboards/summary` |
+| GET | `/api/v1/events`, `/api/v1/events/{id}` |
+| GET | `/api/v1/problems`, `/api/v1/problems/{id}` |
+| POST | `/api/v1/problems/{id}/ack`, `/resolve` |
+| GET | `/api/v1/hosts`, `/api/v1/hosts/{id}` |
+
+JWT с мобильного устройства содержит claim `device_id`.
+
+---
+
+## См. также
+
+- [seaca-fcm.md](seaca-fcm.md) — Firebase и push
+- [deployment.md](deployment.md) — деплой SAC
+- [runbook-ops.md](runbook-ops.md) — эксплуатация