# Fase 5: Analytics y Administración ## Estado: ✅ COMPLETADA ### ✅ Tareas completadas: #### 5.1.1: Dashboard Administrativo - [x] Vista general de ocupación del día/semana - [x] Accesos rápidos (crear reserva, bloquear cancha) - [x] Lista de reservas del día con filtros - [x] Gestión de usuarios (activar/desactivar) #### 5.1.2: Métricas de Ocupación - [x] % de ocupación por cancha - [x] Ocupación por franja horaria - [x] Comparativa mes a mes - [x] Días y horas más demandados (peak hours) #### 5.2.1: Métricas Financieras - [x] Ingresos por período (día, semana, mes, año) - [x] Ingresos por tipo (reservas, bonos, torneos, clases) - [x] Ingresos por cancha - [x] Comparativas y tendencias #### 5.2.2: Gestión de Reportes - [x] Reporte completo de ingresos - [x] Reporte de ocupación - [x] Reporte de usuarios - [x] Resumen ejecutivo #### 5.2.3: Métricas de Usuarios - [x] Total de usuarios activos - [x] Nuevos registros por período - [x] Jugadores más activos (top 10/50) - [x] Jugadores inactivos (alertas de churn) - [x] Retención y frecuencia de uso #### 5.2.4: Exportación de Datos - [x] Exportar reservas a Excel/CSV - [x] Exportar informes financieros - [x] Exportar base de usuarios - [x] Reportes automáticos por email (preparado para futura implementación) --- ## 📊 Módulos de Analytics ### 1. Dashboard Resumen ejecutivo para administradores: - Reservas hoy/semana/mes - Ingresos hoy/semana/mes - Usuarios nuevos - Ocupación promedio - Alertas del día ### 2. Ocupación Métricas de uso de canchas: - Ocupación por fecha/rango - Ocupación por cancha específica - Ocupación por franja horaria - Horas pico (top 5) - Comparativa entre períodos ### 3. Financiero Ingresos y métricas económicas: - Ingresos totales por período - Desglose por tipo (booking, tournament, subscription, class) - Ingresos por cancha - Métodos de pago más usados - Estadísticas de reembolsos - Tendencias de crecimiento ### 4. Usuarios Comportamiento de usuarios: - Estadísticas generales - Actividad por período - Top jugadores - Usuarios en riesgo de abandono (churn) - Tasa de retención - Crecimiento mensual ### 5. Exportación Exportar datos en múltiples formatos: - CSV (separado por ; para Excel español) - JSON - Excel (múltiples hojas) --- ## 🔌 Endpoints de Analytics ### Dashboard ``` GET /api/v1/analytics/dashboard/summary - Resumen ejecutivo GET /api/v1/analytics/dashboard/today - Vista del día GET /api/v1/analytics/dashboard/calendar - Calendario semanal ``` ### Ocupación ``` GET /api/v1/analytics/occupancy - Ocupación por fechas GET /api/v1/analytics/occupancy/by-court - Por cancha GET /api/v1/analytics/occupancy/by-timeslot - Por franja horaria GET /api/v1/analytics/occupancy/peak-hours - Horas pico GET /api/v1/analytics/occupancy/comparison - Comparativa períodos ``` ### Financiero ``` GET /api/v1/analytics/revenue - Ingresos GET /api/v1/analytics/revenue/by-court - Por cancha GET /api/v1/analytics/revenue/by-type - Por tipo GET /api/v1/analytics/payment-methods - Métodos de pago GET /api/v1/analytics/outstanding-payments - Pagos pendientes GET /api/v1/analytics/refunds - Reembolsos GET /api/v1/analytics/trends - Tendencias GET /api/v1/analytics/top-days - Mejores días ``` ### Reportes ``` GET /api/v1/analytics/reports/revenue - Reporte ingresos GET /api/v1/analytics/reports/occupancy - Reporte ocupación GET /api/v1/analytics/reports/users - Reporte usuarios GET /api/v1/analytics/reports/summary - Resumen ejecutivo ``` ### Usuarios ``` GET /api/v1/analytics/users/overview - Stats generales GET /api/v1/analytics/users/activity - Actividad GET /api/v1/analytics/users/top-players - Top jugadores GET /api/v1/analytics/users/churn-risk - Riesgo de abandono GET /api/v1/analytics/users/retention - Tasa de retención GET /api/v1/analytics/users/growth - Crecimiento ``` ### Exportación ``` GET /api/v1/analytics/exports/bookings - Exportar reservas GET /api/v1/analytics/exports/users - Exportar usuarios GET /api/v1/analytics/exports/payments - Exportar pagos GET /api/v1/analytics/exports/tournaments/:id - Exportar torneo GET /api/v1/analytics/exports/excel-report - Reporte Excel completo ``` --- ## 📁 Estructura de Archivos ``` backend/src/ ├── services/analytics/ │ ├── dashboard.service.ts # Dashboard ejecutivo │ ├── occupancy.service.ts # Métricas de ocupación │ ├── financial.service.ts # Métricas financieras │ ├── report.service.ts # Generación de reportes │ ├── userAnalytics.service.ts # Analytics de usuarios │ └── export.service.ts # Exportación de datos ├── controllers/analytics/ │ ├── dashboard.controller.ts │ ├── occupancy.controller.ts │ ├── financial.controller.ts │ ├── report.controller.ts │ ├── userAnalytics.controller.ts │ └── export.controller.ts ├── routes/ │ └── analytics.routes.ts # Todas las rutas de analytics ├── utils/ │ ├── analytics.ts # Utilidades de cálculo │ └── export.ts # Utilidades de exportación ├── types/ │ └── analytics.types.ts # Tipos TypeScript └── constants/ └── export.constants.ts # Constantes de exportación ``` --- ## 📊 Ejemplos de Uso ### Dashboard Summary ```bash curl http://localhost:3000/api/v1/analytics/dashboard/summary \ -H "Authorization: Bearer ADMIN_TOKEN" ``` Response: ```json { "today": { "bookings": 12, "revenue": 25000, "occupancyRate": 75.5 }, "week": { "newUsers": 5, "totalBookings": 89 } } ``` ### Ocupación por Fechas ```bash curl "http://localhost:3000/api/v1/analytics/occupancy?startDate=2024-01-01&endDate=2024-01-31" \ -H "Authorization: Bearer ADMIN_TOKEN" ``` ### Exportar a Excel ```bash curl "http://localhost:3000/api/v1/analytics/exports/excel-report?startDate=2024-01-01&endDate=2024-01-31" \ -H "Authorization: Bearer ADMIN_TOKEN" \ --output reporte_enero.xlsx ``` --- ## 🔐 Seguridad - Todos los endpoints de analytics requieren autenticación - Solo accesible para roles ADMIN y SUPERADMIN - Validación de fechas y parámetros con Zod --- ## 📦 Dependencias ```json { "xlsx": "^0.18.5" } ``` --- *Completada el: 2026-01-31*