Flujos de Trabajo

Este documento describe los flujos de trabajo principales del sistema UnoSportClub.

Flujo de Reserva por Cliente

El flujo completo de reserva realizado por un cliente incluye los siguientes pasos:

  1. Cliente accede al sitio web

  2. Cliente hace clic en "Reservar"

  3. Sistema muestra el asistente de reserva

  4. Cliente selecciona cantidad de canchas necesarias

  5. Sistema consulta disponibilidad

  6. Sistema muestra calendario semanal con disponibilidad

  7. Cliente selecciona fecha y hora

  8. Sistema verifica canchas disponibles para esa fecha/hora

  9. Cliente selecciona canchas específicas y define lapso de tiempo

  10. Sistema crea la reserva (estado: amarillo/pendiente)

  11. Sistema muestra datos de pago y campo para número de confirmación

  12. Cliente ingresa número de confirmación de pago

  13. Sistema conecta WebSocket para escuchar registro de pago

  14. Sistema compara número de referencia:

    • Si el pago fue registrado antes del número ingresado: alinea automáticamente

    • Si el número fue ingresado antes del pago: espera coincidencia

  15. Cuando hay coincidencia, sistema cambia estado de reserva a "comprada" (verde)

  16. Cliente llega a la cancha y solicita Check-in

  17. Operador registra la presencia del cliente

  18. Sistema confirma asistencia registrada

Ver diagrama de secuencia completo en Diagrama de Secuencia: Flujo de Reserva.

Flujo de Reserva por Operador

El flujo de reserva realizado por un operador es similar pero gestionado directamente:

  1. Operador accede al sistema

  2. Operador crea reserva para cliente

  3. Operador selecciona cantidad de canchas

  4. Sistema consulta disponibilidad

  5. Operador selecciona fecha, hora y canchas

  6. Operador define lapso de tiempo

  7. Sistema crea la reserva

  8. Operador registra el pago

  9. Sistema confirma pago

  10. Cuando el cliente llega, operador registra asistencia

  11. Sistema confirma asistencia registrada

Ver diagrama de secuencia completo en Diagrama de Secuencia: Flujo de Reserva (Operador).

Flujo de pago en reserva

Los pagos de reserva se registran en el paso Pago del wizard de reserva (/booking/payment/:id):

  1. El operador ingresa monto, tipo de pago y transaction_id, guarda con + y puede adjuntar la captura con el botón verde Subir (o integraciones vía POST/PATCH multipart).

  2. POST /admin/booking/{bookingId}/payment acepta JSON (foto = null) o multipart (foto obligatorio); PATCH …​/payment/{paymentId} en multipart añade o reemplaza comprobante. La API usa PaymentReceiptStorage (S3/R2 privado).

  3. El operador valida pagos pendientes ya vinculados desde Pagos → Pendientes (PATCH /admin/payments/:id con status: true).

  4. Ver abre el modal con GET …​/payment/{paymentId}/foto (Bearer + CSRF). Eliminar comprobante (modal) llama DELETE …​/payment/{paymentId}/foto (borra objeto en bucket y payment.foto = null). Eliminar pago (icono papelera en la fila) llama DELETE …​/payment/{paymentId}; si el pago tenía comprobante, también se elimina del bucket antes de borrar el registro.

No existe conciliación manual de pagos sin reserva ni inscripción desde el panel.

Referencia API: Comprobantes de pago. Diagramas: Subida y Visualización privada.

Flujo de creación de evento (operador)

Operador en panel (/events/new):

  1. Selección de slot en calendario (cancha + rango horario mural).

  2. Datos del evento: título, event_type_id, capacidad, descripción opcional.

  3. POST /admin/events → reserva pendiente tipo Evento + fila event.

  4. Asignación de participantes por casilla (POST /admin/events/{id}/participants) con boleto disponible del cliente.

  5. La reserva aparece en agenda (/booking) con event_id asociado.

Diagrama: Diagramas de Ingeniería (secuencia creación de evento).

Flujo de tickets (emisión panel)

  1. Operador abre /tickets (listado de ventas alineado con GET /admin/tickets/sales).

  2. Wizard de emisión: cotización (POST /admin/tickets/quote) y venta (POST /admin/tickets/sales).

  3. Boletos quedan available hasta usarse en un event_participant.

Ver xref:api-reference.adoc y xref:enrollment-payment-module.adoc.

Flujo de Disponibilidad

El sistema calcula la disponibilidad considerando:

  1. Consulta todas las reservas existentes para el rango de fechas

  2. Filtra por cancha y tipo de cancha si se especifica

  3. Calcula slots disponibles basándose en:

    • Horarios de operación de las canchas

    • Reservas existentes (ocupadas)

    • Cantidad de canchas requeridas vs disponibles

  4. Retorna slots disponibles marcados como disponibles/no disponibles

Un slot se marca como no disponible si: * Ya hay una reserva confirmada en ese horario * No hay suficientes canchas disponibles para la cantidad requerida

Flujo de Check-in

Cuando un cliente llega a la cancha:

  1. Cliente solicita Check-in (desde la aplicación o en persona)

  2. Sistema notifica al operador sobre la solicitud

  3. Operador verifica la identidad del cliente

  4. Operador registra la presencia del cliente

  5. Sistema actualiza RESERVATION.checking con la fecha/hora actual

  6. Sistema confirma el Check-in al cliente

Flujo de Check-out

Al finalizar el uso de la cancha:

  1. Cliente o operador solicita Check-out

  2. Sistema registra RESERVATION.checkout con la fecha/hora actual

  3. Sistema calcula tiempo de uso real vs tiempo reservado

  4. Sistema genera reporte si es necesario