rckrdmrd
97f407c661
- Prefijo v2: MCH - TRACEABILITY-MASTER.yml creado - Listo para integracion como submodulo Workspace: v2.0.0 | SIMCO: v4.0.0
214 lines
5.5 KiB
Markdown
214 lines
5.5 KiB
Markdown
# 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
|