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: Pendiente
phase: 6
priority: P2
created_at: 2026-01-10
updated_at: 2026-01-10
simco_version: "3.8.0"
dependencies:
  blocks: []
  depends_on: []
---

# MCH-023: Programa de Referidos

## Metadata
- **Codigo:** MCH-023
- **Fase:** 6 - Crecimiento
- **Prioridad:** P2
- **Estado:** Completado
- **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);
}
```

## 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-10