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

Nota: Puesto que el módulo admin no posee tablas propias y en su lugar recopila métricas operando sobre las entidades de todo el sistema (como UserProfile, Membership, Trainer, Reservation, etc.), no se incluye un extracto específico del esquema de Prisma aquí. Para ver los modelos de datos exactos, por favor consulta la documentación de sus respectivos módulos.

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'
  }
})

---

Activar Membresía Manualmente

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

Descripción Interna

Este endpoint permite al administrador activar la membresía de un usuario de forma manual, útil para gestionar pagos en efectivo o excepciones.

Cuerpo de Solicitud

{
  "type": "MONTHLY",
  "duration": 30,
  "price": 100,
  "paymentMethod": "CASH"
}

Respuesta

{
  "message": "Membresía activada exitosamente",
  "data": {
    "id": "cm...",
    "status": "ACTIVE",
    "startDate": "2023-10-27T00:00:00Z",
    "endDate": "2023-11-26T00:00:00Z"
  }
}

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'].membership.activate.$post({
  param: { id: 'user_id' },
  json: {
    type: 'MONTHLY',
    duration: 30,
    price: 100,
    paymentMethod: 'CASH'
  }
})

---

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 Estadísticas de Reportes

Obtener estadísticas de reportes para un período específico.

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

Descripción Interna

Este endpoint genera un reporte. Retorna los datos solicitados según los filtros especificados.

Parámetros de Consulta de Solicitud

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

Respuesta

{
  "message": "Reportes obtenidos exitosamente",
  "data": {
    "period": "month",
    "total": 15000,
    "growth": 5.2,
    "bySource": [],
    "byPeriod": []
  }
}

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.$get({
  query: {
    startDate: '2023-01-01',
    endDate: '2023-12-31'
  }
})