Manual del Administrador

Este manual describe el uso del Panel de Administración de UnoSportClub, pensado para usuarios con rol de administrador (admin).

Introducción

Bienvenido al manual del administrador. Este documento cubre todas las funcionalidades administrativas del sistema UnoSportClub.

Como administrador, tienes acceso a funciones de gestión de nivel medio que te permiten mantener la operación del negocio sin necesidad de acceso de super usuario. Tus responsabilidades incluyen:

  • Gestionar la información de clientes

  • Configurar y mantener las canchas deportivas

  • Definir y actualizar tarifas y precios

  • Revisar y monitorear los pagos del sistema

  • Supervisar la operación general del club

Acceso al Panel

El panel de administración es parte de la aplicación principal. Para acceder:

  1. Inicia sesión en la aplicación principal con tus credenciales

  2. Asegúrate de tener el rol de admin asignado

  3. Las opciones administrativas estarán disponibles en el menú

Si no tienes acceso, contacta a un super usuario para que te asigne el rol correspondiente.

Funcionalidades Principales

El panel de administración está organizado en las siguientes secciones:

  • Clientes: Gestión completa de la información de clientes

  • Canchas: Configuración y mantenimiento de canchas deportivas

  • Tarifas: Definición y gestión de precios y tarifas

  • Pagos: Revisión y monitoreo de todos los pagos del sistema

Cada sección se detalla en las siguientes páginas.

Gestión de Clientes

Administración completa del módulo de clientes. Los clientes se obtienen de la tabla client complementada con información de la tabla user.

Ver Lista de Clientes

La lista de clientes muestra todos los usuarios registrados como clientes en el sistema con información relevante:

  • ID del cliente

  • Email (desde tabla user)

  • Nombre para mostrar (display_name desde tabla user)

  • Tipo de cliente

  • Estado de verificación de email

  • ID de usuario (OAuth2 local IdP)

Crear Cliente

Para crear un nuevo cliente:

  1. Accede a la sección "Clientes"

  2. Haz clic en "Nuevo Cliente"

  3. Completa el formulario con los datos requeridos:

    • Identificador IdP (local_id): opcional si proporcionas email

    • Email: Dirección de correo electrónico del usuario (opcional si proporcionas User ID)

    • Tipo de Cliente: Selecciona el tipo de cliente

  4. Guarda los cambios

Usuarios existentes en el IdP

El sistema maneja automáticamente usuarios que ya existen en OAuth2 local:

  • Si proporcionas un email: verifica si el usuario existe en el IdP

  • Si existe: busca user_id en PostgreSQL por local_id

  • Si no existe en BD: crea o vincula el registro user

  • Si no existe en IdP: crea usuario en OAuth2 local con el email indicado

Nota: puedes indicar email o local_id del IdP; no uses terminología de proveedores externos.

Editar Cliente

Los datos de los clientes pueden ser actualizados desde el panel de administración:

  1. Selecciona el cliente a editar

  2. Haz clic en "Editar"

  3. Modifica el tipo de cliente (el user_id no se puede modificar)

  4. Guarda los cambios

Eliminar Cliente

Los clientes pueden ser eliminados siguiendo las políticas de retención de datos:

  1. Selecciona el cliente

  2. Haz clic en "Eliminar"

  3. Confirma la eliminación

La eliminación borra la fila del usuario en la tabla user (rol client).

No se elimina la cuenta en OAuth2 local IdP si existe allí; solo el registro en PostgreSQL.

Cuándo no se puede eliminar (409)

El sistema rechaza la eliminación si el cliente tiene dependencias bloqueantes:

  • Reservas asociadas como cliente (reservation.client_id)

  • Reservas donde figura como operador (reservation.operator_id)

  • Sesiones de caja como cajero (till.cashier_id)

  • Inscripciones con pagos registrados

En esos casos el panel muestra un toast con el motivo concreto (mensaje del API con viñetas cuando hay varios bloqueos). Debes resolver las dependencias antes de volver a intentar.

Búsqueda y Filtros

Utiliza las herramientas de búsqueda para encontrar clientes:

  • Por email (búsqueda en tabla user)

  • Por nombre para mostrar (display_name)

  • Por tipo de cliente

Paginación

La lista de clientes incluye paginación con 50 registros por página. Puedes navegar entre páginas usando los controles de paginación en la parte inferior de la lista.

