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
237 lines
6.4 KiB
Markdown
237 lines
6.4 KiB
Markdown
# 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*
|