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
@@ -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) — эксплуатация