Gestión de Tipos de Cliente

Los tipos de cliente definen categorías especiales:

  • Cliente Regular: Cliente estándar sin beneficios especiales

  • Cliente VIP: Cliente con beneficios y prioridades especiales

  • Cliente Corporativo: Cliente empresarial con tarifas especiales

  • Cliente Promocional: Cliente con descuentos o promociones activas

Asignar Tipo de Cliente

Para asignar o cambiar el tipo de cliente:

  1. Selecciona el cliente

  2. Haz clic en "Editar"

  3. Selecciona el nuevo tipo de cliente

  4. Guarda los cambios

El tipo de cliente puede afectar las tarifas aplicadas y los beneficios disponibles.

Verificación de Datos

Verificar Información del Cliente

Es importante mantener la información de clientes actualizada:

  • Email verificado: Indica si el cliente ha confirmado su email

  • Datos completos: Verifica que toda la información esté completa

  • Contacto actualizado: Confirma que los datos de contacto sean correctos

Actualizar Información desde User

La información básica del cliente (nombre, email) proviene de la tabla user. Si necesitas actualizar esta información:

  1. El cliente debe actualizar su perfil desde la aplicación

  2. O un super usuario puede actualizar la información en la tabla user

  3. Los cambios se reflejarán automáticamente en la vista de clientes

Mejores Prácticas

  • Mantén datos actualizados: Revisa regularmente la información de clientes

  • Verifica tipos de cliente: Asegúrate de que los tipos estén correctamente asignados

  • Documenta cambios: Toma notas sobre cambios importantes en la información de clientes

  • Respeta privacidad: Maneja la información de clientes con confidencialidad

  • Coordina con operadores: Comunica cambios relevantes al equipo operativo

Solución de Problemas

Cliente No Aparece en la Lista

Si un cliente no aparece:

  • Verifica que el cliente esté registrado en OAuth2 local IdP

  • Confirma que exista un registro en la tabla user

  • Verifica los filtros aplicados

  • Contacta al super usuario si el problema persiste

Error al Crear Cliente

Si hay error al crear un cliente:

  • Código 400 (Bad Request): Solicitud mal formada

  • Verifica que el user_id sea un número válido (si se proporciona)

  • Verifica que el formato del email sea correcto

  • Asegúrate de proporcionar user_id o email (al menos uno es requerido)

  • Verifica que el usuario exista en la base de datos si proporcionas user_id

  • Código 409 (Conflict): Conflicto de recursos

  • "El email ya está en uso" - El email ya está registrado en OAuth2 local IdP

  • "El teléfono ya está en uso" - El teléfono ya está registrado en el sistema

  • "El usuario ya es cliente" - El usuario ya tiene un registro de cliente activo

  • "El usuario no puede convertirse en cliente" - El usuario tiene roles que impiden ser cliente

  • Otros errores:

  • Verifica que el local_id del IdP sea correcto (si se proporciona)

  • Confirma que el usuario exista en OAuth2 local IdP (si se proporciona email)

  • Asegúrate de que no haya un cliente duplicado

  • Revisa que todos los campos requeridos estén completos

Códigos de Estado HTTP

El sistema utiliza códigos de estado HTTP estándar para indicar el resultado de las operaciones:

  • 200 OK: Operación exitosa

  • 400 Bad Request: Solicitud mal formada (datos inválidos, formato incorrecto)

  • 409 Conflict: Conflicto de recursos (email/teléfono en uso, usuario ya es cliente)

  • 404 Not Found: Recurso no encontrado

  • 500 Internal Server Error: Error interno del servidor

Los códigos 409 se utilizan específicamente para conflictos de recursos, mientras que 400 se usa para solicitudes mal formadas.

Gestión de Canchas

Administración de las canchas deportivas del club.

Lista de Canchas

La lista muestra todas las canchas registradas con su información:

  • Nombre

  • Tipo

  • Deporte

  • Capacidad

  • Estado actual

Crear Cancha

Los administradores pueden agregar nuevas canchas al sistema:

  1. Accede a "Canchas" > "Nueva Cancha"

  2. Completa el formulario:

    • Nombre de la cancha

    • Tipo (indoor/outdoor)

    • Deporte principal

    • Capacidad máxima

    • Estado inicial

  3. Guarda la cancha

Configurar Canchas

Cada cancha puede ser configurada con sus características específicas:

