michangarrito/docs/01-epicas/MCH-023-programa-referidos.md

id	type	title	code	status	phase	priority	story_points	created_at	updated_at	simco_version	dependencies
EPIC-MCH-023	Epic	MCH-023: Programa de Referidos	MCH-023	Completado	6	P2	21	2026-01-10	2026-01-17	4.0.1	blocks depends_on

MCH-023: Programa de Referidos

Metadata

• Codigo: MCH-023
• Fase: 6 - Crecimiento
• Prioridad: P2
• Estado: Completado
• Story Points: 21
• Fecha completado: 2026-01-10

Descripcion

Programa de referidos para crecimiento organico: codigos de referencia unicos, beneficios para referidor y referido, tracking de conversiones, y recompensas automaticas.

Objetivos

1. Codigos de referido unicos
2. Beneficios para ambas partes
3. Tracking de conversiones
4. Recompensas automaticas
5. Dashboard de referidos

Alcance

Incluido

• Codigo unico por usuario
• Link compartible
• Beneficio: 1 mes gratis (referidor)
• Beneficio: 50% descuento primer mes (referido)
• Dashboard con estadisticas
• Notificaciones de conversion

Excluido

• Comisiones en efectivo
• Multinivel (referidos de referidos)
• Programa de afiliados formal

Mecanica del Programa

Beneficios

Rol	Beneficio	Condicion
Referidor	1 mes gratis de suscripcion	Por cada referido que pague
Referido	50% descuento primer mes	Al registrarse con codigo

Flujo de Referido

1. Usuario A tiene codigo "TIENDAJUAN"
2. Comparte link: michangarrito.com/r/TIENDAJUAN
3. Usuario B se registra con codigo
4. Usuario B obtiene 50% descuento
5. Usuario B paga primer mes
6. Usuario A recibe notificacion
7. Usuario A obtiene 1 mes gratis acumulado

Modelo de Datos

Tablas

referral_codes

• id, tenant_id, code (unique)
• created_at, active

referrals

• id, referrer_tenant_id, referred_tenant_id
• code_used, status (pending/converted/expired)
• converted_at, reward_applied_at

referral_rewards

• id, tenant_id, type (free_month)
• months_earned, months_used
• expires_at

Endpoints API

Metodo	Endpoint	Descripcion
GET	/referrals/my-code	Mi codigo
POST	/referrals/generate-code	Generar nuevo codigo
GET	/referrals/stats	Estadisticas
GET	/referrals/list	Mis referidos
POST	/referrals/apply-code	Aplicar codigo (registro)
GET	/referrals/rewards	Mis recompensas

Estados del Referido

pending ──► converted ──► rewarded
    │
    └──► expired (si no paga en 30 dias)

Estado	Descripcion
pending	Referido registrado, no ha pagado
converted	Referido pago primer mes
rewarded	Recompensa aplicada al referidor
expired	Referido no pago en tiempo

UI Components

ShareReferralCard

┌─────────────────────────────────┐
│  Invita amigos y gana          │
│                                 │
│  Tu codigo: TIENDAJUAN         │
│                                 │
│  [Copiar]  [Compartir WhatsApp] │
│                                 │
│  Por cada amigo que se suscriba │
│  ganas 1 mes gratis!           │
└─────────────────────────────────┘

ReferralStats

┌─────────────────────────────────┐
│  Tus Referidos                 │
├─────────────────────────────────┤
│  👥 Invitados: 8               │
│  ✅ Convertidos: 3             │
│  🎁 Meses ganados: 3           │
│  📅 Meses disponibles: 2       │
└─────────────────────────────────┘

ReferralList

• Tabla de referidos
• Nombre, fecha, estado
• Recompensa aplicada

Notificaciones

Referido se Registra

[Push al referidor]
"🎉 Juan se registro con tu codigo!
Te avisaremos cuando active su suscripcion."

Referido Paga

[Push + WhatsApp al referidor]
"🎁 Ganaste 1 mes gratis!
Juan activo su suscripcion.
Ya tienes 3 meses acumulados."

Integracion con Suscripciones

