app-padel/docs/roadmap/FASE-05.md

Fase 5: Analytics y Administración

Estado: ✅ COMPLETADA

✅ Tareas completadas:

5.1.1: Dashboard Administrativo

• Vista general de ocupación del día/semana
• Accesos rápidos (crear reserva, bloquear cancha)
• Lista de reservas del día con filtros
• Gestión de usuarios (activar/desactivar)

5.1.2: Métricas de Ocupación

• % de ocupación por cancha
• Ocupación por franja horaria
• Comparativa mes a mes
• Días y horas más demandados (peak hours)

5.2.1: Métricas Financieras

• Ingresos por período (día, semana, mes, año)
• Ingresos por tipo (reservas, bonos, torneos, clases)
• Ingresos por cancha
• Comparativas y tendencias

5.2.2: Gestión de Reportes

• Reporte completo de ingresos
• Reporte de ocupación
• Reporte de usuarios
• Resumen ejecutivo

5.2.3: Métricas de Usuarios

• Total de usuarios activos
• Nuevos registros por período
• Jugadores más activos (top 10/50)
• Jugadores inactivos (alertas de churn)
• Retención y frecuencia de uso

5.2.4: Exportación de Datos

• Exportar reservas a Excel/CSV
• Exportar informes financieros
• Exportar base de usuarios
• 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

curl http://localhost:3000/api/v1/analytics/dashboard/summary \
  -H "Authorization: Bearer ADMIN_TOKEN"

Response:

{
  "today": {
    "bookings": 12,
    "revenue": 25000,
    "occupancyRate": 75.5
  },
  "week": {
    "newUsers": 5,
    "totalBookings": 89
  }
}

Ocupación por Fechas

curl "http://localhost:3000/api/v1/analytics/occupancy?startDate=2024-01-01&endDate=2024-01-31" \
  -H "Authorization: Bearer ADMIN_TOKEN"

Exportar a Excel

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

{
  "xlsx": "^0.18.5"
}

---

Completada el: 2026-01-31