Información General

  • Nombre descriptivo

  • Descripción detallada

  • Ubicación dentro del club

  • Horarios de disponibilidad

Características Físicas

  • Dimensiones

  • Tipo de superficie

  • Iluminación

  • Vestuarios disponibles

Disponibilidad

  • Horarios de apertura

  • Días de la semana disponibles

  • Temporadas especiales

  • Restricciones

Editar Cancha

Para modificar una cancha existente:

  1. Selecciona la cancha

  2. Haz clic en "Editar"

  3. Modifica los campos necesarios

  4. Guarda los cambios

Eliminar Cancha

Las canchas pueden ser eliminadas del sistema si ya no están en uso:

  1. Selecciona la cancha

  2. Verifica que no tenga reservas activas

  3. Confirma la eliminación

Mantenimiento

Gestiona el mantenimiento de las canchas:

  • Programar mantenimiento preventivo: Planifica mantenimientos regulares

  • Registrar reparaciones: Documenta reparaciones realizadas

  • Historial de mantenimientos: Revisa el historial completo de cada cancha

  • Costos asociados: Registra y rastrea los costos de mantenimiento

Programar Mantenimiento Preventivo

Para programar mantenimiento preventivo:

  1. Selecciona la cancha

  2. Ve a "Mantenimiento" > "Programar"

  3. Define la fecha y hora

  4. Describe el tipo de mantenimiento

  5. Estima la duración

  6. El sistema bloqueará automáticamente las reservas durante ese período

Registrar Reparación

Para registrar una reparación:

  1. Selecciona la cancha

  2. Ve a "Mantenimiento" > "Registrar Reparación"

  3. Describe el problema

  4. Registra la solución aplicada

  5. Ingresa los costos asociados

  6. Marca la fecha de inicio y fin de la reparación

Historial de Mantenimientos

El historial muestra:

  • Fechas de mantenimientos

  • Tipos de mantenimiento realizados

  • Costos acumulados

  • Frecuencia de mantenimientos

  • Problemas recurrentes

Usa esta información para planificar mantenimientos futuros y presupuestos.

Análisis de Uso

Estadísticas de Canchas

Puedes analizar el uso de cada cancha:

  • Horas utilizadas: Total de horas reservadas

  • Tasa de ocupación: Porcentaje de tiempo ocupado

  • Horarios pico: Horarios más demandados

  • Temporadas: Análisis por temporada o mes

Optimización

Usa los datos de uso para:

  • Optimizar horarios de disponibilidad

  • Planificar mantenimientos en horarios de baja demanda

  • Ajustar tarifas según popularidad

  • Identificar canchas que requieren mejoras

Mejores Prácticas

  • Mantenimiento regular: Programa mantenimientos preventivos regularmente

  • Documenta todo: Mantén registros detallados de todos los mantenimientos

  • Analiza datos: Usa las estadísticas para tomar decisiones informadas

  • Coordina con operadores: Trabaja con el equipo operativo para minimizar interrupciones

  • Presupuesta adecuadamente: Usa el historial de costos para planificar presupuestos

Gestión de Tarifas

Configuración de precios y tarifas para las reservas.

Ver Tarifas

La lista de tarifas muestra todas las configuraciones de precios:

  • Nombre de la tarifa

  • Cancha asociada

  • Horario

  • Tipo de día

  • Precio

  • Estado

Crear Tarifa

Para crear una nueva tarifa:

  1. Accede a "Tarifas" > "Nueva Tarifa"

  2. Completa el formulario:

    • Nombre descriptivo

    • Cancha asociada

    • Horario (mañana/tarde/noche)

    • Tipo de día (entre semana/fin de semana/festivo)

    • Precio

    • Duración

    • Estado (activa/inactiva)

  3. Guarda la tarifa

Configurar Tarifas

Las tarifas pueden ser configuradas según diferentes criterios:

Por Horario

  • Tarifa matutina (6:00 - 12:00)

  • Tarifa vespertina (12:00 - 18:00)

  • Tarifa nocturna (18:00 - 24:00)

Por Tipo de Día

  • Entre semana

  • Fin de semana

  • Días festivos

Por Temporada

  • Temporada alta

  • Temporada baja

  • Temporada especial

Aplicar Descuentos

Los administradores pueden aplicar descuentos especiales:

Descuentos Automáticos

  • Descuento por volumen

  • Descuento por fidelidad

  • Descuento para grupos

