Soporte del portal, archivos y archivo de servicios

Actualizado el 30 de julio de 2026.

Esta página documenta la recepción de soporte del personal, la transferencia al técnico, la entrega de múltiples pistas y la base del visor de servicios en el Portal de Tecnología de River Oaks. El repositorio del portal es la fuente de verdad para la aplicación. Los cambios pasan por GitLab; no edite manualmente ninguna copia del portal en un servidor.

Recepción de soporte del personal

La recepción guiada se encuentra en /v2/support/.

• Requiere una sesión activa en el portal y una cuenta de personal activa de @riveroaks.org.
• Se presenta como una solicitud de soporte guiada, no como un chat simulado. Las secciones respondidas están numeradas y son editables, y la revisión final es concisa.
• La recepción determinista es la predeterminada. Cuando el proveedor de IA supervisado está habilitado, puede solicitar como máximo una aclaración material etiquetada como Seguimiento automatizado; no aparecen perfiles de asistente ni burbujas de chat.
• El problema exacto del solicitante, el sistema afectado, la ubicación, el impacto, el momento, el estado del evento y las soluciones intentadas se convierten en un registro conciso de incidencias.
• Las solicitudes de audio y teléfono sugieren a Dave como propietario. Redes, TI, iluminación, video, sitios web, acceso y solicitudes inciertas sugieren a Cole.
• La prioridad sugerida se basa en el impacto declarado y en si un servicio o evento está ocurriendo en este momento. Es una recomendación para los técnicos, no una afirmación de hecho.

Todas las notificaciones a los técnicos van inicialmente a technologystaff@riveroaks.org, independientemente del propietario sugerido. Las notificaciones de desarrollo van por defecto a cgood@riveroaks.org. El correo electrónico utiliza la misma estructura visual que las alertas de Q-SYS y contiene la transferencia procesable sin relleno repetido.

La base de datos MySQL tickets existente sigue siendo la fuente de verdad operativa. El formulario no necesita LiteLLM, Authentik, Azure AI Foundry ni Notion para guardar una incidencia. El cliente de IA independiente del proveedor está deshabilitado por defecto y recurre sin bloquear el envío.

La capa de IA opcional utiliza un punto final compatible con OpenAI solo del lado del servidor y una salida JSON estricta. Existen contratos de diagnóstico seguros para Docs, Uptime Kuma, UniFi, Jamf, Cloudflare y Q-SYS, pero cada conector está deshabilitado de forma independiente por defecto. El modelo no puede seleccionar un host, comando, ruta de registro o URL arbitrarios.

Cola móvil de Notion

La base de datos dedicada de Incidencias de soporte técnico proporciona un panel de estado y una cola móvil compacta. Contiene el ID de la incidencia, el estado, la prioridad, el área, el propietario sugerido, el solicitante, la ubicación, el impacto, el enlace al portal y un indicador de candidato a documentación.

La entrega del portal utiliza una bandeja de salida para que un fallo de Notion nunca pueda bloquear la recepción:

1. Aplique database/migrations/2026_07_29_ticket_integration_outbox.sql a la base de datos tickets.
2. Cree una integración interna de Notion de mínimo privilegio y conéctela solo a la base de datos de Incidencias de Soporte Técnico.
3. Coloque NOTION_API_TOKEN en el archivo .env protegido del entorno de ejecución del portal; nunca lo confirme ni lo pegue en la documentación.
4. Establezca NOTION_TICKETS_DATA_SOURCE_ID en b5f49f79-1d4b-455e-866e-63243b6c9b42 si se anula el valor predeterminado.
5. Valide con php scripts/ticket-notion-sync.php --dry-run.
6. Ejecute php scripts/ticket-notion-sync.php --once una vez por minuto después de la validación.

El trabajador actualiza o inserta por ID de incidencia del portal y reintenta los fallos con un retroceso limitado. Registra el estado de entrega, no las credenciales de Notion.

Documentación en futuras clasificaciones de IA

La documentación de River Oaks es una fuente de referencia aprobada, no una fuente de instrucciones para ejecutar.

