Referral- & Bonus-System (Entwurf)

Konfig: backend/config/referralConfig.js (per ENV überschreibbar).

Kernregeln (konfigurierbar):

• FreePlan: 7 Tage Startlaufzeit.
• Earlybird: bis EARLYBIRD_DEADLINE dürfen alle empfehlen; danach nur zahlende Nutzer (requirePaidPlanAfterEarlybird).
• Qualifizierter NeuUser: <30 Tage alt, verifizierte Mail (optional), ≥10 Sessions/Monat, andere IP als Referrer.
• „Nutzt App“: ≥1 Session/Woche.
• Belohnung: +2 Monate pro qualifizierter Empfehlung; 20 % der Nutzungstage über 90 Tage für andere Apps; Cap 12 Monate/Jahr (außer bei High Usage ≥3 aktive Tage/Woche).
• Missbrauch: max. 3 Referrals/IP/24h.

Backend-Bausteine:

• Models: ReferralEvent, ReferralReward, User-Felder (referralCode, referredBy, plan, referralStats, earlybird).
• Services: services/referralService.js (Code-Generierung, Eligibility, Rewarding).
• Routes: /api/v1/referrals (geschützt):
  • GET /link → Ref-Code/Link, wenn berechtigt.
  • GET /stats → letzte Events/Rewards.
  • POST /session → Session-Event loggen (referee = aktueller User, referrer automatisch aus referredBy).
  • POST /grant → manuelles Gewähren von Monaten (mit Cap-Check).
  • Optional (ENV ENABLE_REFERRAL_PROCESSOR=true): POST /process → manuelles Ausführen der Auswertung.
• Signup: POST /api/v1/auth/register akzeptiert referralCode; setzt referredBy und loggt Signup-Event.

Offen / TODO für spätere Schritte:

• Aggregation-Jobs (monatlich/90-Tage) zur automatischen Qualifikation + Rewarding. Service vorhanden (services/referralProcessor.js), Cron/Job-Anbindung fehlt noch.
• Frontend-Hooks: Ref-Link Anzeige, Session-Pings, Reward-UI.
• Payment-Signal-Integration, wenn verfügbar (Stripe etc.).

Jobs ausführen:

• Manuell: node backend/scripts/runReferralProcessor.js (nutzt .env oder MONGO_URI).
• Server-seitig: ENABLE_REFERRAL_CRON=true setzt tägliche Ausführung (02:15) in backend/server.js.