✅ FASE 5 COMPLETADA: Analytics y Administración
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
This commit is contained in:
@@ -1,6 +1,236 @@
|
||||
# Fase 5: Analytics
|
||||
# Fase 5: Analytics y Administración
|
||||
|
||||
## Estado: ⏳ Pendiente
|
||||
## Estado: ✅ COMPLETADA
|
||||
|
||||
*Esta fase comenzará al finalizar la Fase 4*
|
||||
### ✅ 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*
|
||||
|
||||
Reference in New Issue
Block a user