Descuentos Manuales

  • Cupones promocionales

  • Descuentos por cliente

  • Descuentos temporales

Editar Tarifa

Para modificar una tarifa existente:

  1. Selecciona la tarifa

  2. Haz clic en "Editar"

  3. Modifica los campos necesarios

  4. Guarda los cambios

Activar/Desactivar Tarifas

Puedes activar o desactivar tarifas sin eliminarlas:

  • Tarifas activas: Se aplican automáticamente a las reservas

  • Tarifas inactivas: No se ofrecen pero se mantienen para referencia histórica

Proceso de Activación/Desactivación

Para cambiar el estado de una tarifa:

  1. Selecciona la tarifa

  2. Haz clic en "Editar"

  3. Cambia el estado (activa/inactiva)

  4. Guarda los cambios

Las tarifas inactivas no se aplicarán a nuevas reservas, pero las reservas existentes mantendrán su tarifa original.

Estrategias de Precios

Precios Dinámicos

Considera implementar precios dinámicos basados en:

  • Demanda: Aumentar precios en horarios de alta demanda

  • Temporada: Ajustar precios según temporada alta/baja

  • Disponibilidad: Ofrecer descuentos en horarios de baja ocupación

  • Eventos especiales: Tarifas especiales para eventos

Promociones

Puedes crear promociones temporales:

  • Descuentos por tiempo limitado: Ofrecer descuentos por períodos específicos

  • Paquetes: Crear paquetes de múltiples reservas con descuento

  • Promociones de lanzamiento: Tarifas especiales para nuevos clientes

Análisis de Tarifas

Revisar Efectividad

Analiza el impacto de tus tarifas:

  • Compara ingresos: Compara ingresos antes y después de cambios de tarifa

  • Tasa de ocupación: Verifica si los cambios afectan la ocupación

  • Feedback de clientes: Considera las opiniones de los clientes

  • Competencia: Compara con tarifas de la competencia

Optimización Continua

Mejora continuamente tus tarifas:

  • Revisa regularmente las tarifas

  • Ajusta según datos de uso

  • Experimenta con diferentes estrategias

  • Mide el impacto de los cambios

Mejores Prácticas

  • Documenta cambios: Registra todos los cambios de tarifa y sus razones

  • Comunica cambios: Informa a los clientes sobre cambios importantes de tarifa

  • Prueba gradualmente: Implementa cambios de tarifa de forma gradual

  • Monitorea resultados: Revisa regularmente el impacto de las tarifas

  • Mantén flexibilidad: Ten tarifas que se puedan ajustar según necesidades

Gestión de Pagos

Administración y seguimiento de todos los pagos del sistema. Los pagos son de solo lectura y no se pueden crear, editar o eliminar desde el panel.

Ver Pagos

La vista de pagos está organizada en dos pestañas:

Pagos Procesados

Muestra los pagos con status = true (completados/validados).

Pagos Pendientes

Muestra los pagos con status = false que ya están vinculados a una reserva (reservation_id) o a una inscripción de evento (enrollment_id). Desde esta pestaña el operador puede validar el pago (marcarlo como completado).

La captura del comprobante y la vinculación con la reserva ocurren durante el flujo de reserva; no hay pestaña de conciliación manual de pagos sin afiliar.

Comprobante en el paso de pago de reserva

En Reservas → Pago (/booking/payment/:id), cada fila de pago muestra acciones según el estado del comprobante:

  • Subir (botón verde): adjunta captura vía PATCH multipart cuando aún no hay comprobante.

  • Ver (icono ojo): abre modal Comprobante de pago (GET …​/foto; no expone URL del bucket).

  • Eliminar comprobante (rojo en el modal): DELETE …​/foto (borra objeto en S3/R2 y limpia payment.foto).

  • Eliminar pago (papelera en la fila): DELETE …​/payment/{paymentId} (borra el pago; si tenía comprobante, también lo elimina del bucket).

También puede adjuntarse al crear el pago (POST multipart) desde integraciones o scripts.

  • La vista global de pagos (/payments) no incluye este visor.

  • En reservas confirmadas puede Ver comprobantes, pero no añadir, editar ni eliminar pagos ni comprobantes.

Guía operador: Pago y comprobante. Referencia técnica: API comprobantes.

Información Mostrada

