Nivel & XP

Endpoints para gestionar puntos de experiencia y niveles de usuario.

Modelos de Datos

La información de nivel y XP se almacena en el modelo UserProfile del schema users:

Campos de Gamificación en UserProfile

model UserProfile {
  // ... otros campos

  // Sistema de gamificación
  totalXp        Int @default(0) @map("total_xp")
  level          Int @default(1)
  currentLevelXp Int @default(0) @map("current_level_xp")

  // ... relaciones
  @@map("user_profiles")
  @@schema("users")
}

Sistema de XP y Niveles

La gamificación utiliza un sistema de experiencia (XP) exponencial donde cada nivel requiere más XP que el anterior. La tabla de XP va del nivel 1 al 30, con niveles superiores requiriendo 2500 XP fijos por nivel.

Endpoints

Obtener Nivel de Usuario

Obtener información del nivel del usuario actual.

• URL: /api/v1/gamification/level/me
• Método: GET
• Autenticación Requerida: Sí

Descripción Interna

Este endpoint obtiene información del nivel del usuario:

1. Obtiene datos del perfil:

   • totalXp, level, currentLevelXp, avatar_url, name

2. Calcula información adicional:

   • xpForNextLevel: XP necesario para el siguiente nivel
   • progressPercentage: Porcentaje de progreso al siguiente nivel

3. Sistema de niveles:

   • Niveles 1-30 tienen XP predefinidos (exponencial)
   • Niveles 30+ requieren 2500 XP cada uno

Respuesta

{
  "data": {
    "id": "...",
    "name": "John Doe",
    "totalXp": 1500,
    "level": 5,
    "currentLevelXp": 350,
    "xpForNextLevel": 500,
    "progressPercentage": 70,
    "avatar_url": "..."
  }
}

Ejemplo de Cliente Hono

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

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

const res = await client.api.v1.gamification.level.me.$get()

---

Añadir XP a Usuario

Añadir puntos de experiencia a un usuario (interno/admin).

• URL: /api/v1/gamification/xp
• Método: POST
• Autenticación Requerida: Sí (Admin)

Descripción Interna

Este endpoint añade XP a un usuario:

1. Obtiene perfil actual con totalXp y level
2. Calcula nuevo totalXp y determina nivel resultante
3. Verifica subida de nivel (leveledUp)
4. Actualiza perfil con nuevo totalXp, level y currentLevelXp
5. Si subió de nivel, verifica y desbloquea achievements de tipo ‘level’
6. Retorna perfil actualizado con xpAdded y leveledUp

Cuerpo de Solicitud

{
  "userProfileId": "user_profile_id",
  "xpAmount": 100,
  "reason": "Completed workout"
}

Respuesta

{
  "data": {
    "id": "...",
    "totalXp": 1600,
    "level": 5,
    "currentLevelXp": 450,
    "xpAdded": 100,
    "leveledUp": false
  }
}

---

Obtener Estadísticas de Gamificación

Obtener estadísticas completas de gamificación para el usuario.

• URL: /api/v1/gamification/stats
• Método: GET
• Autenticación Requerida: Sí

Descripción Interna

Este endpoint obtiene estadísticas completas:

1. Calcula período según parámetro (week, month, year, all)

2. Ejecuta consultas en paralelo:

   • Información de nivel
   • Objetivos activos
   • Actividades completadas en el período
   • Total de achievements desbloqueados
   • Top 5 rachas activas

3. Retorna:

   • levelInfo: Nivel, XP, progreso
   • stats: activeGoals, completedActivities, totalAchievements
   • topStreaks: Mejores rachas actuales

Parámetros de Consulta de Solicitud

• period: Período de tiempo (week, month, year, all)

Respuesta

{
  "data": {
    "levelInfo": {
      "level": 5,
      "totalXp": 1500,
      "progressPercentage": 70
    },
    "stats": {
      "activeGoals": 3,
      "completedActivities": 25,
      "totalAchievements": 8
    },
    "topStreaks": [
      { "type": "WORKOUT_STREAK", "currentStreak": 15 }
    ]
  }
}