Saltar a contenido

La API central (portal-api)

riveroaks/portal-api es un Cloudflare Worker de TypeScript. Su catálogo mapea recursos canónicos /api/v1 a adaptadores PHP, manejadores nativos de ticket-live o el enlace de servicio de tareas de desarrollo (Tasks). assistant sigue siendo un recurso planificado que devuelve 501. Fuentes: portal-api · src/contract.ts, portal-api · src/index.ts.

Ciclo de vida de la solicitud

El Worker valida el nombre de host/carril configurado, la codificación de la ruta, la ruta, el método, los límites del cuerpo y la forma del encabezado de autenticación. Las llamadas ordinarias rechazan cookies y actualizaciones; ticket-live tiene una ruta de actualización dedicada. Los enlaces separados de autenticación/límite de tasa de API proporcionan una capa de protección contra abusos en el borde. PHP también aplica sus propios límites. Fuente: portal-api · src/index.ts, portal · dashboard/api/mobile/v1/lib/runtime.php.

Para un recurso del Portal, construye una ruta de origen permitida, elimina encabezados de reenvío/cookies que se pueden falsificar, establece metadatos de reenvío confiables y un ID de solicitud, y llama a PRIVATE_PORTAL_API.fetch. Los encabezados devueltos se sanitizan y las respuestas incluyen X-Request-ID y X-Portal-API-Release. Las llamadas del navegador utilizan el Portal BFF; este no es un proxy CORS general. Fuente: portal-api · src/index.ts.

Conectividad privada

OpenTofu enlaza un servicio HTTP de VPC de Workers al túnel Goshen existente y 10.200.24.42:80. El Worker selecciona el nombre de host del Portal coincidente de su configuración, por lo que la selección de Host de nginx separa los pagos. El último salto declarado es HTTP; no lo describa como TLS de origen de extremo a extremo. Fuentes: portal-api · infra/modules/portal-platform/main.tf, portal-api · src/index.ts, infra · nginx/hosts/rocc-db/sites-enabled/ro.church.conf.

Dev es propietario del recurso de Servicio de VPC; producción hace referencia a ese ID de servicio existente en lugar de poseer un duplicado. Los Workers, los dominios personalizados, los espacios de nombres de límites de tasa y los estados de Terraform son específicos del carril. El conector compartido, el host de origen y el puerto siguen siendo dependencias comunes. Fuentes: portal-api · infra/modules/portal-platform/main.tf, portal-api · infra/environments/alpha/main.tf, portal-api · infra/environments/production/main.tf.

Catálogo de recursos

Los siguientes grupos resumen el catálogo de fuente de desarrollo; cada método exacto, etiqueta de permiso, estado de implementación, estilo de autenticación y bandera devOnly se encuentra en portal-api · src/contract.ts. Compare con portal-api · src/contract.ts antes de asumir que producción soporta una de estas rutas. Las etiquetas no reemplazan las verificaciones de permisos en tiempo de ejecución del adaptador.

Grupo Recursos canónicos Backend
Identidad me, bootstrap, web-session Portal PHP
Tickets tickets, ticket-attachments, ticket-email-reply Portal PHP
Invalidación de tickets tickets-live-token, tickets-live, ticket-live-ingest Worker + Objeto Duradero
Presupuesto budget, budget-expenses, budget-inbox, budget-admin, budget-export Portal PHP
Herramientas del personal links, sermon-slides, services, files, network, physical-access, device-updates, automation Portal PHP
Gastos expense-requests, receipt-link Portal PHP
Alertas alerts, alerts-wait, alert-ingest, alert-preferences, push-installations, task-alert-ingest Portal PHP
Comunicaciones comms, comms-ingest, panic-ingest Portal PHP y instantáneas de RAM
Acceso doors, access-cards Portal PHP, entradas de catálogo solo para desarrollo
Tareas tasks, task-detail, task-comments, task-comment, task-projects, task-project-assignees, task-alert-preferences Tasks Worker, solo para desarrollo
Reserva de asistente assistant Planificado (501)

Estilos de autenticación

Estilo Uso Evidencia
Bearer Llamadas nativas del personal y Portal BFF portal · dashboard/api/mobile/v1/lib/runtime.php
alert-hmac Eventos de máquina firmados, incluyendo rutas de ingesta de alertas y tickets portal-api · src/contract.ts, portal · dashboard/api/mobile/v1/lib/alert-ingest.php
comms-hmac Instantáneas de comunicaciones y pánico portal · dashboard/api/mobile/v1/lib/comms.php
connect-token WebSocket de ticket-live portal-api · src/ticket-live.ts

