Ivan Alcaraz
5e50dd766f
Implementados 5 módulos de analytics con agent swarm: 1. DASHBOARD ADMINISTRATIVO - Resumen ejecutivo (reservas, ingresos, usuarios) - Vista del día con alertas - Calendario semanal de ocupación 2. MÉTRICAS DE OCUPACIÓN - Ocupación por fecha, cancha, franja horaria - Horas pico (top 5 demandados) - Comparativa entre períodos - Tendencias de uso 3. MÉTRICAS FINANCIERAS - Ingresos por período, cancha, tipo - Métodos de pago más usados - Estadísticas de reembolsos - Tendencias de crecimiento - Top días de ingresos 4. MÉTRICAS DE USUARIOS - Stats generales y actividad - Top jugadores (por partidos/victorias/puntos) - Detección de churn (riesgo de abandono) - Tasa de retención - Crecimiento mensual 5. EXPORTACIÓN DE DATOS - Exportar a CSV (separado por ;) - Exportar a JSON - Exportar a Excel (múltiples hojas) - Reportes completos descargables Endpoints nuevos (solo admin): - /analytics/dashboard/* - /analytics/occupancy/* - /analytics/revenue/* - /analytics/reports/* - /analytics/users/* - /analytics/exports/* Dependencias: - xlsx - Generación de archivos Excel Utilidades: - Cálculo de crecimiento porcentual - Formateo de moneda - Agrupación por fechas - Relleno de fechas faltantes
137 lines
4.5 KiB
Markdown
137 lines
4.5 KiB
Markdown
# 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
|