// Al procesar pago de suscripcion
async function processSubscriptionPayment(tenant, payment) {
  // Verificar si tiene meses gratis disponibles
  const rewards = await getReferralRewards(tenant.id);

  if (rewards.months_available > 0) {
    // Usar mes gratis en lugar de cobrar
    await useReferralMonth(tenant.id);
    return { charged: false, used_referral: true };
  }

  // Cobrar normalmente
  return chargeSubscription(tenant, payment);
}

Historias de Usuario

MCH-US-220: Codigo de Referido Unico

Story Points: 3

Como propietario de tienda Quiero tener un codigo de referido unico y personalizable Para compartirlo facilmente con mis contactos y que sea memorable

Criterios de Aceptacion

• [CA-220-1] El sistema genera automaticamente un codigo unico al crear la tienda
• [CA-220-2] El codigo tiene formato MCH-XXXXX por defecto
• [CA-220-3] El usuario puede personalizar su codigo (ej: TIENDAJUAN) si esta disponible
• [CA-220-4] El codigo es case-insensitive para facilitar ingreso
• [CA-220-5] El sistema valida que el codigo no contenga palabras ofensivas

Tareas

ID	Tarea	Estimacion
MCH-TT-220-01	Crear tabla referral_codes en DDL	2h
MCH-TT-220-02	Implementar servicio de generacion de codigos	3h
MCH-TT-220-03	Endpoint GET /referrals/my-code	1h
MCH-TT-220-04	Endpoint POST /referrals/generate-code con personalizacion	2h
MCH-TT-220-05	Validacion de codigos ofensivos (blacklist)	1h

---

MCH-US-221: Link Compartible con Codigo Embebido

Story Points: 2

Como propietario de tienda Quiero obtener un link compartible con mi codigo de referido Para enviarlo por WhatsApp, redes sociales o email sin friccion

Criterios de Aceptacion

• [CA-221-1] El link tiene formato michangarrito.com/r/{CODIGO}
• [CA-221-2] El boton "Copiar" copia el link al portapapeles
• [CA-221-3] El boton "Compartir WhatsApp" abre WhatsApp con mensaje predefinido
• [CA-221-4] El link es valido mientras el codigo este activo
• [CA-221-5] Al acceder al link, el registro pre-llena el campo de codigo

Tareas

ID	Tarea	Estimacion
MCH-TT-221-01	Implementar ruta /r/{codigo} en frontend	2h
MCH-TT-221-02	Componente ShareReferralCard con botones	2h
MCH-TT-221-03	Integracion con Web Share API	1h
MCH-TT-221-04	Pre-llenado de codigo en formulario de registro	1h

---

MCH-US-222: Beneficio al Referido (50% Descuento)

Story Points: 5

Como nuevo usuario registrado con codigo de referido Quiero recibir automaticamente un 50% de descuento en mi primer mes Para probar la plataforma a menor costo

Criterios de Aceptacion

• [CA-222-1] Al registrarse con codigo valido, se aplica 50% de descuento
• [CA-222-2] El descuento aplica solo al primer mes de suscripcion
• [CA-222-3] El usuario ve claramente el descuento aplicado en checkout
• [CA-222-4] Si el codigo es invalido/expirado, se muestra mensaje de error
• [CA-222-5] El descuento se registra en el historial de pagos

Tareas

ID	Tarea	Estimacion
MCH-TT-222-01	Endpoint POST /referrals/apply-code en registro	2h
MCH-TT-222-02	Logica de validacion de codigo (activo, no expirado)	2h
MCH-TT-222-03	Integracion con modulo de suscripciones para descuento	4h
MCH-TT-222-04	UI de confirmacion de descuento en checkout	2h
MCH-TT-222-05	Tests de integracion de flujo completo	2h

---

MCH-US-223: Recompensa al Referidor (1 Mes Gratis)

Story Points: 5

Como usuario que refirio a un nuevo cliente Quiero recibir 1 mes gratis de suscripcion cuando mi referido pague Para ser recompensado por ayudar al crecimiento de la plataforma

Criterios de Aceptacion

• [CA-223-1] Al pagar el referido su primer mes, se acredita 1 mes gratis al referidor
• [CA-223-2] Los meses gratis son acumulables (multiples referidos)
• [CA-223-3] Los meses gratis se usan automaticamente en el siguiente ciclo de pago
• [CA-223-4] El referidor recibe notificacion cuando gana el mes gratis
• [CA-223-5] Los meses gratis tienen vigencia de 12 meses

