app-padel/README_FASE_5.3.md

Fase 5.3 - Métricas de Usuarios y Exportación

📊 Resumen

Implementación del sistema completo de analytics y exportación de datos para la aplicación Padel.

📁 Estructura de Archivos

src/
├── constants/
│   ├── export.constants.ts      # Enum ExportFormat, ChurnRiskLevel
│   └── index.ts
├── controllers/
│   ├── analytics/
│   │   ├── export.controller.ts    # Controladores de exportación
│   │   ├── userAnalytics.controller.ts  # Controladores de métricas
│   │   └── index.ts
├── routes/
│   └── analytics.routes.ts      # Definición de rutas
├── services/
│   ├── analytics/
│   │   ├── export.service.ts    # Lógica de exportación
│   │   ├── userAnalytics.service.ts  # Lógica de métricas
│   │   └── index.ts
├── types/
│   ├── analytics.types.ts       # Interfaces y tipos
│   └── index.ts
└── utils/
    └── export.ts                # Utilidades de exportación

🚀 Endpoints

Analytics de Usuarios

Endpoint	Método	Descripción	Parámetros
/analytics/users/overview	GET	Stats generales de usuarios	-
/analytics/users/activity	GET	Actividad en período	startDate, endDate
/analytics/users/top-players	GET	Mejores jugadores	limit, by
/analytics/users/churn-risk	GET	Usuarios en riesgo	-
/analytics/users/retention	GET	Tasa de retención	startDate, endDate
/analytics/users/growth	GET	Tendencia de crecimiento	months

Exportación

Endpoint	Método	Descripción	Parámetros
/analytics/exports/bookings	GET	Exportar reservas	startDate, endDate, format
/analytics/exports/users	GET	Exportar usuarios	format, level, city
/analytics/exports/payments	GET	Exportar pagos	startDate, endDate, format
/analytics/exports/tournaments/:id	GET	Exportar torneo	id, format
/analytics/exports/excel-report	GET	Reporte Excel	startDate, endDate

📦 Instalación

npm install xlsx

🔧 Uso

Ejemplo: Obtener Overview de Usuarios

curl http://localhost:3000/analytics/users/overview \
  -H "Authorization: Bearer <token_admin>"

Ejemplo: Exportar Reservas a CSV

curl "http://localhost:3000/analytics/exports/bookings?startDate=2024-01-01&endDate=2024-01-31&format=csv" \
  -H "Authorization: Bearer <token_admin>" \
  --output reservas_enero.csv

Ejemplo: Reporte Excel Completo

curl "http://localhost:3000/analytics/exports/excel-report?startDate=2024-01-01&endDate=2024-01-31" \
  -H "Authorization: Bearer <token_admin>" \
  --output reporte_enero.xlsx

📋 Funcionalidades

Métricas de Usuarios

1. getUserStatsOverview()

   • Total de usuarios
   • Usuarios activos (30 días)
   • Nuevos usuarios (hoy/semana/mes)
   • Distribución por nivel
   • Distribución por ciudad

2. getUserActivityStats()

   • Usuarios con reservas en período
   • Promedio de reservas por usuario
   • Top 10 usuarios más activos
   • Usuarios sin actividad

3. getTopPlayers()

   • Ranking por partidos jugados
   • Ranking por victorias
   • Ranking por puntos
   • Ranking por torneos asistidos

4. getChurnRiskUsers()

   • Identifica usuarios sin reservar 60+ días
   • Calcula nivel de riesgo (LOW/MEDIUM/HIGH)
   • Muestra última fecha de reserva

5. getRetentionRate()

   • Tasa de retención mensual
   • Usuarios que siguen activos después de N días

6. getUserGrowthTrend()

   • Crecimiento de usuarios por mes
   • Tasa de crecimiento mes a mes

Exportación

1. exportBookings() - Exporta reservas con campos: id, usuario, pista, fecha, hora, precio, estado
2. exportUsers() - Exporta usuarios con campos: id, nombre, email, nivel, ciudad, reservas
3. exportPayments() - Exporta pagos con campos: id, usuario, tipo, monto, estado, fecha
4. exportTournamentResults() - Exporta resultados de torneo con estadísticas
5. generateExcelReport() - Reporte completo con 4 hojas: Resumen, Ingresos, Ocupación, Usuarios

🔒 Consideraciones

• Todos los endpoints requieren autenticación de administrador
• Formato de fechas: ISO 8601 (YYYY-MM-DD)
• CSV usa punto y coma (;) como separador (mejor para Excel español)
• Excel generado con librería xlsx