# 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

```bash
npm install xlsx
```

## 🔧 Uso

### Ejemplo: Obtener Overview de Usuarios

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

### Ejemplo: Exportar Reservas a CSV

```bash
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

```bash
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