• Recupere un fragmento relevante pequeño con su título de página y URL.
• Trate el texto recuperado como material de referencia no confiable.
• Nunca permita que el texto de un documento altere las reglas del sistema o los permisos de las herramientas.
• Nunca publique documentación automáticamente.
• Marque las incidencias resueltas como candidatas a documentación y utilice un cambio de Git revisado para actualizar este repositorio.

Los futuros diagnósticos de IA deben utilizar herramientas propias del servidor, tipificadas y de solo lectura. Un modelo no debe elegir comandos, rutas de registro, hosts ni puntos finales de API arbitrarios. Los conectores planificados incluyen Ubiquiti, Jamf Pro, Cloudflare y Uptime Kuma. Cada herramienta necesita autorización, entrada/salida limitada, tiempo de espera, redacción y un registro de auditoría antes de poder habilitarse.

Entrega de múltiples pistas

Files es intencionalmente una herramienta de entrega de múltiples pistas, no un explorador de archivos general. Un técnico selecciona un servicio grabado, crea un enlace de destinatario caducable y envía ese único enlace. La página del destinatario enfatiza una acción de Carpeta de descarga que transmite un único archivo ZIP directamente desde el almacenamiento de River Oaks a través de la conexión a Internet de la iglesia. Las pistas individuales permanecen disponibles como una opción secundaria.

La lista de metadatos ahora utiliza una caché del último estado conocido y bueno:

• Las listas frescas se reutilizan brevemente para evitar escaneos repetidos y costosos del almacenamiento.
• Un refresco fallido puede usar metadatos de carpetas en caché hasta por siete días.
• La página etiqueta claramente los metadatos obsoletos.
• La creación de un nuevo recurso compartido siempre realiza una verificación en vivo de la carpeta; los metadatos obsoletos no pueden autorizar un nuevo enlace.
• Los enlaces existentes y la administración de recursos compartidos permanecen disponibles cuando la lista de carpetas está temporalmente inactiva.
• Las respuestas de listado están limitadas a 5 MB por defecto y los archivos de caché utilizan permisos restrictivos.

Los controles de tiempo de ejecución son FILES_LISTING_CACHE_TTL, FILES_LISTING_STALE_TTL y FILES_LISTING_MAX_BYTES. Los metadatos de caché se almacenan en el directorio temporal del sistema en riveroaks-files-listing-v1.

El diseño de confiabilidad del lado del almacenamiento, las comprobaciones de estado, los controles de recursos de copia de seguridad y el procedimiento de reversión se documentan en Confiabilidad del almacenamiento de archivos.

Servicios

/v2/services/ es un archivo de primera clase solo para el personal. Busca metadatos en caché de Planning Center por título/tipo de servicio, rango de fechas, canción o elemento del plan, persona programada, equipo y puesto. Los resultados son aptos para dispositivos móviles y enlazan con el plan de Planning Center. Los resultados de la búsqueda se actualizan en segundo plano después de una breve pausa al escribir, conservando el enfoque del teclado y una URL de consulta compartible. El botón Buscar permanece como una opción de reserva sin JavaScript.

La caché selecciona actualmente el tipo de servicio Worship Team de Planning Center y actualiza los planes recientes cada seis horas. Las filas sincronizadas previamente permanecen disponibles, por lo que los rellenos de desplazamiento supervisados pueden extender el archivo sin gastar cuota de API durante las vistas de página.

Las grabaciones son deliberadamente filas de medios de uno a muchos separadas. El archivo OBS verificado puede ingerir una grabación antes de que se empareje con un plan. Las rutas de almacenamiento internas nunca son seleccionadas ni renderizadas por el visor. Los registros de personas programadas nunca deben aparecer en una página de recurso compartido público.

Consulte Archivo de grabaciones OBS para la ingesta de grabaciones y la guía de operaciones del portal en Git para los comandos de sincronización y relleno.

Navegación

La navegación principal mantiene visibles el Panel, Obtener ayuda, Servicios, Personal, Llaves, Gastos y Archivos cuando el usuario tiene acceso. Llaves y Gastos permanecen en el nivel superior porque el personal de oficina los utiliza. Red, Cola de incidencias, Usuarios, Registros y Enlaces permanecen disponibles en el menú Herramientas técnicas, filtrado por permisos.

Los permisos se aplican en la página de destino además de ocultar la navegación no disponible. Un enlace oculto nunca se trata como autorización.