Objetivos

Endpoints para crear y gestionar objetivos de fitness.

Modelos de Datos

Los siguientes modelos de Prisma pertenecen al schema gamification:

Goal

model Goal {
  id            String   @id @default(cuid())
  userProfileId String   @map("user_profile_id")
  type          GoalType
  title         String
  description   String?

  frequency   GoalFrequency @default(DAILY)
  targetValue Float?        @map("target_value")
  unit        String?

  isActive   Boolean @default(true) @map("is_active")
  xpReward   Int     @default(10) @map("xp_reward")
  difficulty Int     @default(1)

  startDate DateTime  @default(now()) @map("start_date")
  endDate   DateTime? @map("end_date")

  userProfile     UserProfile     @relation(fields: [userProfileId], references: [id], onDelete: Cascade)
  progress        GoalProgress[]
  dailyActivities DailyActivity[]
  streaks         Streak[]

  createdAt DateTime @default(now()) @map("created_at")
  updatedAt DateTime @updatedAt @map("updated_at")

  @@map("goals")
  @@schema("gamification")
}

GoalProgress

model GoalProgress {
  id      String   @id @default(cuid())
  goalId  String   @map("goal_id")
  value   Float
  notes   String?
  logDate DateTime @default(now()) @map("log_date")

  goal Goal @relation(fields: [goalId], references: [id], onDelete: Cascade)

  @@map("goal_progress")
  @@schema("gamification")
}

DailyActivity

model DailyActivity {
  id            String         @id @default(cuid())
  userProfileId String         @map("user_profile_id")
  goalId        String?        @map("goal_id")
  activityDate  DateTime       @map("activity_date")
  status        ActivityStatus @default(PENDING)

  valueAchieved Float?  @map("value_achieved")
  notes         String?

  xpEarned  Int     @default(0) @map("xp_earned")
  wasFrozen Boolean @default(false) @map("was_frozen")

  userProfile UserProfile @relation(fields: [userProfileId], references: [id], onDelete: Cascade)
  goal        Goal?       @relation(fields: [goalId], references: [id], onDelete: Cascade)

  createdAt DateTime @default(now()) @map("created_at")
  updatedAt DateTime @updatedAt @map("updated_at")

  @@unique([userProfileId, goalId, activityDate])
  @@map("daily_activities")
  @@schema("gamification")
}

GoalType (Enum)

enum GoalType {
  WEIGHT_LOSS
  MUSCLE_GAIN
  ENDURANCE
  STRENGTH
  FLEXIBILITY
  GENERAL_FITNESS

  @@schema("gamification")
}

GoalFrequency (Enum)

enum GoalFrequency {
  DAILY
  WEEKLY
  MONTHLY
  CUSTOM

  @@schema("gamification")
}

ActivityStatus (Enum)

enum ActivityStatus {
  PENDING
  COMPLETED
  MISSED
  FROZEN

  @@schema("gamification")
}

Endpoints

Obtener Objetivos

Obtener objetivos del usuario con filtrado.

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

Descripción Interna

Este endpoint obtiene objetivos del usuario:

Filtros disponibles:
- type: Tipo de objetivo (WEIGHT_LOSS, MUSCLE_GAIN, etc.)
- frequency: Frecuencia (DAILY, WEEKLY, MONTHLY)
- isActive: Solo objetivos activos
- userProfileId: Filtrar por usuario
Incluye:
- userProfile (id, name)
- Contadores de progress y dailyActivities
Ordenado por fecha de creación descendente

Parámetros de Consulta de Solicitud

type: Tipo de objetivo
frequency: Frecuencia del objetivo
isActive: Filtrar solo objetivos activos
page: Número de página
limit: Resultados por página

Ejemplo de Cliente Hono

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

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

const res = await client.api.v1.gamification.goals.$get({
  query: {
    isActive: 'true'
  }
})

Obtener Objetivo por ID

Obtener un objetivo específico con historial de progreso.

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

Crear Objetivo

Crear un nuevo objetivo.

URL: /api/v1/gamification/goals
Método: POST
Autenticación Requerida: Sí

Descripción Interna

Este endpoint crea un nuevo objetivo:

Crea el objetivo con:
- title, description, type, frequency
- targetValue, unit, xpReward, difficulty
- startDate (default: hoy), endDate (opcional)
Crea automáticamente un Streak asociado:
- type: ‘GOAL_STREAK’
- Vinculado al goalId
Retorna el objetivo con userProfile incluido

Cuerpo de Solicitud

{
  "title": "Run 5k",
  "description": "Run 5km in under 30 mins",
  "type": "CARDIO",
  "frequency": "WEEKLY",
  "targetValue": 5,
  "unit": "km",
  "xpReward": 100,
  "difficulty": 2,
  "deadline": "2023-12-31"
}

Ejemplo de Cliente Hono

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

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

const res = await client.api.v1.gamification.goals.$post({
  json: {
    title: 'Run 5k',
    description: 'Run 5km in under 30 mins',
    targetValue: 5,
    unit: 'km',
    xpReward: 100
  }
})

Actualizar Objetivo

Actualizar un objetivo existente.

URL: /api/v1/gamification/goals/:id
Método: PUT
Autenticación Requerida: Sí

Eliminar Objetivo

Eliminar un objetivo.

URL: /api/v1/gamification/goals/:id
Método: DELETE
Autenticación Requerida: Sí

Registrar Progreso de Objetivo

Registrar progreso para un objetivo.

URL: /api/v1/gamification/goals/:id/progress
Método: POST
Autenticación Requerida: Sí

Cuerpo de Solicitud

{
  "value": 3.5,
  "notes": "Ran 3.5km today"
}

Crear Actividad Diaria

Registrar una actividad diaria completada.

URL: /api/v1/gamification/daily-activities
Método: POST
Autenticación Requerida: Sí

Descripción Interna

Este endpoint registra una actividad diaria:

Normaliza la fecha a inicio del día (00:00:00)
Verifica duplicados: No permite dos actividades del mismo objetivo en el mismo día
Crea la actividad con status: ‘COMPLETED’
Otorga XP:
- Calcula: xpReward × difficulty del objetivo
- Añade XP al usuario
Actualiza racha del objetivo asociado

Cuerpo de Solicitud

{
  "goalId": "goal_id",
  "activityDate": "2023-10-27",
  "value": 5,
  "notes": "Completed morning run"
}

Obtener Actividades Diarias

Obtener actividades diarias para un rango de fechas.

URL: /api/v1/gamification/daily-activities
Método: GET
Autenticación Requerida: Sí

Parámetros de Consulta de Solicitud

startDate: Fecha de inicio
endDate: Fecha de fin
goalId: Filtrar por objetivo
status: Filtrar por status