Guthabensystem (Credits)

Uebersicht

Das Guthabensystem in TanStack Ship bietet eine flexible Treuewaehrung, die Benutzerengagement und Kundenbindung foerdert. Benutzer verdienen Credits durch verschiedene Aktionen — Einladungen, Aktionen, Kaeufe und Engagement-Meilensteine — und koennen sie fuer Abonnements, Funktionen oder Produkt-Upgrades ausgeben.

Als Teil der TanStack Ship Plattform ist das Guthabensystem mit Zuverlaessigkeit als Kernprinzip konzipiert. Es implementiert eine doppelte Buchhaltung mit idempotenten Operationen und vollstaendiger Pruefprotokollierung, um sicherzustellen, dass jede Guthabenbewegung genau erfasst und niemals dupliziert wird.

Guthabenfluss

Das Guthabensystem folgt einem strengen doppelten Buchhaltungsmodell, bei dem jede Ausgabe und jeder Verbrauch als unveraenderliche Transaktion aufgezeichnet wird:

Design-Philosophie

Das Guthabensystem basiert auf drei Kernprinzipien finanzieller Zuverlaessigkeit:

• Doppelte Buchhaltung — Jede Guthabenbewegung wird als Transaktion mit Soll- und Haben-Eintrag aufgezeichnet. Das Guthaben eines Benutzers wird nie als einzelner Wert gespeichert, sondern als Summe aller Transaktionen abgeleitet, was mathematische Integritaet gewaehrleistet. Im Gegensatz zu LoyaltyLion oder Yotpo — die als Drittanbieter-SaaS-Plattformen operieren und API-Aufrufe fuer Kontostandsabfragen sowie Webhook-Integrationen fuer ereignisbasierte Belohnungen erfordern — ist unsere Guthaben-Engine direkt in Ihre Datenbank eingebettet, mit null externer Latenz bei Kontostandspruefungen und vollstaendiger transaktionaler Integritaet bei allen Vorgaengen.
• Idempotente Operationen — Jede Guthabenoperation traegt einen eindeutigen Idempotenzschluessel. Bei Wiederholung derselben Operation erkennt das System das Duplikat und gibt das vorhandene Ergebnis zurueck.
• Pruefpfad-First-Design — Alle Guthabenbewegungen werden mit vollstaendigen Metadaten protokolliert: Zeitstempel, Betrag, Grund, referenzierte Entitaet und ausfuehrender Benutzer.

Kernfunktionen

Konfigurierbare Guthabenplaene

Guthabenplaene legen fest, wie Credits an Benutzer vergeben werden. Drei Plantypen werden unterstuetzt:

• Einmalige Plaene — Einmalige Guthabenvergabe mit festem Betrag, geeignet fuer Willkommensboni oder einmalige Aktionen
• Wiederkehrende Plaene — Periodische Guthabenvergabe (monatlich, jaehrlich) mit automatischer Verlaengerung im konfigurierten Intervall
• Dauerhafte Plaene — Unbegrenzte wiederkehrende Credits, die nie verfallen, ideal fuer lebenslange Treueprogramme

Jeder Plan gibt den Guthabenbetrag, das Intervall (bei wiederkehrenden Plaenen) und optionale Ablaufregeln an. Plaene koennen ueber das Admin-Dashboard aktiviert oder deaktiviert werden, ohne historische Daten zu verlieren.

Ausgabe- & Verbrauchs-Engine

Guthabenoperationen folgen einem strengen doppelten Buchhaltungsmodell:

• Ausgabe — Erstellt einen positiven Transaktionsdatensatz, der den Kontostand des Benutzers erhoeht
• Verbrauch — Erstellt einen negativen Transaktionsdatensatz, der den Kontostand des Benutzers verringert
• Kontostandsberechnung — Der aktuelle Kontostand wird als Summe aller Transaktionen berechnet
• Idempotenz — Jede Operation traegt einen eindeutigen Idempotenzschluessel, der sicherstellt, dass Wiederholungen nicht zu doppelter Verarbeitung fuehren

