Workout App API

API robusta para la gestión de atletas, entrenadores, ejercicios y sesiones de entrenamiento. Construida con Node.js, TypeScript, Express y MongoDB/Mongoose.

Tabla de Contenidos

• Descripción
• Stack Tecnológico
• Características
• Instalación y Configuración
• Ejecución y Seeding
• Pruebas
• Estructura del Proyecto
• Endpoints Principales
• Seguridad y Autenticación
• Email y Notificaciones
• Sistema de Colas
• Contribución
• Licencia

---

Descripción

Backend para el seguimiento y análisis de progreso de atletas y entrenadores, con endpoints seguros, validaciones exhaustivas y consultas avanzadas.

Stack Tecnológico

• Node.js 22+
• TypeScript
• Express.js
• MongoDB + Mongoose
• Joi (validación)
• JWT (autenticación)
• Redis (opcional, cache/sesiones)
• Jest (tests)
• Docker y docker-compose

Características

• Autenticación robusta (JWT dual-token, refresh rotation)
• Gestión completa de atletas, ejercicios y sesiones
• Relaciones complejas y populate avanzado
• Validaciones estrictas con Joi y DTOs tipados
• Seguridad avanzada: roles, ownership, middlewares
• Consultas avanzadas: filtros, paginación, select
• Tests unitarios y e2e (>96% cobertura)
• Listo para producción: Docker, logging, error handling

Instalación y Configuración

git clone https://github.com/tu-usuario/workout-app.git
cd workout-app
yarn install
cp .env.dist .env # y edita según tu entorno

Variables principales en .env:

• NODE_ENV — Entorno de ejecución (development, production)
• MONGO_URI — Cadena de conexión a MongoDB
• REDIS_URI — Cadena de conexión a Redis
• JWT_SECRET — Secreto para firmar JWT
• JWT_EXPIRATION — Duración del access token (ej: 30m)
• JWT_REFRESH_EXPIRATION — Duración del refresh token (ej: 7d)
• SALT_ROUNDS — Rondas de hash para contraseñas
• SMTP_HOST, SMTP_PORT, SMTP_SECURE, SMTP_USER, SMTP_PASSWORD, SMTP_FROM, SMTP_FROM_NAME — Configuración de email
• LOG_LEVEL — Nivel de logs (debug, info, warn, error)
• MAX_LOGIN_ATTEMPTS, MAX_PASSWORD_RESET_ATTEMPTS, BLOCK_DURATION — Seguridad de login/reset
• CODE_LENGTH, CODE_RETRY_INTERVAL, CODE_EXPIRATION — Configuración de códigos de recuperación
• FRONTEND_URL — URL del frontend permitido para CORS y emails

Ejecución y Seeding

• Desarrollo: yarn dev
• Producción: yarn start
• Docker: docker-compose up -d
• Seeding: yarn seed o npx ts-node src/seeders/index.seeder.ts

Pruebas

• Todas: yarn test
• Unitarias: yarn test:unit
• E2E: yarn test:e2e
• Cobertura: yarn test:coverage

Estructura del Proyecto

src/
  config/         # Configuración
  controllers/    # Endpoints
  DTOs/           # Data Transfer Objects
  exceptions/     # Excepciones personalizadas
  factories/      # Factories para tests y seeders
  handlers/       # Respuesta y error
  helpers/        # Utilidades
  interfaces/     # Interfaces TS
  middlewares/    # Middlewares Express
  models/         # Modelos Mongoose
  repositories/   # Acceso a datos
  routes/         # Definición de rutas
  schemas/        # Validación Joi
  seeders/        # Poblar la base de datos
  services/       # Lógica de negocio
  strategies/     # Estrategias de autenticación
  templates/      # Plantillas de email
  types/          # Tipos globales
  utils/          # Utilidades generales
tests/
  config/
  e2e/            # Tests de integración
  unit/           # Tests unitarios

Endpoints Principales

• POST /auth/login — Login (access y refresh token)
• POST /auth/refresh — Renovar tokens
• GET /athletes — Listar atletas
• POST /athletes — Crear atleta
• PATCH /athletes/:id — Actualizar atleta
• PATCH /athletes/:id/disciplines — Actualizar disciplinas del atleta
• DELETE /athletes/:id — Eliminar atleta
• ...y más para ejercicios, sesiones, usuarios

Seguridad y Autenticación

• JWT dual-token (access/refresh) con rotación y gestión avanzada de sesiones
• El refresh token se entrega y valida mediante una cookie httpOnly segura (no accesible por JS)
• Roles y ownership
• Validaciones Joi en todos los endpoints
• Middleware de autenticación y autorización

Email y Notificaciones

• Envío de emails con Nodemailer y plantillas Handlebars
• Mailhog para desarrollo (docker-compose)
• Ejemplo de uso en src/services/mail.service.ts

Sistema de Colas

La aplicación incluye un sistema de colas robusto basado en BullMQ y Redis para el procesamiento asíncrono de tareas en segundo plano:

• ✅ Procesamiento asíncrono de emails y notificaciones
• ✅ Dead Letter Queue (DLQ) para manejo de fallos
• ✅ Workers especializados con reintentos automáticos
• ✅ Sistema de eventos para monitoreo del ciclo de vida
• ✅ Persistencia de trabajos fallidos en MongoDB
• ✅ Escalabilidad horizontal con múltiples workers

📖 Ver documentación completa del Sistema de Colas

Uso Básico

import { enqueueEmailJob } from './queueSystem/jobs/email/email.job'
import { JobEnum } from './utils/enums/jobs/jobs.enum'
import { TemplateEnum } from './utils/enums/templates.enum'

// Agregar trabajo de email
await enqueueEmailJob({
  type: JobEnum.EMAIL,
  template: TemplateEnum.WELCOME,
  payload: { to: '[email protected]', userName: 'Juan' },
})

Testing

La aplicación cuenta con una suite completa de pruebas unitarias y de integración:

• ✅ 625 tests totales (unitarios + e2e)
• ✅ Cobertura superior al 96%
• ✅ Pruebas aisladas con mocks y factories
• ✅ Tests e2e para flujos completos de autenticación y seguridad

Para ejecutar los tests:

yarn test           # Todos los tests
yarn test:unit      # Solo unitarios
yarn test:e2e       # Solo end-to-end
yarn test:coverage  # Con cobertura

Contribución

• Sigue la Guía de Estilos
• Revisa la configuración recomendada de editor
• Pull requests y sugerencias bienvenidas

---

Licencia

MIT