Clientes y publicadores
1. Aplicación iOS (riveroaks/portal-ios)
La aplicación universal de SwiftUI comparte solicitudes de API, modelos y PKCE a través del paquete local PortalCore. El AppEnvironment de la aplicación valida el par de nombres de host de la API/web; APIConfiguration crea las URL de los puntos finales. Fuentes:
portal-ios · Sources/PortalCore/APIClient.swift, portal-ios · Sources/PortalCore/PKCE.swift,
portal-ios · Sources/PortalCore/APIConfiguration.swift,
portal-ios · RiverOaksPortal/App/AppEnvironment.swift.
| Configuración de compilación | Origen de API / navegador | Fuente |
|---|---|---|
| Debug | dev-api.ro.church / dev.portal.ro.church |
portal-ios · Configuration/Debug.xcconfig |
| Prueba interna (TestFlight) | Mismo par de desarrollo; derecho de producción APNs | portal-ios · Configuration/TestFlight.xcconfig |
| Lanzamiento (Release) | api.ro.church / portal.ro.church |
portal-ios · Configuration/Release.xcconfig |
La configuración no es prueba de que se haya enviado una compilación de producción para la App Store. La CI actual de desarrollo protegido carga automáticamente compilaciones internas de TestFlight y tiene un trabajo separado de implementación de Jamf Portal-iPad; el lanzamiento independiente del panel de control es manual. Fuente: portal-ios · .gitlab-ci.yml.
El inicio de sesión utiliza ASWebAuthenticationSession y PKCE. La aplicación almacena los tokens del Portal en un elemento del Keychain solo para dispositivos. Las verificaciones del servidor siguen siendo autoritarias; los permisos del cliente controlan la presentación. Fuentes:
portal-ios · RiverOaksPortal/App/WebAuthenticationService.swift,
portal-ios · RiverOaksPortal/App/KeychainTokenVault.swift,
portal-ios · CONTRIBUTING.md.
La pestaña Asistente tiene su propio cliente Authentik/PKCE. No llama a la implementación reservada /api/v1/assistant del Portal. Fuentes:
portal-ios · Sources/PortalCore/AssistantClient.swift, portal-api · src/contract.ts.
2. Superficies de iPad
| Superficie | Relación central con la API | Evidencia |
|---|---|---|
| Aplicación Portal universal, modo Staff Portal | Las funciones de personal usan la API; los modos de servicio integran paneles de control LAN | portal-ios · RiverOaksPortal/Views/ServiceModes/IPadPortalView.swift |
| Panel de control de servicio independiente | Destino propio, fuentes LAN; sin requisito de token de personal para esas fuentes | portal-ios · project.yml, portal-ios · RiverOaksServiceDashboard/Models/DashboardConfiguration.swift |
| Utilidad River Oaks independiente | Controles de sala Q-SYS a través de QSysKit/QSysRoomUI compartidos; sin API del Portal ni inicio de sesión de personal |
portal-ios · RiverOaksUtility/App/RiverOaksUtilityApp.swift, portal-ios · Sources/QSysKit/QSysConfiguration.swift |
| Páginas de letras/confianza del navegador | Muestra WebSocket independiente de la API del personal | portal · lyrics/index.html, portal · lyrics/confidence.html |
La configuración administrada del panel de control proporciona/anula las URL de las fuentes; los valores predeterminados se encuentran en portal-ios · RiverOaksServiceDashboard/Models/DashboardConfiguration.swift.
La tabla mapea cada fuente predeterminada a su límite del lado del servidor.
| Panel | Ruta | Servidor/fuente |
|---|---|---|
| Acústica/código de tiempo | Service Monitor HTTP/SSE en 10.200.21.38:8080 |
service-monitor · app/backend/internal/handlers/handlers.go, portal-ios · docs/IPAD_SERVICE_DASHBOARD.md |
| Letras, notas de escenario, cuentas regresivas enviadas | Lyrics WebSocket, predeterminado ws://10.200.24.42:8081/ |
portal · lyrics/server.php, portal · lyrics/poll_propresenter.php |
| Planes, elementos, claves, notas | lyrics.riveroaks.cc/songs/api.php |
portal · lyrics/songs/api.php, portal · lyrics/songs/service_elements.php |
| Comunicaciones/pánico | Fotogramas de letras opcionales más /comms/state.json y /comms/panic.json privados; el host con sesión iniciada puede proporcionar un cargador de comunicaciones de la API |
portal · lyrics/comms_feed.php, portal-ios · RiverOaksServiceDashboard/ViewModel/DashboardViewModel.swift, infra · nginx/hosts/rocc-db/sites-enabled/lyrics.riveroaks.cc.conf |
| Respaldo de cuenta regresiva | Rutas proxy ProPresenter estrechas | portal-ios · RiverOaksServiceDashboard/ViewModel/DashboardViewModel.swift, infra · nginx/hosts/rocc-db/sites-enabled/lyrics.riveroaks.cc.conf |
| Modo seguidor/grabación | lyrics-control.riveroaks.cc/api/ipad/*, rutas POST permitidas por origen |
infra · nginx/hosts/rocc-db/sites-enabled/lyrics.riveroaks.cc.conf |
Las encuestas REST de comunicaciones utilizan un intervalo de seguridad de 15 segundos mientras las inserciones están activas y vuelven a un segundo cuando se desconectan o están en silencio durante 20 segundos. El modelo rechaza instantáneas/revisiones antiguas. Las líneas de transcripción finales pueden permanecer visibles durante un minuto; un carril obsoleto no es necesariamente un panel en blanco. Fuentes:
portal-ios · RiverOaksServiceDashboard/Models/DashboardModels.swift,
portal-ios · RiverOaksServiceDashboard/ViewModel/DashboardViewModel.swift.
Controles de sala Q-SYS: las aplicaciones Portal y Utility ahora comparten QSysKit y QSysRoomUI. Los controles de sala utilizan QRC LAN directo (TCP 1710 predeterminado) y activos HTTPS, independientemente de la API central. qsys.host de Jamf puede seleccionar un host válido; la confianza del certificado utiliza pines SPKI administrados o confianza de primer uso por host. Los activos descargados no pueden redirigir QRC. El modo admin del Portal expone los controles de sala; staff y qsys restringen las superficies visibles. Utility requiere un host administrado válido y muestra una pantalla de espera en lugar de adivinar un núcleo. Estas son capacidades de origen, no prueba de implementación en una sala de producción. Fuentes: portal-ios · Sources/QSysKit/QSysConfiguration.swift,
portal-ios · Sources/QSysRoomUI/QSysNetwork.swift,
portal-ios · RiverOaksUtility/App/RiverOaksUtilityApp.swift,
portal-ios · docs/QSYS_ROOM_CONTROLS.md.
Utility es un destino Ad Hoc/Jamf solo para iPad con un trabajo de lanzamiento de desarrollo protegido manual. TestFlight y el carril Jamf universal Portal-iPad siguen siendo automáticos en desarrollo protegido; un programa de caducidad de perfiles de Utility solo verifica la caducidad y no puede lanzar una aplicación. Fuentes: portal-ios · .gitlab-ci.yml,
portal-ios · docs/UTILITY.md.
Alertas de servicio LAN
El panel de control de audio también consulta la instantánea privada /comms/alerts.json cada dos segundos, sin un token de personal. Esta es una ruta separada de las listas de alertas de la API central autenticadas, las preferencias y el registro APNs. El Portal escribe una instantánea limitada respaldada por RAM después de los commits de alertas: solo categorías de servicio/tecnología y tipos de recursos de alerta operativa/de sermón, como máximo diez entradas dentro de una ventana de quince minutos. Una lectura fallida de la fuente mantiene las entradas anteriores; las reglas de frescura del cliente las eliminan. Fuentes:
portal-ios · RiverOaksServiceDashboard/ViewModel/PanicAlertMonitor.swift,
portal-ios · RiverOaksServiceDashboard/Models/DashboardConfiguration.swift,
portal-ios · RiverOaksServiceDashboard/Models/DashboardModels.swift,
portal · dashboard/api/mobile/v1/lib/alerts.php.
El alias de nginx está en el vhost de letras existente restringido a LAN/fuente; no es una API anónima de Internet. Fuente:
infra · nginx/hosts/rocc-db/sites-enabled/lyrics.riveroaks.cc.conf.
3. Portal Web (riveroaks/portal)
El navegador conserva su cookie de sesión del Portal. Las páginas migradas llaman a un PHP BFF; ese servidor mantiene los tokens OAuth y llama a la API canónica correspondiente. El par connect/callback verifica el estado y PKCE, y el cierre de sesión revoca la familia. Fuentes: portal · dashboard/v2/api/lib/client.php,
portal · dashboard/v2/api/connect.php, portal · dashboard/v2/api/callback.php,
portal · docs/WEB_CANONICAL_API_MIGRATION.md.
La cobertura es incremental: utilice la lista de verificación de migración para distinguir las vistas respaldadas por API de los servicios y mutaciones PHP restantes. La habilitación de la producción de BFF requiere una configuración de tiempo de ejecución coincidente explícita; el host de desarrollo canónico tiene valores predeterminados. Fuentes: portal · docs/WEB_CANONICAL_API_MIGRATION.md,
portal · dashboard/v2/api/lib/client.php,
portal · dashboard/api/mobile/v1/lib/core.php.
Para destinos solo web, la aplicación nativa solicita una transferencia de un solo uso a través de web-session; el servidor devuelve un destino permitido con un secreto de fragmento, y web-continue.php lo consume en una sesión PHP vinculada a la familia. Fuentes: portal-ios · Sources/PortalCore/APIClient.swift,
portal · dashboard/api/mobile/v1/web-session.php,
portal · dashboard/api/mobile/v1/web-continue.php.
4. Publicadores de máquinas (envían a la API)
| Productor | Conexión y autorización de API | Fuente |
|---|---|---|
| Q-SYS / Node-RED | Node-RED firma las solicitudes de ingesta de alertas con HMAC con ámbito de publicador | infra · nodered/instances/telegram/qsys-portal-alert.js, portal · dashboard/api/mobile/v1/lib/alert-ingest.php |
| Adaptador Grafana | Verifica la firma de Grafana y vuelve a firmar en el formato de alerta del Portal | infra · docs/alerting/grafana-portal-adapter.md |
| Service Monitor | Publicador de alertas firmado configurable; configurar solo un carril de API cuyo catálogo admita la ingesta | service-monitor · deploy/ota/service-monitor-alert, portal-api · src/contract.ts, portal-api · src/contract.ts |
| Rama de transcripción de captura de datos de adoración | Instantáneas de comunicaciones/pánico firmadas con clave de carril; estado más reciente limitado, sin cola de carga de interrupciones | infrastructure/lyric-follower · macos/WorshipDataCaptureApp/Sources/WorshipDataCaptureApp/CommsPublisher.swift, infrastructure/lyric-follower · macos/WorshipDataCaptureApp/Sources/WorshipDataCaptureCore/Transcription.swift |
| Ayudantes de integración del Portal | Los recursos de correo electrónico de tickets/alertas de tareas utilizan la autenticación del servicio en lugar de una sesión de usuario | portal-api · src/contract.ts, portal · dashboard/api/mobile/v1/ticket-email-reply.php, portal · dashboard/api/mobile/v1/task-alert-ingest.php |
Los publicadores de alertas no pueden proporcionar destinatarios arbitrarios: el Portal valida la política del publicador, los permisos y las preferencias del usuario. Las comunicaciones/pánico utilizan un contrato de firma diferente. Consulte identidad. Fuente: portal · dashboard/api/mobile/v1/lib/alert-ingest.php.
5. Workers de borde alrededor del Portal
Estos tienen sus propios datos/almacenamiento y puertas de lanzamiento; no forman parte de portal-api porque se ejecutan en Cloudflare.
| Repositorio | Flujo y relación con la API central | Evidencia |
|---|---|---|
cloudflare-forms |
Turnstile → envío/archivos adjuntos cifrados → D1, R2 y Cola → adaptador de aplicación; reintentos de cola/DLQ. La entrega utiliza una URL de adaptador configurada y firmada en lugar del contrato de portador del personal | cloudflare-forms · src/index.ts, cloudflare-forms · src/adapter.ts, cloudflare-forms · src/crypto.ts |
cloudflare-email |
Llamador HMAC/idempotente → cola o ruta de adjunto síncrona definida → Servicio de correo electrónico de Cloudflare; D1 rastrea metadatos de entrega/cuota | cloudflare-email · src/index.ts, cloudflare-email · README.md |
cloudflare-short-links |
Redirección pública → D1; espacio de nombres de administración separado protegido por Access/HMAC utilizado por el Portal | cloudflare-short-links · src/index.ts, cloudflare-short-links · src/admin.ts |
API de alertas church-app |
Worker de contenido/alertas de la congregación, contrato y D1 separados; no la API del personal | church-app · services/alerts-api/src/worker.ts |
cloudflare-mobile-edge |
Puerta de enlace opcional anterior; los valores predeterminados de origen desactivan los dominios personalizados y la activación manual. No infiera el enrutamiento en vivo de ese diseño | cloudflare-mobile-edge · README.md, cloudflare-mobile-edge · infra/modules/mobile-edge/main.tf |