✅ FASE 4 COMPLETADA: Pagos y Monetización con MercadoPago

Implementados 4 módulos con agent swarm: 1. MERCADOPAGO INTEGRADO - SDK oficial de MercadoPago - Crear preferencias de pago - Webhooks para notificaciones - Reembolsos y cancelaciones - Estados: PENDING, PROCESSING, COMPLETED, REFUNDED 2. SISTEMA DE BONOS Y PACKS - Pack 5, Pack 10, Pack Mensual - Compra online con MP - Uso FIFO automático - Control de expiración - Aplicación en reservas 3. SUSCRIPCIONES/MEMBRESÍAS - Planes: Básico, Premium, Anual VIP - Beneficios: descuentos, reservas gratis, prioridad - Cobro recurrente vía MP - Estados: ACTIVE, PAUSED, CANCELLED - Aplicación automática en reservas 4. CLASES CON PROFESORES - Registro de coaches con verificación - Tipos: Individual, Grupal, Clínica - Horarios y disponibilidad - Reservas con pago integrado - Sistema de reseñas Endpoints nuevos: - /payments/* - Pagos MercadoPago - /bonus-packs/*, /bonuses/* - Bonos - /subscription-plans/*, /subscriptions/* - Suscripciones - /coaches/* - Profesores - /classes/*, /class-enrollments/* - Clases Variables de entorno: - MERCADOPAGO_ACCESS_TOKEN - MERCADOPAGO_PUBLIC_KEY - MERCADOPAGO_WEBHOOK_SECRET Datos de prueba: - 3 Bonus Packs - 3 Planes de suscripción - 1 Coach verificado (admin) - 3 Clases disponibles
2026-01-31 09:02:25 +00:00
parent 6494e2b38b
commit b8a964dc2c
44 changed files with 7084 additions and 9 deletions
--- a/docs/roadmap/FASE-04.md
+++ b/docs/roadmap/FASE-04.md
@@ -1,6 +1,270 @@
-# Fase 4: Pagos
+# Fase 4: Pagos y Monetización

-## Estado: ⏳ Pendiente
+## Estado: ✅ COMPLETADA

-*Esta fase comenzará al finalizar la Fase 3*
+### ✅ Tareas completadas:

+#### 4.1.1: Integración de MercadoPago
+- [x] SDK de MercadoPago instalado y configurado
+- [x] Crear preferencias de pago
+- [x] Webhooks para notificaciones de pago
+- [x] Procesar pagos completados
+- [x] Reembolsos (refunds)
+- [x] Cancelación de pagos pendientes
+
+#### 4.1.2: Gestión de Transacciones
+- [x] Historial de pagos del usuario
+- [x] Estados de pago (PENDING, PROCESSING, COMPLETED, FAILED, REFUNDED, CANCELLED)
+- [x] Comprobantes/facturas automáticas
+- [x] Metadata de pagos (método, cuotas)
+
+#### 4.2.1: Sistema de Bonos
+- [x] Tipos de bonos (5, 10, 30 clases)
+- [x] Compra de bonos online (integración MP)
+- [x] Descuento automático al usar bono
+- [x] Expiración de bonos configurable
+- [x] Historial de uso de bonos
+- [x] Verificación automática de expirados
+
+#### 4.2.2: Suscripciones/Membresías
+- [x] Planes: Básico, Premium, Anual VIP
+- [x] Beneficios por plan (descuentos, reservas gratis, prioridad)
+- [x] Cobro recurrente vía MercadoPago
+- [x] Estados: PENDING, ACTIVE, PAUSED, CANCELLED, EXPIRED
+- [x] Cambio de método de pago
+- [x] Aplicación automática de beneficios en reservas
+
+#### 4.3.1: Gestión de Profesores
+- [x] Perfil de coaches (bio, especialidades, certificaciones)
+- [x] Horarios disponibles por coach
+- [x] Tarifas por clase/tipo
+- [x] Sistema de reseñas y rating
+
+#### 4.3.2: Reserva de Clases
+- [x] Catálogo de clases disponibles
+- [x] Tipos: Individual, Grupal, Clínica
+- [x] Reserva con pago integrado (MP)
+- [x] Control de cupos
+- [x] Historial de clases tomadas
+- [x] Marcado de asistencia
+
+---
+
+## 💳 Integración MercadoPago
+
+### Flujo de Pago
+
+1. **Crear Preferencia** → Backend crea preferencia MP con items
+2. **Redirigir a MP** → Frontend redirige a init_point
+3. **Usuario paga** → En MP con tarjeta/efectivo/transferencia
+4. **Webhook MP** → Notifica a backend el resultado
+5. **Actualizar estado** → Backend actualiza payment y entidad relacionada
+
+### Estados de Pago
+
+| Estado | Descripción |
+|--------|-------------|
+| PENDING | Preferencia creada, esperando pago |
+| PROCESSING | Pago en proceso |
+| COMPLETED | Pago aprobado |
+| FAILED | Pago rechazado |
+| REFUNDED | Reembolsado |
+| CANCELLED | Cancelado por usuario |
+
+---
+
+## 🎟️ Sistema de Bonos
+
+### Tipos de Bonos
+
+| Nombre | Reservas | Precio | Validez |
+|--------|----------|--------|---------|
+| Pack 5 Clases | 5 | $90 | 90 días |
+| Pack 10 Clases | 10 | $160 | 180 días |
+| Pack Mensual | 30 | $400 | 30 días |
+
+### Reglas
+- Un bono = Una reserva completa (1 hora)
+- No se puede usar parcialmente
+- Un booking solo puede tener un bono
+- FIFO al usar (el que expira primero)
+
+---
+
+## 💎 Suscripciones
+
+### Planes Disponibles
+
+| Plan | Precio/Mes | Descuento | Gratis/Mes | Prioridad |
+|------|-----------|-----------|------------|-----------|
+| Básico | $150 | 10% | 2 | No |
+| Premium | $250 | 20% | 5 | Sí |
+| Anual VIP | $25000/año | 30% | 10 | Sí |
+
+### Beneficios Automáticos
+- Descuento en todas las reservas
+- Reservas gratis mensuales (contador)
+- Prioridad en reservas (primeros en cola)
+- Descuento en torneos
+
+---
+
+## 👨‍🏫 Sistema de Clases
+
+### Tipos de Clase
+
+| Tipo | Máx. Alumnos | Duración | Precio/persona |
+|------|-------------|----------|----------------|
+| Individual | 1 | 60 min | $50 |
+| Grupal | 2-4 | 60 min | $35 |
+| Clínica | 5-16 | 90 min | $20 |
+
+### Proceso
+1. Ver catálogo de clases
+2. Seleccionar clase y ver sesiones disponibles
+3. Inscribirse y pagar vía MercadoPago
+4. Confirmación automática al completar pago
+5. Asistencia marcada por el coach
+
+---
+
+## 🔌 Endpoints de Pagos
+
+```
+POST   /api/v1/payments/preference        - Crear preferencia MP
+GET    /api/v1/payments/my-payments       - Mis pagos
+GET    /api/v1/payments/:id               - Ver pago
+POST   /api/v1/payments/webhook           - Webhook MP (público)
+POST   /api/v1/payments/:id/refund        - Reembolsar (admin)
+POST   /api/v1/payments/:id/cancel        - Cancelar pago
+```
+
+## 🔌 Endpoints de Bonos
+
+```
+GET    /api/v1/bonus-packs                - Listar packs disponibles
+POST   /api/v1/bonus-packs                - Crear pack (admin)
+POST   /api/v1/bonuses/purchase           - Comprar bono
+GET    /api/v1/bonuses/my-bonuses         - Mis bonos
+GET    /api/v1/bonuses/available          - Bonos disponibles para usar
+POST   /api/v1/bonuses/:id/use            - Usar bono específico
+POST   /api/v1/bonuses/use-auto           - Usar bono automático
+```
+
+## 🔌 Endpoints de Suscripciones
+
+```
+GET    /api/v1/subscription-plans         - Listar planes
+POST   /api/v1/subscription-plans         - Crear plan (admin)
+POST   /api/v1/subscriptions              - Crear suscripción
+GET    /api/v1/subscriptions/my-subscription - Mi suscripción
+GET    /api/v1/subscriptions/benefits     - Ver mis beneficios
+PUT    /api/v1/subscriptions/:id/cancel   - Cancelar
+PUT    /api/v1/subscriptions/:id/pause    - Pausar
+PUT    /api/v1/subscriptions/:id/resume   - Reanudar
+POST   /api/v1/subscriptions/webhook      - Webhook MP
+```
+
+## 🔌 Endpoints de Clases
+
+```
+POST   /api/v1/coaches/register           - Registrarme como coach
+GET    /api/v1/coaches                    - Listar coaches
+GET    /api/v1/coaches/:id                - Ver coach
+POST   /api/v1/coaches/:id/reviews        - Dejar reseña
+GET    /api/v1/classes                    - Listar clases
+POST   /api/v1/classes                    - Crear clase (coach)
+POST   /api/v1/classes/:id/sessions       - Programar sesión
+POST   /api/v1/class-enrollments          - Inscribirme
+GET    /api/v1/class-enrollments/my       - Mis inscripciones
+PUT    /api/v1/class-enrollments/:id/attend - Marcar asistencia
+```
+
+---
+
+## 🚀 Cómo probar pagos
+
+### Configurar credenciales MercadoPago
+```bash
+# .env
+MERCADOPAGO_ACCESS_TOKEN=TEST-xxxxxxxx
+MERCADOPAGO_PUBLIC_KEY=TEST-yyyyyyyy
+```
+
+### Crear preferencia de pago
+```bash
+curl -X POST http://localhost:3000/api/v1/payments/preference \
+  -H "Authorization: Bearer TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "type": "BOOKING",
+    "referenceId": "booking-id",
+    "title": "Reserva Cancha 1",
+    "description": "Reserva para el 15/02/2024",
+    "amount": 2500
+  }'
+```
+
+---
+
+## 📁 Archivos creados en esta fase
+
+```
+backend/src/
+├── config/
+│   └── mercadopago.ts           # Configuración MP
+├── services/
+│   ├── payment.service.ts       # Pagos con MP
+│   ├── bonusPack.service.ts     # Packs de bonos
+│   ├── userBonus.service.ts     # Bonos de usuarios
+│   ├── subscriptionPlan.service.ts  # Planes
+│   ├── subscription.service.ts  # Suscripciones
+│   ├── coach.service.ts         # Coaches
+│   ├── class.service.ts         # Clases
+│   └── classEnrollment.service.ts   # Inscripciones
+├── controllers/
+│   ├── payment.controller.ts
+│   ├── bonusPack.controller.ts
+│   ├── userBonus.controller.ts
+│   ├── subscriptionPlan.controller.ts
+│   ├── subscription.controller.ts
+│   ├── coach.controller.ts
+│   ├── class.controller.ts
+│   └── classEnrollment.controller.ts
+├── routes/
+│   ├── payment.routes.ts
+│   ├── bonus.routes.ts
+│   ├── subscription.routes.ts
+│   ├── coach.routes.ts
+│   ├── class.routes.ts
+│   └── classEnrollment.routes.ts
+└── validators/
+    ├── payment.validator.ts
+    ├── bonus.validator.ts
+    ├── subscription.validator.ts
+    └── class.validator.ts
+```
+
+---
+
+## 🎯 Datos de prueba
+
+| Entidad | Datos |
+|---------|-------|
+| Bonus Packs | Pack 5, Pack 10, Pack Mensual |
+| Planes | Básico ($150), Premium ($250), Anual VIP ($25000) |
+| Coach | Admin verificado como coach |
+| Clases | Individual, Pareja, Clínica de Volea |
+
+---
+
+## 📝 Notas
+
+- MercadoPago en modo sandbox para desarrollo
+- Webhooks configurables en dashboard de MP
+- Requiere cuenta de MP para producción
+- Beneficios de suscripción aplicados automáticamente
+
+---
+
+*Completada el: 2026-01-31*