Tareas

ID	Tarea	Estimacion
MCH-TT-223-01	Crear tabla referral_rewards en DDL	2h
MCH-TT-223-02	Trigger al confirmar pago de referido	3h
MCH-TT-223-03	Logica de acreditacion de meses gratis	2h
MCH-TT-223-04	Integracion con processSubscriptionPayment	4h
MCH-TT-223-05	Endpoint GET /referrals/rewards	1h

---

MCH-US-224: Tracking de Conversiones

Story Points: 3

Como sistema Quiero rastrear el estado de cada referido (pending/converted/expired) Para gestionar correctamente las recompensas y metricas

Criterios de Aceptacion

• [CA-224-1] Estado inicial es "pending" al registrarse con codigo
• [CA-224-2] Cambia a "converted" cuando referido paga primer mes
• [CA-224-3] Cambia a "expired" si no paga en 30 dias
• [CA-224-4] Estado "rewarded" se marca cuando referidor recibe beneficio
• [CA-224-5] Job programado verifica expiraciones diariamente

Tareas

ID	Tarea	Estimacion
MCH-TT-224-01	Crear tabla referrals con estados	2h
MCH-TT-224-02	Implementar maquina de estados de referido	3h
MCH-TT-224-03	Cron job para marcar expirados	2h
MCH-TT-224-04	Logs de auditoria de cambios de estado	1h

---

MCH-US-225: Dashboard de Referidos

Story Points: 3

Como propietario de tienda Quiero ver un dashboard con mis estadisticas de referidos Para conocer el impacto de mis invitaciones y meses acumulados

Criterios de Aceptacion

• [CA-225-1] Muestra total de invitados (todos los registrados)
• [CA-225-2] Muestra convertidos (que pagaron)
• [CA-225-3] Muestra meses ganados y meses disponibles
• [CA-225-4] Lista de referidos con nombre, fecha y estado
• [CA-225-5] Opcion de filtrar por estado (pending/converted/expired)

Tareas

ID	Tarea	Estimacion
MCH-TT-225-01	Endpoint GET /referrals/stats	2h
MCH-TT-225-02	Endpoint GET /referrals/list con filtros	2h
MCH-TT-225-03	Componente ReferralStats	2h
MCH-TT-225-04	Componente ReferralList con tabla	3h
MCH-TT-225-05	Pagina Referrals.tsx integrando componentes	2h

---

Resumen de Historias de Usuario

ID	Historia	Story Points	Prioridad
MCH-US-220	Codigo de Referido Unico	3	Alta
MCH-US-221	Link Compartible	2	Alta
MCH-US-222	Beneficio al Referido (50%)	5	Alta
MCH-US-223	Recompensa al Referidor (1 mes)	5	Alta
MCH-US-224	Tracking de Conversiones	3	Media
MCH-US-225	Dashboard de Referidos	3	Media
Total		21

Entregables

Entregable	Estado	Archivo
referrals.module	Completado	apps/backend/src/modules/referrals/
DDL referrals	Completado	database/schemas/13-referrals.sql
Referrals Page	Completado	apps/frontend/src/pages/Referrals.tsx
Referrals API	Completado	apps/frontend/src/lib/api.ts
Deep linking	Pendiente	Mobile config

Dependencias

Depende de

• MCH-018 (Suscripciones)
• MCH-017 (Notificaciones)

Bloquea a

• Ninguno

Criterios de Aceptacion

• Codigo unico se genera
• Link compartible funciona
• Descuento se aplica al referido
• Mes gratis se acredita al referidor
• Dashboard muestra estadisticas
• Notificaciones se envian (requiere integracion con MCH-017)

Configuracion

{
  referrals: {
    enabled: true,
    referrer_reward: { type: 'free_month', months: 1 },
    referred_discount: { percent: 50, months: 1 },
    code_prefix: 'MCH', // MCH-XXXXX
    expiry_days: 30 // dias para que referido pague
  }
}

---

Ultima actualizacion: 2026-01-17