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

---
id: EPIC-MCH-023
type: Epic
title: "MCH-023: Programa de Referidos"
code: MCH-023
status: Completado
phase: 6
priority: P2
story_points: 21
created_at: 2026-01-10
updated_at: 2026-01-17
simco_version: "4.0.1"
dependencies:
  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

```typescript
// 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

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

## Configuracion

```typescript
{
  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