managarten/apps-archived/uload/docs/features/referral/voucher-implementation-approaches.md

Implementierungsansätze für Voucher-System in uload

Übersicht

Dieses Dokument analysiert verschiedene technische Ansätze zur Integration eines Voucher/Promo-Code-Systems in die bestehende uload-Architektur. Basierend auf der aktuellen Codebasis werden drei Hauptansätze vorgestellt: Minimal MVP, Integrierte Lösung und Enterprise-Ready System.

Aktuelle Architektur-Analyse

Bestehende Komponenten

Datenbank-Struktur (PocketBase):

• links Collection mit Workspace-Support
• users Collection mit Subscription-Status
• clicks Collection für Analytics
• workspaces Collection für Team-Features
• Bereits vorhandene Tag-System-Architektur

Frontend-Stack:

• SvelteKit mit Server-Side-Rendering
• Tailwind CSS für UI
• Form-Actions für Backend-Interaktionen

Business-Logic:

• Link-Limits basierend auf Subscription
• Workspace-basierte Link-Organisation
• Bereits implementierte Short-Code-Generierung

Ansatz 1: Minimal MVP (1-2 Wochen)

Konzept

Schnelle Integration durch Erweiterung der bestehenden Link-Struktur. Voucher-Codes werden als spezielle Links behandelt.

Technische Umsetzung

Datenbank-Erweiterung:

links Collection erweitern:
- voucher_code: string (optional, unique)
- voucher_type: select ['discount', 'feature', 'trial']
- voucher_value: json (z.B. {discount: 30, currency: 'EUR'})
- voucher_valid_until: date
- voucher_max_uses: number
- voucher_current_uses: number
- is_voucher: bool (unterscheidet Voucher von normalen Links)

Implementation:

1. Neues Feld voucher_code in bestehender links Collection
2. Voucher-Validation im bestehenden Redirect-Flow ([...slug]/+page.server.ts)
3. Einfaches Admin-Interface in /my/vouchers

Vorteile:

• Minimale Änderungen an bestehender Architektur
• Nutzt vorhandene Link-Analytics
• Schnelle Time-to-Market
• Keine neuen Dependencies

Nachteile:

• Vermischung von Links und Vouchers
• Limitierte Voucher-Features
• Schwierig zu skalieren

Aufwand:

• Backend: 3-4 Tage
• Frontend: 2-3 Tage
• Testing: 1-2 Tage

Ansatz 2: Dedizierte Voucher-Collections (2-3 Wochen)

Konzept

Saubere Trennung durch eigene Datenstrukturen für Vouchers, aber Integration in bestehende Flows.

Technische Umsetzung

Neue Collections:

vouchers:
- id: string
- code: string (unique, indexed)
- creator_id: relation -> users
- workspace_id: relation -> workspaces
- type: select ['percentage', 'fixed', 'feature', 'trial']
- value: json
- conditions: json (min_amount, eligible_plans, etc.)
- valid_from: date
- valid_until: date
- max_redemptions: number
- max_redemptions_per_user: number
- metadata: json

voucher_redemptions:
- id: string
- voucher_id: relation -> vouchers
- user_id: relation -> users (optional für anonyme)
- session_id: string
- redeemed_at: datetime
- applied_value: json
- referrer_url: string
- ip_hash: string
- user_agent: string

API-Struktur:

/api/voucher/validate - POST - Prüft Voucher
/api/voucher/redeem - POST - Löst Voucher ein
/api/voucher/stats - GET - Analytics für Creator

Frontend-Routes:

/voucher/[code] - Landing Page mit Voucher
/my/vouchers - Voucher-Management
/my/vouchers/create - Neuer Voucher
/my/vouchers/[id]/analytics - Voucher-Analytics

Integration Points:

1. Download-Page zeigt Voucher-Code prominent
2. Session-Storage für Voucher-Persistenz
3. Webhook für App-Integration

Vorteile:

• Saubere Architektur
• Flexibel erweiterbar
• Unabhängige Voucher-Features
• Bessere Performance durch Separation

Nachteile:

• Mehr Entwicklungsaufwand
• Neue Collections zu verwalten
• Komplexere Deployment

Aufwand:

• Backend: 5-7 Tage
• Frontend: 4-5 Tage
• Testing: 2-3 Tage
• Integration: 2 Tage

Ansatz 3: Enterprise-Ready Affiliate System (4-6 Wochen)

Konzept

Vollständiges Affiliate-Management-System mit Vouchers als Kernkomponente.

Technische Umsetzung

