Saltar al contenido principal

Programa de referidos — Referencia técnica

← Volver a Programa de referidos

Construido de cero (Fase D.7 / roadmap 4.15). Antes de esto, el único rastro de referidos era una línea de JSDoc desactualizada @method processReferralBonus sin ninguna implementación detrás.

Dónde vive esto​

Backend

Frontend

Checklist de implementación técnica​

  • referralCode / referredById en users; código único generado perezosamente
  • Query myReferralInfo — ReferralPage.tsx
  • referralCode en UserRegistrationInput; capturado desde ?ref= y aplicado al registrarse
  • Bonos configurables en SystemSetting, editables desde la página de configuración de pagos del admin
  • Bonos otorgados por la vía estándar de transacción de monedas (reward / relatedType referral), idempotente
  • Referente notificado (notificación referral_bonus) cuando se otorga su bono
  • Comisión de afiliado sobre compras recurrentes — no construido (solo bono único de registro)

API de GraphQL​

# El código de referido + estadísticas de quien llama (el código se genera en el primer acceso)
query MyReferralInfo {
  myReferralInfo { referralCode referralCount totalEarnedCoins }
}

# El input de registro ganó un referralCode opcional
mutation Register($input: UserRegistrationInput!) {
  register(input: $input) { token user { id username } }
}
# input: { username, email, password, dateOfBirth, referralCode: "ABCD2345" }

Notas de diseño​

  • Bono único de registro, no una comisión recurrente. La recompensa se otorga una vez, cuando un usuario referido se registra. Una comisión de afiliado real (un porcentaje de todo lo que el usuario referido compre después) necesitaría hooks en cada flujo de compra (compras de monedas, suscripciones, tienda, posts exclusivos) y su propia contabilidad — deliberadamente fuera de alcance en esta pasada; el modelo registra referredById de forma permanente, así que ese dato está disponible si se agrega la comisión más adelante.
  • Desactivado por defecto. Ambos montos de bono son 0 por defecto, así que no se mueve ninguna moneda hasta que un administrador los fije — el mismo patrón "configurable por admin, desactivado por defecto" que verificationPriceCoins.
  • Idempotente y best-effort. referredById solo se fija una vez (un segundo intento de registro con un código es un no-op), y todo el paso de aplicación está envuelto para que un fallo de referido nunca bloquee un registro exitoso.
  • Los bonos usan la vía estándar de monedas. coinTransactionManager.createTransaction({ transactionType: 'reward', relatedType: 'referral' }) maneja el balance + la contabilidad de UserCoinBalance, así que las ganancias por referidos aparecen en el historial de ganancias y cuentan exactamente como cualquier otra recompensa.