Admin

Endpoints para tareas administrativas, reportes y configuración del sistema.

Modelos de Datos

Los endpoints de administración utilizan modelos de múltiples schemas para generar estadísticas y reportes. Los principales modelos consultados incluyen:

Schemas Utilizados

Schema	Modelos
auth	User, Account, UserRole
users	UserProfile, Membership
gym	Trainer, Class, ClassSchedule, Reservation, TrainingSession
fitness	WorkoutLog, Exercise
gamification	Goal, Streak, Achievement
social	Post, Comment, Like, Follow
payments	Payment
reviews	TrainerReview

Para ver los modelos completos, consulta la documentación de cada módulo correspondiente.

Endpoints

Obtener Estadísticas del Dashboard

Obtener estadísticas del dashboard con métricas completas sobre el gimnasio.

• URL: /api/v1/admin/dashboard
• Método: GET
• Autenticación Requerida: Sí Admin

Descripción Interna

Este endpoint calcula y retorna estadísticas completas del dashboard:

1. Cálculo de períodos: Determina el rango de fechas según el parámetro period (day, week, month, quarter, year) y calcula el período anterior para comparaciones de crecimiento.

2. Overview:

   • totalUsers: Conteo total de perfiles de usuario
   • activeMembers: Usuarios con membresía activa
   • totalRevenue: Suma de precios de membresías en el período
   • revenueGrowth: Porcentaje de crecimiento respecto al período anterior
   • activeClasses: Clases con isActive: true
   • totalReservations: Reservas creadas en el período
   • reservationGrowth: Crecimiento de reservas vs período anterior
   • averageAttendance: Porcentaje de reservas confirmadas sobre el total

3. Memberships:

   • Conteo por estado: ACTIVE, EXPIRED, SUSPENDED
   • expiringThisMonth: Membresías activas que expiran en los próximos 30 días
   • totalRevenue: Ingresos por membresías en el período

4. Classes:

   • totalClasses: Clases activas
   • totalSchedules: Horarios de clase activos
   • averageCapacity: Capacidad promedio de las clases
   • mostPopularClasses: Top 5 clases por número de reservas confirmadas

5. Trainers:

   • totalTrainers y activeTrainers
   • totalSessions: Sesiones de entrenamiento en el período
   • averageRating: Promedio de valoraciones visibles
   • topRatedTrainers: Top 5 entrenadores por rating promedio

6. Recent Activity:

   • recentReservations: Últimas 10 reservas con clase y usuario
   • recentMembers: Últimos 10 usuarios registrados

Parámetros de Consulta de Solicitud

• period: Período de tiempo (day, week, month, quarter, year)
• startDate: Fecha de inicio personalizada (opcional)
• endDate: Fecha de fin personalizada (opcional)

Ejemplo de Cliente Hono

import { hcWithType } from '@vitality-gym/api/client'

const client = hcWithType('http://localhost:3000')

const res = await client.api.v1.admin.dashboard.$get({
  query: {
    period: 'month'
  }
})

---

Obtener Usuarios

Obtener todos los usuarios con filtrado y paginación.

• URL: /api/v1/admin/users
• Método: GET
• Autenticación Requerida: Sí Admin

Descripción Interna

Este endpoint obtiene usuarios con filtros avanzados:

1. Construye filtros dinámicos:

   • role: Filtra por rol (MEMBER, TRAINER, ADMIN, STAFF)
   • membershipStatus: Filtra por estado de membresía
   • createdFrom/createdTo: Rango de fechas de creación
   • search: Búsqueda por nombre o email (case-insensitive)

2. Consulta paginada que incluye:

   • Información del usuario (id, email, emailVerified)
   • Membresía (id, type, status, startDate, endDate)
   • Contadores de reservas y sesiones de entrenamiento

3. Retorna lista paginada con datos completos del perfil

Parámetros de Consulta de Solicitud

• role: Filtrar por rol (MEMBER, TRAINER, ADMIN, STAFF)
• search: Buscar por nombre/email
• membershipStatus: Filtrar por status de membresía
• page: Número de página (por defecto: 1)
• limit: Resultados por página (por defecto: 10)

Ejemplo de Cliente Hono

import { hcWithType } from '@vitality-gym/api/client'

const client = hcWithType('http://localhost:3000')

const res = await client.api.v1.admin.users.$get({
  query: {
    role: 'MEMBER'
  }
})

---

Obtener Usuario por ID

Obtener información detallada de un usuario específico.

• URL: /api/v1/admin/users/:id
• Método: GET
• Autenticación Requerida: Sí Admin

Descripción Interna

Este endpoint obtiene el perfil completo de un usuario específico:

1. Busca el UserProfile por ID
2. Incluye relaciones extensas:
   • Información del User (id, email, emailVerified, timestamps)
   • Membresía completa
   • Perfil de entrenador con contadores (sesiones, reviews)
   • Últimas 10 reservas con información de clase
   • Últimas 10 sesiones de entrenamiento con info del trainer
   • Contadores totales (reservas, sesiones, posts, comentarios)

Ejemplo de Cliente Hono

import { hcWithType } from '@vitality-gym/api/client'

const client = hcWithType('http://localhost:3000')

