114 lines
5.3 KiB
Markdown
114 lines
5.3 KiB
Markdown
# 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-api.kalinamall.ru`** для Seaca; веб-админка — `https://sac.kalinamall.ru`), код `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: настроен / не настроен** читает эти переменные; править их через веб нельзя.
|
||
|
||
---
|
||
|
||
## Perimeter (HAProxy)
|
||
|
||
| Hostname | Clients | IP allowlist |
|
||
|----------|---------|--------------|
|
||
| `sac.kalinamall.ru` | Web UI | yes (`git-sac-allowed`) |
|
||
| `sac-api.kalinamall.ru` | Seaca, `/api/v1/mobile/*` | no (enroll + JWT) |
|
||
|
||
Both resolve to the same SAC server (**192.168.160.145**). nginx must accept both names in `server_name`. See [reverse-proxy/docs/sac-access.md](https://git.kalinamall.ru/PapaTramp/reverse-proxy/src/branch/main/docs/sac-access.md).
|
||
|
||
---
|
||
|
||
## 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) — эксплуатация
|