Die Guthaben-Engine validiert alle Operationen in Echtzeit und ueberprueft, ob der Benutzer vor der Verarbeitung einer Verbrauchsanfrage ueber ausreichend Guthaben verfuegt.

Zuverlaessigkeit & Datenintegritaet

Funktionen fuer Unternehmenszuverlaessigkeit:

• Idempotenzschluessel — Verhindert doppelte Verarbeitung durch Webhook-Wiederholungen, Netzwerkprobleme oder clientseitige Wiederholungen
• Transaktionsprotokollierung — Jeder Vorgang wird mit Zeitstempel, Betrag, Grund und referenzierter Entitaet protokolliert
• Kontostandsvalidierung — Echtzeit-Kontostandspruefungen verhindern Ueberausgaben mit atomaren Datenbanktransaktionen
• Pruefpfad — Vollstaendige Historie aller Guthabenbewegungen fuer Debugging, Compliance und Kundensupport
• Atomare Operationen — Ausgabe und Verbrauch sind in Datenbanktransaktionen gekapselt, um Wettlaufsituationen zu verhindern

Einladungsbelohnungsintegration

Das Guthabensystem integriert sich mit dem Einladungsmodul fuer Empfehlungsbelohnungen:

1. Wenn ein geworbener Benutzer ein Abonnement abschliesst, erhaelt der Einladende eine Guthabenbelohnung (konfigurierbarer Betrag pro Kampagne)
2. Der neue Benutzer erhaelt einen Willkommensguthabenbonus zur Foerderung des ersten Engagements
3. Beide Transaktionen werden mit eindeutigen Idempotenzschluesseln protokolliert
4. Das System behandelt Grenzfaelle — doppelte Empfehlungsversuche, Selbstempfehlungsverhinderung und Belohnungslimits

Clientseitiges Guthabenkomponenten-Beispiel:

import { useQuery } from '@tanstack/react-query'

export function CreditBalance() {
  const { data } = useQuery({
    queryKey: ['credit-account'],
    queryFn: () =>
      fetch('/api/credits/balance').then((r) => r.json()) as Promise<{
        balance: number
        transactions: Array<{ id: string; amount: number; reason: string }>
      }>,
  })

  return (
    <div className="rounded-lg border p-4">
      <div className="mb-3">
        <p className="text-sm text-muted-foreground">Guthaben</p>
        <p className="text-3xl font-bold">{data?.balance.toLocaleString() ?? '—'}</p>
      </div>
      <p className="mb-2 text-xs font-semibold uppercase text-muted-foreground">Letzte</p>
      {data?.transactions.slice(0, 3).map((tx) => (
        <div key={tx.id} className="flex justify-between py-1 text-sm">
          <span>{tx.reason}</span>
          <span className={tx.amount > 0 ? 'text-green-600' : 'text-red-600'}>
            {tx.amount > 0 ? '+' : ''}{tx.amount}
          </span>
        </div>
      ))}
    </div>
  )
}

Best Practices

Idempotenzschluessel-Verwaltung

Generieren Sie immer eindeutige Idempotenzschluessel fuer jede Guthabenoperation. Verwenden Sie eine Kombination aus Entitaetstyp, Entitaets-ID und Operationstyp (z. B. invitation_reward_{invitation_id}), um Eindeutigkeit sicherzustellen.

Kontostandsueberpruefung

Zeigen Sie Benutzern Echtzeit-Kontostaende an, ueberpruefen Sie aber immer die ausreichende Deckung auf dem Server, bevor Sie einen Verbrauch verarbeiten. Clientseitige Kontostandspruefungen sind nur fuer die Benutzererfahrung.

Angemessener Umgang mit unzureichendem Guthaben

Wenn einem Benutzer nicht genuegend Credits fuer einen Kauf zur Verfuegung stehen, geben Sie klares Feedback mit dem aktuellen Kontostand und dem erforderlichen Betrag. Bieten Sie alternative Zahlungsmethoden an.