Erweiterte Datenstruktur:

affiliates:
- id: string
- user_id: relation -> users
- tier: select ['bronze', 'silver', 'gold', 'platinum']
- commission_rate: number
- lifetime_earnings: number
- current_balance: number
- payout_threshold: number
- payment_details: json (encrypted)
- approved_at: datetime
- suspended_at: datetime

campaigns:
- id: string
- name: string
- affiliate_id: relation -> affiliates
- start_date: datetime
- end_date: datetime
- budget: number
- spent: number
- target_conversions: number
- actual_conversions: number

voucher_templates:
- id: string
- name: string
- code_pattern: string (z.B. "AFFILIATE-{RANDOM}")
- default_value: json
- auto_generate: bool
- requires_approval: bool

conversions:
- id: string
- voucher_redemption_id: relation
- user_id: relation -> users
- event_type: select ['signup', 'purchase', 'subscription']
- event_value: number
- commission_amount: number
- commission_paid: bool
- attributed_to: relation -> affiliates

Advanced Features:

Multi-Touch Attribution:

// Tracking mehrerer Touchpoints
interface AttributionChain {
  touchpoints: [{
    voucher_code: string,
    timestamp: Date,
    weight: number // Anteil an Conversion
  }],
  model: 'first_touch' | 'last_touch' | 'linear' | 'time_decay'
}

Fraud Detection:

interface FraudSignals {
  velocity_score: number, // Zu viele Redemptions zu schnell
  ip_diversity: number, // Verschiedene IPs
  device_fingerprint_matches: number,
  behavioral_anomalies: string[]
}

Real-Time Dashboard:

• WebSocket-Updates für Live-Metriken
• Heatmaps für geografische Verteilung
• Conversion-Funnel-Visualization
• A/B-Test-Results

API-Ecosystem:

/api/v1/affiliates - CRUD für Affiliates
/api/v1/campaigns - Campaign Management
/api/v1/vouchers - Voucher Operations
/api/v1/analytics - Comprehensive Analytics
/api/v1/webhooks - Event Notifications
/api/v1/payouts - Commission Management

Integration-Features:

• Stripe Connect für automatische Auszahlungen
• Slack/Discord-Notifications
• Zapier-Integration
• CSV-Export für Buchhaltung
• API-SDK für Partner

Vorteile:

• Komplett-Lösung für Affiliate-Marketing
• Skaliert auf Enterprise-Level
• Maximale Flexibilität
• Competitive Advantage

Nachteile:

• Hoher initialer Aufwand
• Komplexität in Wartung
• Overhead für kleine Teams
• Längere Time-to-Market

Aufwand:

• Backend: 15-20 Tage
• Frontend: 10-15 Tage
• Testing: 5-7 Tage
• Documentation: 2-3 Tage
• Integration: 3-5 Tage

Empfohlene Strategie: Progressiver Ansatz

Phase 1: Start mit Ansatz 2 (Dedizierte Collections)

Warum:

• Balance zwischen Schnelligkeit und Sauberkeit
• Solide Grundlage für Erweiterungen
• Ermöglicht frühe Validierung

Initiale Features:

• Basic Voucher CRUD
• Simple Redemption-Flow
• Basis-Analytics
• Manual Affiliate-Onboarding

Phase 2: Schrittweise Erweiterung

Nach 1-2 Monaten:

• Automated Code-Generation
• Tiered Affiliate-System
• Enhanced Analytics
• Email-Integration

Nach 3-4 Monaten:

• Commission-Tracking
• Fraud-Detection
• API für Partner
• Advanced Dashboard

Phase 3: Enterprise Features

Nach 6+ Monaten:

• Multi-Touch Attribution
• Automated Payouts
• White-Label Options
• ML-based Optimization

Technische Requirements

Backend-Anforderungen

Neue API-Endpoints:

// Voucher-Validation
POST /api/voucher/validate
Body: { code: string, context?: any }
Response: { valid: boolean, discount?: number, message?: string }

// Voucher-Redemption
POST /api/voucher/redeem
Body: { code: string, session_id: string, user_id?: string }
Response: { success: boolean, applied_value: any }

// Affiliate-Dashboard
GET /api/affiliate/stats
Response: { redemptions: number, earnings: number, ... }

PocketBase-Rules:

// Vouchers Collection Rules
listRule: "@request.auth.id = creator_id || is_public = true"
viewRule: "@request.auth.id = creator_id || code = @request.data.code"
createRule: "@request.auth.id != ''"
updateRule: "@request.auth.id = creator_id"
deleteRule: "@request.auth.id = creator_id"