const res = await client.api.v1.admin.users[':id'].$get({
  param: { id: 'user_profile_id' }
})

---

Actualizar Rol de Usuario

Actualizar el rol de un usuario.

• URL: /api/v1/admin/users/:id/role
• Método: PATCH
• Autenticación Requerida: Sí Admin

Descripción Interna

Este endpoint actualiza el rol de un usuario:

1. Verifica que el usuario existe
2. Validación especial para TRAINER:
   • Si el nuevo rol es TRAINER, verifica que exista un perfil de entrenador (Trainer) asociado
   • Si no existe el perfil de trainer, lanza error 400
3. Actualiza el rol en UserProfile
4. Retorna el perfil actualizado con info básica del usuario

Errores Comunes

• 400 Bad Request: El usuario debe tener un perfil de entrenador para asignar rol TRAINER

Cuerpo de Solicitud

{
  "role": "TRAINER"
}

Ejemplo de Cliente Hono

import { hcWithType } from '@vitality-gym/api/client'

const client = hcWithType('http://localhost:3000')

const res = await client.api.v1.admin.users[':id'].role.$patch({
  param: { id: 'user_id' },
  json: {
    role: 'TRAINER'
  }
})

---

Eliminar Usuario

Eliminar un usuario del sistema.

• URL: /api/v1/admin/users/:id
• Método: DELETE
• Autenticación Requerida: Sí Admin

Descripción Interna

Este endpoint elimina un usuario del sistema:

1. Verifica reservas futuras: Cuenta reservas CONFIRMED con fecha futura
2. Bloquea eliminación si tiene reservas confirmadas pendientes
3. Obtiene el UserProfile con el User asociado
4. Elimina el User (esto elimina en cascada el UserProfile por la relación)
5. Retorna confirmación de eliminación

Errores Comunes

• 400 Bad Request: No se puede eliminar porque tiene reservas confirmadas futuras

Ejemplo de Cliente Hono

import { hcWithType } from '@vitality-gym/api/client'

const client = hcWithType('http://localhost:3000')

const res = await client.api.v1.admin.users[':id'].$delete({
  param: { id: 'user_id' }
})

---

Obtener Reporte de Ingresos

Obtener reporte de ingresos para un período específico.

• URL: /api/v1/admin/reports/revenue
• Método: GET
• Autenticación Requerida: Sí Admin

Descripción Interna

Este endpoint genera un reporte de ingresos:

Nota: Este endpoint tiene implementación parcial (TODO en el código)

1. Parámetros de período: Acepta startDate, endDate y period
2. Retorna estructura base:
   • period: Período del reporte
   • total: Total de ingresos (TODO: calcular)
   • growth: Crecimiento (TODO: calcular)
   • bySource: Ingresos por fuente (membresías, sesiones) (TODO)
   • byPeriod: Desglose temporal (TODO)

Parámetros de Consulta de Solicitud

• startDate: Fecha de inicio (YYYY-MM-DD)
• endDate: Fecha de fin (YYYY-MM-DD)
• period: Período de agrupación (day, week, month)

Ejemplo de Cliente Hono

import { hcWithType } from '@vitality-gym/api/client'

const client = hcWithType('http://localhost:3000')

const res = await client.api.v1.admin.reports.revenue.$get({
  query: {
    startDate: '2023-01-01',
    endDate: '2023-12-31'
  }
})

---

Obtener Configuración del Sistema

Obtener todas las configuraciones del sistema.

• URL: /api/v1/admin/system/config
• Método: GET
• Autenticación Requerida: Sí Admin

Descripción Interna

Este endpoint obtiene las configuraciones del sistema:

Nota: Este endpoint no está completamente implementado (TODO: modelo SystemConfig)

Actualmente retorna un array vacío. Cuando se implemente el modelo SystemConfig, retornará todas las configuraciones del sistema.

Ejemplo de Cliente Hono

import { hcWithType } from '@vitality-gym/api/client'

const client = hcWithType('http://localhost:3000')

const res = await client.api.v1.admin.system.config.$get()

---

Obtener Estado del Sistema

Obtener métricas de estado del sistema.

• URL: /api/v1/admin/system/health
• Método: GET
• Autenticación Requerida: Sí Admin

Descripción Interna

Este endpoint verifica el estado de salud del sistema:

1. Database Health (si includeDatabase: true):

   • Ejecuta SELECT 1 para probar conexión
   • Mide tiempo de respuesta
   • Cuenta registros totales de usuarios
   • Estado: “connected” o “disconnected”

2. Memory Usage:

   • used: Memoria heap usada
   • total: Memoria heap total
   • percentage: Porcentaje de uso

3. Overall Status:

   • “healthy”: DB conectada y memoria < 90%
   • “degraded”: DB conectada pero memoria > 90%
   • “unhealthy”: DB desconectada

4. Uptime: Tiempo de ejecución del proceso

Parámetros de Consulta de Solicitud

• includeDatabase: Incluir verificación de estado de la base de datos (por defecto: true)

Ejemplo de Cliente Hono

import { hcWithType } from '@vitality-gym/api/client'

const client = hcWithType('http://localhost:3000')

const res = await client.api.v1.admin.system.health.$get({
  query: {
    includeDatabase: 'true'
  }
})