Regelmaessige Audit-Abstimmung

Fuehren Sie regelmaessig Abstimmungsberichte durch, die das Transaktionsprotokoll mit den erwarteten Kontostaenden vergleichen. Das Admin-Dashboard stellt Werkzeuge fuer diese Analyse bereit.

Haeufig gestellte Fragen

Wie verdienen Benutzer Credits? Credits koennen auf mehreren Wegen verdient werden: Einladungsempfehlungen, Werbekampagnen, monatliche Treueboni, manuelle Admin-Anpassungen und Guthabenvergabe-Angebote.

Koennen Credits verfallen? Ja. Guthabenplaene koennen optional Ablaufregeln haben. Administratoren koennen konfigurieren, dass Credits nach einer festgelegten Zeitspanne verfallen (z. B. 12 Monate nach Ausgabe).

Wie werden Credits fuer Kaeufe verwendet? Waehrend des Checkouts koennen Benutzer "Mit Credits bezahlen" als Alternative zur Kreditkarte waehlen. Das System berechnet den Stripe-Zahlungsbetrag abzueglich des angewendeten Credit-Werts.

Was passiert, wenn das Abonnement eines Benutzers rueckerstattet wird? Wenn ein mit Credits gekauftes Abonnement rueckerstattet wird, werden die entsprechenden Credits dem Konto des Benutzers durch eine Stornotransaktion gutgeschrieben.

Kann ich Benutzer-Credits manuell anpassen? Ja. Das Admin-Dashboard bietet ein Guthabenanpassungswerkzeug zur manuellen Vergabe oder Abziehung von Credits. Alle Anpassungen werden im Pruefpfad protokolliert.

Sind Guthabenoperationen threadsicher? Ja. Die Guthaben-Engine verwendet Datenbanktransaktionen mit Sperren auf Zeilenebene, um sicherzustellen, dass gleichzeitige Operationen keine Wettlaufsituationen oder Kontostandinkonsistenzen verursachen.

Wie verhindert das System Betrug? Das System setzt mehrere Betrugspraeventionsmassnahmen durch: Ratenbegrenzung bei Guthabenoperationen, Duplikaterkennung ueber Idempotenzschluessel und Protokollierung verdaechtiger Aktivitaeten.

Konfiguration

Verwalten Sie Guthabenplaene und -konten ueber das Admin-Dashboard:

• /dashboard/admin/credits/plans — Guthabenplaene erstellen und verwalten (einmalig, wiederkehrend, dauerhaft)
• /dashboard/admin/credits/accounts — Benutzerguthaben und Transaktionshistorie anzeigen
• /dashboard/admin/credits/transactions — Vollstaendiges Transaktionsprotokoll mit Filterung und Suche
• /dashboard/admin/credits/debug — Debug-Panel zur Fehlerbehebung bei Guthabenoperationen

Es werden keine zusaetzlichen Umgebungsvariablen ueber die Standard-Datenbankkonfiguration hinaus benoetigt.

Integrationspunkte

Das Guthabensystem integriert sich mit den folgenden TanStack Ship Plattformmodulen:

• Abrechnung — Credits koennen als alternative Zahlungsmethode waehrend des Stripe-Checkouts verwendet werden
• Einladungssystem — Empfehlungsbelohnungen werden als Credits mit konfigurierbaren Betraegen pro Kampagne vergeben
• Kampagnenangebote — Guthabenvergabe-Angebote gewaehren Punkte auf Benutzerguthaben bei qualifizierenden Kaeufen
• UTM-Kampagnen — Verkehrsquellenspezifische Aktionen koennen Guthabenboni enthalten
• Benutzer-Dashboard — Benutzer sehen ihren Guthabenstand, ihre Transaktionshistorie und verfuegbare Guthabenplaene
• Admin-Dashboard — Umfassende Guthabenverwaltungsoberflaeche mit Pruefwerkzeugen