Frontend-Komponenten

Neue Komponenten benötigt:

VoucherInput.svelte - Code-Eingabe mit Validation
VoucherBadge.svelte - Visuelle Code-Darstellung
VoucherStats.svelte - Analytics-Dashboard
VoucherCreator.svelte - Code-Generator
AffiliateOnboarding.svelte - Partner-Registration
CommissionOverview.svelte - Earnings-Dashboard

Infrastructure

Caching-Strategy:

// Redis/In-Memory Cache für häufige Voucher
const voucherCache = new Map<string, VoucherData>();
const CACHE_TTL = 300; // 5 Minuten

// Cache-Warming für populäre Codes
async function warmCache() {
  const popularVouchers = await getPopularVouchers();
  popularVouchers.forEach(v => voucherCache.set(v.code, v));
}

Rate-Limiting:

// Verhindere Voucher-Brute-Force
const rateLimiter = {
  maxAttempts: 10,
  windowMs: 60000, // 1 Minute
  blockDurationMs: 600000 // 10 Minuten
};

Migration von bestehenden Daten

Falls bereits Referral-Links existieren:

// Migration Script
async function migrateReferralLinks() {
  const referralLinks = await pb.collection('links')
    .getFullList({ filter: 'is_referral = true' });
  
  for (const link of referralLinks) {
    await pb.collection('vouchers').create({
      code: link.short_code.toUpperCase(),
      creator_id: link.user_id,
      type: 'percentage',
      value: { discount: 20 },
      // ... mapping
    });
  }
}

Testing-Strategie

Unit-Tests

// Voucher-Validation Tests
describe('VoucherValidation', () => {
  test('validates expired vouchers', () => {});
  test('checks redemption limits', () => {});
  test('applies conditions correctly', () => {});
});

Integration-Tests

// End-to-End Redemption Flow
describe('VoucherRedemption', () => {
  test('complete redemption journey', async () => {
    // 1. Create voucher
    // 2. Validate voucher
    // 3. Redeem voucher
    // 4. Check analytics
  });
});

Load-Testing

# K6 Script für Voucher-Endpoints
k6 run --vus 100 --duration 30s voucher-load-test.js

Sicherheitsüberlegungen

Voucher-Code-Generation

// Sichere Code-Generation
function generateSecureCode(prefix: string): string {
  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
  const random = crypto.getRandomValues(new Uint8Array(8));
  let code = prefix;
  for (const byte of random) {
    code += chars[byte % chars.length];
  }
  return code;
}

SQL-Injection-Prevention

// Immer Parameterized Queries
const voucher = await pb.collection('vouchers')
  .getFirstListItem(`code = {:code}`, { code: userInput });
// Niemals: `code = "${userInput}"`

Rate-Limiting und Fraud-Detection

// Fraud-Signale
const fraudIndicators = {
  tooManyRedemptions: redemptions > 10 && timeWindow < 3600,
  suspiciousPattern: hasSimilarTimestamps(redemptions),
  knownAbuser: blacklist.includes(ipHash)
};

Monitoring und Analytics

Key Metrics

interface VoucherMetrics {
  // Performance
  redemptionRate: number, // Redemptions / Impressions
  conversionValue: number, // Revenue from Voucher Users
  
  // Quality
  fraudRate: number, // Fraudulent / Total Redemptions
  abuseRate: number, // Multi-Use Attempts / Total
  
  // Business
  customerAcquisitionCost: number,
  lifetimeValue: number,
  returnOnInvestment: number
}

Logging

// Strukturiertes Logging
logger.info('voucher_redeemed', {
  code: voucher.code,
  user_id: user?.id,
  session_id: session.id,
  value: voucher.value,
  timestamp: new Date().toISOString()
});

Zusammenfassung

Für uload empfiehlt sich der progressive Ansatz mit Start bei Ansatz 2 (Dedizierte Collections):

Sofort umsetzbar (Woche 1-2):

• Basis Voucher-System
• Simple Redemption
• Creator-Dashboard

Kurzfristig erweiterbar (Monat 1-2):

• Affiliate-Tiers
• Advanced Analytics
• Fraud-Detection

Langfristig skalierbar (Monat 3+):

• Full Attribution
• Automated Payouts
• Enterprise Features

Dieser Ansatz bietet die beste Balance zwischen schneller Markteinführung und langfristiger Skalierbarkeit, während er perfekt zur bestehenden uload-Architektur passt.