La lista de pagos muestra:

  • ID del pago

  • Transaction ID: ID de transacción del gateway de pago

  • Reservación/Inscripción: enlace a la reserva o identificador del evento

  • Tipo de pago

  • Monto: Cantidad del pago en formato COP

  • Estado: Estado actual del pago

  • Fecha: Fecha y hora del pago

Filtros y Búsqueda

Utiliza los filtros para encontrar pagos específicos:

  • Por transaction_id o descripción (búsqueda de texto)

  • Por tipo de pago

Estados de Pago

Los pagos utilizan un booleano status:

  • false: Pendiente de validación

  • true: Completado

Estadísticas

El dashboard muestra estadísticas generales de pagos:

  • Total de pagos

  • Monto total de todos los pagos

  • Monto de pagos completados

  • Desglose por estado (completados, pendientes, fallidos)

Paginación

La lista de pagos incluye paginación estándar del panel (selector de registros por página y navegación Primera/Anterior/Siguiente/Última).

Mejores Prácticas

  • Revisa regularmente: Revisa los pagos pendientes para validarlos a tiempo

  • Monitorea métricas: Usa el resumen financiero para identificar tendencias

  • Coordinar con finanzas y con contabilidad NIIF cuando el cierre de caja requiere período abierto

Pagos de tickets y caja

  • Ventas de paquetes de boletos se registran en Tickets del panel (/tickets); no siempre crean fila en esta vista de pagos de reservas

  • Los cierres de caja (/till) generan asientos en contabilidad solo con período contable vigente

Flujo de Trabajo Administrativo

Gestión Diaria

Tareas administrativas diarias típicas:

  1. Revisar nuevos registros de clientes

  2. Actualizar información de clientes según sea necesario

  3. Verificar el estado de las canchas

  4. Revisar pagos pendientes o problemas de pago

  5. Responder a consultas de operadores o usuarios

Gestión Semanal

Tareas administrativas semanales:

  1. Revisar reportes de uso de canchas

  2. Analizar tendencias de reservas

  3. Ajustar tarifas según demanda

  4. Revisar y actualizar información de canchas

  5. Coordinar con operadores sobre mejoras operativas

Gestión Mensual

Tareas administrativas mensuales:

  1. Generar reportes mensuales completos

  2. Analizar ingresos y pagos

  3. Revisar y optimizar tarifas

  4. Planificar mantenimientos de canchas

  5. Evaluar la satisfacción de clientes

Mejores Prácticas

Gestión de Clientes

  • Mantén la información de clientes actualizada

  • Responde a solicitudes de clientes de manera oportuna

  • Protege la privacidad de los datos de clientes

  • Documenta cualquier interacción importante

Configuración de Canchas

  • Mantén información precisa sobre cada cancha

  • Actualiza el estado de mantenimiento regularmente

  • Documenta características y restricciones

  • Coordina con operadores sobre cambios

Gestión de Tarifas

  • Revisa las tarifas regularmente

  • Ajusta precios según demanda y temporada

  • Documenta cambios de tarifas

  • Comunica cambios importantes a los usuarios

Monitoreo de Pagos

  • Revisa pagos pendientes regularmente

  • Identifica y resuelve problemas de pago

  • Mantén registros claros de transacciones

  • Coordina con el equipo financiero según sea necesario

Solución de Problemas Comunes

Cliente No Puede Reservar

Si un cliente reporta problemas para hacer reservas:

  1. Verifica que el cliente esté correctamente registrado

  2. Confirma que el cliente tenga el estado adecuado

  3. Revisa si hay restricciones en su cuenta

  4. Verifica la disponibilidad de canchas

Problema con Pago

Si hay un problema con un pago:

  1. Revisa el estado del pago en la sección de pagos

  2. Verifica la información de la transacción

  3. Contacta al cliente si es necesario

  4. Documenta el problema y la solución

Cancha Requiere Mantenimiento

Si una cancha requiere mantenimiento:

  1. Actualiza el estado de la cancha

  2. Notifica a los operadores

  3. Cancela o reasigna reservas afectadas

  4. Coordina con el equipo de mantenimiento

Recursos Adicionales

Para más información, consulta:

Soporte

Si necesitas ayuda adicional:

  • Contacta a un super usuario para temas de configuración avanzada

  • Revisa los logs del sistema para diagnosticar problemas

  • Consulta la documentación técnica si tienes acceso