GET /oauth/authorize redirige a Portal auth/start.php. POST /oauth/token y /oauth/revoke se proxy a través del servicio de tokens y los adaptadores de revocación familiar. El borde no es una base de datos de usuarios OAuth independiente. Fuentes: portal-api · src/index.ts, portal · dashboard/api/mobile/v1/auth/start.php, portal · dashboard/api/mobile/v1/token.php, portal · dashboard/api/mobile/v1/revoke.php.

Actualizaciones en vivo de tickets (WebSocket)

El BFF del navegador protegido contra CSRF obtiene un token de conexión con su portador mantenido por el servidor. El Worker verifica la identidad/permiso del Portal y emite un token firmado de 60 segundos. La actualización acepta credenciales de subprotocolo exactas y el Portal Origin coincidente, sin token de consulta. Fuentes: portal · dashboard/v2/tickets/api/live-token.php, portal-api · src/index.ts, portal-api · src/ticket-live.ts.

Un TicketLiveHub con ámbito de entorno almacena una revisión monótonamente creciente en SQLite y transmite notificaciones genéricas de tickets.changed. El contenido del ticket y los registros de usuario no se almacenan en ese hub. Los clientes vuelven a obtener los datos autorizados; la cola del Portal conserva la opción de sondeo de respaldo. Fuentes: portal-api · src/ticket-live-hub.ts, portal-api · docs/TICKETS_LIVE.md, portal · docs/ticket-portal-live-updates.md.

Pasarela de tareas (solo desarrollo)

Para una ruta de Tareas, la API primero solicita al adaptador de arranque privado del Portal una identidad de personal activa actual, luego firma una aserción de 30 segundos que cubre el método, la ruta/consulta, el resumen del cuerpo y el ID de solicitud. Llama a TASKS_API a través de un enlace de servicio, no una obtención de nombre de host público. El rol de la pasarela es la identidad y el transporte; Tareas es responsable de su autorización. Fuentes: portal-api · src/index.ts, portal-api · docs/TASKS.md, portal-api · infra/modules/portal-platform/main.tf.

Las rutas de mutación requieren encabezados explícitos de idempotencia/versión donde se definen. El rechazo de la aserción se convierte en 502, evitando una actualización engañosa del token de usuario. Las verificaciones de configuración prohíben habilitar esta pasarela en producción. Fuente: portal-api · src/index.ts, portal-api · infra/modules/portal-platform/main.tf.

Entrega de alertas

El Portal determina los destinatarios, la deduplicación, las preferencias y el estado de lectura. El transporte nativo en primer plano utiliza alerts y alerts-wait limitados; la entrega de APNs la realiza el remitente en segundo plano del Portal. El desarrollo también puede utilizar el proxy de alertas LAN estrecho, con respaldo de API pública. Fuentes: portal · docs/mobile-alerts.md, portal · scripts/mobile-apns-worker.php, portal-ios · Sources/PortalCore/APIClient.swift, infra · nginx/hosts/rocc-db/sites-enabled/dev-alerts.riveroaks.cc.conf.

Salud, implementación y registros

/healthz es una respuesta directa de actividad del Worker. El desarrollo añade /health/live y /health/ready (también /api/v1/_origin/health): la preparación espera que el adaptador de arranque privado rechace una llamada no autenticada con 401. No prueba que todos los recursos o trabajadores en segundo plano estén saludables. Fuentes: portal-api · src/index.ts, portal-api · src/index.ts.

Las etapas de CI son validate, test, plan, deploy, verify; el desarrollo aplica y realiza pruebas automáticamente después de sus puertas, mientras que la aplicación/pruebas de producción requieren ENABLE_PRODUCTION_API=true. alpha es el nombre histórico de la raíz/estado de IaC de desarrollo, no un tercer carril de ejecución. Fuentes: portal-api · .gitlab-ci.yml, portal-api · infra/environments/alpha/backend.tf.

La IaC habilita los registros de invocación del Worker; la aplicación emite registros de resultados limitados. Nunca incluya tokens, instantáneas o registros personales en la salida de depuración. Los planes/estados guardados pueden contener enlaces secretos incluso cuando las variables están marcadas como sensibles. Fuentes: portal-api · infra/modules/portal-platform/main.tf, portal-api · infra/modules/portal-platform/variables.tf, portal-api · .gitlab-ci.yml, portal-api · src/index.ts.

Operaciones y reversión: portal-api · docs/OPERATIONS.md. Añada un recurso en el catálogo, implemente/despliegue primero su adaptador de origen, actualice las pruebas de contrato y luego siga el orden de lanzamiento. Fuente: portal-api · CONTRIBUTING.md, portal-api · docs/MIGRATION.md.