Sistema de Referidos y Promociones

TalentBricksAI incluye un sistema completo de referidos y codigos promocionales para adquisicion y retencion de usuarios.

Resumen del Sistema

Flujo de Referidos

┌─────────────────────────────────────────────────────────────────┐
│                      FLUJO DE REFERIDOS                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Usuario A                    Usuario B (Referido)              │
│  ─────────                    ────────────────────              │
│                                                                 │
│  1. Genera link               4. Click en link                  │
│     /r/abc12def                  → Cookie 30 dias               │
│         │                            │                          │
│         │                            ▼                          │
│         │                    5. Se registra                     │
│         │                       → ReferralSignup                │
│         │                            │                          │
│  2. Recibe email ◀───────────────────┤ (notificación)           │
│     "Nuevo signup!"                  │                          │
│         │                            ▼                          │
│         │                    6. Primera compra                  │
│         │                       → 15% descuento                 │
│         │                            │                          │
│  3. Recibe email ◀───────────────────┤ (notificación)           │
│     "Amigo compro!"                  │                          │
│     + 20% reward                     │                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Beneficios

Rol	Beneficio
Referidor	20% de descuento cuando su referido compra (valido 90 dias)
Referido	15% de descuento en su primera compra

Para Usuarios

Obtener tu Link de Referido

1. Inicia sesión en tu cuenta
2. Ve a Cuenta > Referidos (/account/referrals)
3. Tu link único estara disponible: https://talentbricks.ai/r/tu-código
4. Comparte el link por redes sociales, email, etc.

Dashboard de Referidos

El dashboard muestra:

• Estadísticas: Clicks, signups y conversiones
• Link compartible: Con botón de copiar
• Historial: Lista de referidos con estado
• Recompensas: Descuentos disponibles para usar

Usar tus Recompensas

1. Cuándo un referido hace una compra, recibes un reward de 20%
2. Ve a cualquier curso y haz click en “Comprar”
3. En el checkout, selecciona tu recompensa disponible
4. El descuento se aplica automaticamente

Para Administradores

Panel de Promociones

Accede a /admin/promotions para ver 3 tabs:

Tab 1: Promo Codes

Gestiona codigos promocionales:

Campo	descripción
código	Ej: “VERANO20” (se convierte a mayusculas)
Tipo	Porcentaje o monto fijo
Valor	Porcentaje (10 = 10%) o centavos (500 = $5)
Usos maximos	Limite de uso (opcional)
Expiracion	Fecha limite (opcional)
Cursos	específico a cursos o todos
Solo nuevos	Solo para usuarios sin compras previas
Compra minima	Monto minimo requerido

Crear nuevo código:

// Ejemplo: 25% de descuento, max 100 usos, expira en 30 dias
{
  code: "NAVIDAD25",
  discountType: "PERCENTAGE",
  discountValue: 25,
  maxUses: 100,
  expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000),
  newUsersOnly: false,
  isActive: true
}

Tab 2: Referral Analytics

Estadísticas de referidos:

• Total de referidores activos
• Total de signups y conversiones
• Tasa de conversion
• Top 10 referidores
• Signups recientes

Tab 3: Rewards

Gestiona recompensas de usuarios:

• Ver recompensas activas y redimidas
• Aprobar recompensas manualmente
• Rechazar/eliminar recompensas fraudulentas

integración Tecnica

Rutas

Ruta	Componente	descripción
/r/:code	ReferralLandingPage	Landing de referidos
/account/referrals	ReferralDashboardPage	Dashboard usuario
/admin/promotions	AdminPromotionsPage	Admin panel

Cookie de Referido

Cuándo un usuario visita /r/:code:

1. Se guarda cookie referral_code por 30 dias
2. Se registra el click en ReferralCode.clicks
3. Se redirige a /signup

Al registrarse, si existe la cookie:

1. Se crea ReferralSignup con el código
2. Se incrementa ReferralCode.signups
3. Se envia email al referidor

Checkout con Descuentos

El checkout (createCourseCheckout) acepta:

{
  courseId: number;
  promoCode?: string;   // código promocional
  rewardId?: string;    // ID de reward a redimir
}

Prioridad de descuentos:

1. código promocional (si es valido)
2. Reward de usuario (si no hay promo)
3. Descuento de referido (15% primera compra)

Webhook de Stripe

El handler checkout.session.completed:

1. Crea enrollment del curso
2. Incrementa uso del promo code
3. Marca reward como redimido
4. Procesa conversion de referido:
   • Marca ReferralSignup.convertedAt
   • Incrementa ReferralCode.conversions
   • Crea reward para el referidor
   • Envia email de notificación

Emails

Plantillas Disponibles

función	Trigger	Destinatario
sendReferralSignupEmail	Usuario se registra via link	Referidor
sendReferralConversionEmail	Referido hace primera compra	Referidor
sendRewardEarnedEmail	Usuario gana una recompensa	Usuario
sendPromoExpiringEmail	Promo cerca de expirar	Usuario

Ejemplo de Email

┌────────────────────────────────────────┐
│         [Logo TalentBricks]            │
├────────────────────────────────────────┤
│                                        │
│  Felicidades, Juan!                    │
│                                        │
│  Tu amigo acaba de comprar un curso.   │
│                                        │
│  ┌────────────────────────────┐        │
│  │ Tu recompensa:             │        │
│  │ 20% de descuento           │        │
│  │ Curso: Python básico       │        │
│  └────────────────────────────┘        │
│                                        │
│  [Ver mis recompensas]                 │
│                                        │
├────────────────────────────────────────┤
│  © 2024 TalentBricks                   │
└────────────────────────────────────────┘

configuración

Variables de Entorno

# URL base para links de referido
WASP_WEB_CLIENT_URL=https://talentbricks.ai

Constantes del Sistema

Constante	Valor	Ubicacion
Longitud código referido	8 caracteres	referral/operations.ts
Duracion cookie	30 dias	ReferralLandingPage.tsx
Descuento referido	15%	courses/operations.ts
Reward referidor	20%	referral/operations.ts
Expiracion reward	90 dias	referral/operations.ts

Mejores Prácticas

Para Administradores

1. Codigos promocionales:

   • Usa nombres descriptivos (VERANO20, NAVIDAD25)
   • Establece limites de uso para controlar costos
   • Revisa analytics periodicamente

2. Fraude:

   • Monitorea conversiones sospechosas
   • Usa el panel de rewards para revisar manualmente
   • Rechaza rewards de cuentas duplicadas

3. Engagement:

   • Crea promos por temporada
   • Incentiva referidos con comunicaciones
   • Destaca top referidores

Para Desarrolladores

1. Nuevas validaciones de promo:

   // En promo/operations.ts
   // Agregar validación antes de retornar promo valido

2. Nuevos tipos de reward:

   // En schema.prisma, agregar a RewardType enum
   // Actualizar lógica en courses/operations.ts

3. Testing:

   # Seed de admin
   wasp db seed seedAdminUser
   
   # Crear promo desde admin panel
   # Probar checkout con promo

Troubleshooting

Cookie no se guarda

• Verificar que /r/:code redirige correctamente
• Revisar que document.cookie no está bloqueado
• Verificar dominio en produccion

Email no se envia

• En desarrollo, emails se imprimen en consola
• Verificar configuración de SendGrid en produccion
• Revisar logs del servidor

Descuento no se aplica

• Verificar que promo code es valido y activo
• Revisar restricciones (curso, usuario nuevo, etc.)
• Confirmar que no excede usos maximos