app-padel/docs/roadmap/FASE-04.md

# Fase 4: Pagos y Monetización

## Estado: ✅ COMPLETADA

### ✅ 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*