Wie die Preisgestaltung funktioniert

Diese umfassende Anleitung erklaert, wie das gesamte Preissystem Fahrtkosten berechnet, von Anfang bis Ende. Das Verstaendnis dieses Ablaufs ist essenziell fuer Betreiber, die Preise effektiv konfigurieren und Abrechnungsprobleme beheben moechten.

---

Konfigurations-Checkliste

Bevor Ihr Preissystem korrekt funktioniert, stellen Sie sicher, dass Sie diese Schritte abgeschlossen haben:

1. Ueberpruefen Sie, dass jedes Fahrzeugmodell existiert fuer das aktive Unterkonto (Standort)
2. Legen Sie eine Basispreisregel fest pro Modell mit Entsperrung, Pause, Minimum und Tagesobergrenze
3. Erstellen Sie Abonnementplaene, die Fahrer ueber die mobile App oder das Dashboard kaufen koennen
4. Veroeffentlichen Sie Fahrtpakete, die vorausbezahlte Entsperrungen, Minuten oder Strecke gewaehren
5. Schichten Sie dynamische Preisregeln fuer zeit-, wetter-, nachfrage- oder modellspezifische Anpassungen
6. Geben Sie Aktionscodes aus und ueberpruefen Sie deren Geltungsbereich (global, Unterkonto, Fahrzeugtyp) und Limits
7. Testen Sie Ihre Konfiguration mit den Preis-API-Tests, um alles End-to-End zu validieren

---

Abrechnungsreihenfolge

Wenn eine Fahrt abgeschlossen wird, durchlaeuft das System diese Phasen, bevor der Kunde belastet wird:

┌─────────────────────────────────────────────────────────────────┐
│                     FAHRT ABGESCHLOSSEN                          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ SCHRITT 1: Basiskosten berechnen                                 │
│   • Entsperrgebuehr, Zeittarif, Pausentarif, Streckentarif       │
│   • Tagesobergrenze des Fahrzeugs durchsetzen                    │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ SCHRITT 2: Stufen-Vorteile anwenden                              │
│   • Kundentreuestufe pruefen                                     │
│   • Entsperr-Rabattprozentsatz anwenden                          │
│   • Minuten-Rabattprozentsatz anwenden                           │
│   • Gratis-Entsperrung nutzen falls berechtigt und angefragt     │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ SCHRITT 3: Abonnement-Kontingente verbrauchen                    │
│   • Aktive Abonnementkaufe finden                                │
│   • Entsperrungen, Minuten, Strecke vom Abonnement abziehen      │
│   • Nutzung fuer Abonnementlimits verfolgen                      │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ SCHRITT 4: Fahrtpakete verbrauchen                               │
│   • Aktive Paketkaufe finden (aelteste zuerst)                   │
│   • Verbleibende Entsperrungen, Minuten, Strecke abziehen        │
│   • Detaillierte Nutzungsereignisse protokollieren               │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ SCHRITT 5: Dynamische Preise anwenden                            │
│   • Zeit/Wetter/Nachfrage-Regeln auswerten                       │
│   • Multiplikatoren und feste Anpassungen anwenden               │
│   • Regeln nach Prioritaetsreihenfolge verarbeiten               │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ SCHRITT 6: Aktionscode anwenden                                  │
│   • Zeitfenster, Geltungsbereiche, Nutzungslimits validieren     │
│   • Mindestausgabeanforderungen pruefen                          │
│   • Prozent- oder Festrabatt anwenden                            │
│   • Max. Rabattobergrenze durchsetzen                            │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ SCHRITT 7: Endanpassungen                                        │
│   • Tagesobergrenze gegen Endsumme erneut pruefen                │
│   • Mindestpreis anwenden (falls kein Abo/Paket genutzt)         │
│   • Bereits erhobene Teilbetraege abziehen                       │
│   • Endbetrag berechnen                                          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     KUNDE BELASTEN                               │
└─────────────────────────────────────────────────────────────────┘

---

Detaillierte Phasenaufschluesselung

Phase 1: Basispreisberechnung

Die erste Phase berechnet Rohkosten basierend auf der Preisregel des Fahrzeugs:

Eingaben:

• Fahrtdauer (aktive Minuten)
• Pausendauer (pausierte Minuten)
• Zurueckgelegte Strecke (Kilometer)
• Fahrzeugpreiskonfiguration

Berechnung:

Basis-Zwischensumme = Entsperrgebuehr
                    + (Aktive Minuten × Minutenpreis)
                    + (Pausen-Minuten × Pausentarif)
                    + (Strecke KM × Km-Tarif)

Durchsetzung der Tagesobergrenze: Wenn die Zwischensumme die Tagesobergrenze ueberschreitet, werden Kosten in dieser Reihenfolge reduziert:

1. Zeitgebuehren zuerst reduziert
2. Pausengebuehren zweitens reduziert
3. Streckengebuehren drittens reduziert
4. Entsperrgebuehr zuletzt reduziert (nur wenn noetig)

Phase 2: Treuestufen-Vorteile

Fuer Kunden mit Treueprogramm-Status koennen erhebliche Rabatte gelten:

Arten von Stufen-Vorteilen:

Anwendungsreihenfolge:

1. Gratis-Entsperrung pruefen - Falls Kunde anfragt und noch Gratis-Entsperrungen hat
2. Entsperr-Rabatt anwenden - Prozentsatz ab (nur wenn Gratis-Entsperrung nicht genutzt)
3. Minuten-Rabatt anwenden - Prozentsatz ab auf alle Zeitkosten

Berechnung:

Wenn Gratis-Entsperrung genutzt:
  Entsperr-Rabatt = Volle Entsperrgebuehr (100 % abgedeckt)
Sonst:
  Entsperr-Rabatt = Entsperrgebuehr × (unlock_discount_pct / 100)

Zeit-Rabatt = Zeitgebuehr × (per_minute_discount_pct / 100)

Stufen-Rabatt-Gesamt = Entsperr-Rabatt + Zeit-Rabatt
Nach Stufe = Basis-Zwischensumme - Stufen-Rabatt-Gesamt

Beispiel (Premium-Stufe):

Basiskosten:
  Entsperrung:    1,50 $
  Zeit:           5,85 $
  Zwischensumme:  7,35 $

Premium-Stufen-Vorteile (20 % Entsperrung, 15 % Zeit):
  Entsperr-Rabatt: 1,50 $ × 0,20 = 0,30 $
  Zeit-Rabatt:     5,85 $ × 0,15 = 0,88 $
  Gesamtrabatt:    1,18 $

Nach Stufe: 7,35 $ - 1,18 $ = 6,17 $

Gratis-Entsperrungs-Beispiel:

Basiskosten:
  Entsperrung:    1,50 $
  Zeit:           5,85 $
  Zwischensumme:  7,35 $

Premium-Stufe (Gratis-Entsperrung genutzt):
  Entsperr-Rabatt: 1,50 $ (voller Betrag)
  Zeit-Rabatt:     5,85 $ × 0,15 = 0,88 $
  Gesamtrabatt:    2,38 $

Nach Stufe: 7,35 $ - 2,38 $ = 4,97 $

Stufenrabatte werden separat fuer Berichte verfolgt und erscheinen auf Kundenquittungen.

Phase 3: Abonnement-Verbrauch

Aktive Abonnements werden vor Fahrtpaketen verbraucht:

Abonnement-Kontingente:

• Enthaltene Entsperrungen (pro Tag oder gesamt)
• Fahrtminuten (pro Tag oder gesamt)
• Pausenminuten (pro Tag oder gesamt)
• Fahrtstrecke (pro Tag oder gesamt)

Limit-Typen:

Zuordnung:

• Unterkonto-spezifische Abonnements werden zuerst abgeglichen
• Globale Abonnements als Fallback
• Aeltestes Abonnement wird zuerst verbraucht

Phase 4: Fahrtpaket-Verbrauch

Verbleibende Kosten nach Abonnements werden durch Fahrtpakete abgedeckt:

Paketinhalte:

• Vorausbezahlte Entsperrungen
• Vorausbezahlte Minuten
• Vorausbezahlte Pausenminuten
• Vorausbezahlte Strecke

Verbrauchslogik:

1. Alle aktiven Paketkaufe des Kunden finden
2. Nach Unterkonto filtern (wenn Paket standortspezifisch)
3. Nach Kaufdatum sortieren (aelteste zuerst)
4. Kontingente verbrauchen bis erschoepft oder Kosten gedeckt

Nutzungsverfolgung: Jeder Verbrauch wird protokolliert mit:

• Fahrt-UUID
• Genutzte Minuten
• Genutzte Strecke
• Entsperrung genutzt (boolean)
• Angewendeter Rabatt (Cent)
• Zeitstempel

Phase 5: Dynamische Preisanpassungen

Nach Paketen werden dynamische Preisregeln ausgewertet:

Regelauswertung:

1. Aktive Regeln fuer das Fahrzeugmodell filtern
2. Zeitfenster pruefen (fuer zeitbasierte Regeln)
3. Wetterbedingungen pruefen (fuer wetterbasierte Regeln)
4. Nachfrageschwellenwerte pruefen (fuer nachfragebasierte Regeln)
5. Nach Prioritaet sortieren (hoechste zuerst)
6. Jede zutreffende Regel sequenziell anwenden

Anpassungsanwendung:

Fuer jede zutreffende Regel:
  Wenn Prozent: Zwischensumme = Zwischensumme × (1 + Prozent/100)
  Wenn Multiplikator: Zwischensumme = Zwischensumme × Multiplikator
  Dann: Zwischensumme = Zwischensumme + feste_anpassung

Phase 6: Aktionscode-Anwendung

Wenn ein Aktionscode angegeben wurde:

Validierungspruefungen:

1. Code existiert und ist aktiv
2. Aktuelle Zeit liegt zwischen gueltig_ab und gueltig_bis
3. Globale Nutzung hat max_uses nicht ueberschritten
4. Kundennutzung hat max_uses_per_customer nicht ueberschritten
5. Unterkonto stimmt ueberein (falls begrenzt)
6. Fahrzeugtyp stimmt ueberein (falls begrenzt)
7. Zwischensumme erreicht Mindestfahrtbetrag

Rabattberechnung:

Wenn Prozent:
  Rabatt = Zwischensumme × (Prozent / 100)
Wenn fest:
  Rabatt = Festbetrag

Wenn max_discount_cents gesetzt:
  Rabatt = MIN(Rabatt, max_discount_cents)

Endrabatt = MIN(Rabatt, Zwischensumme)  // Kann Zwischensumme nicht ueberschreiten

Phase 7: Endanpassungen

Die letzte Phase wendet Schutzbegrenzungen an:

Erneute Pruefung der Tagesobergrenze: Nach allen Rabatten und Zuschlaegen wird die Tagesobergrenze verifiziert:

Wenn Endbetrag > Tagesobergrenze:
  Endbetrag = Tagesobergrenze

Mindestpreis: Wird nur angewendet, wenn keine Abonnement- oder Paketrabatte genutzt wurden:

Wenn Endbetrag < Minimum UND keine_vorteile_genutzt:
  Endbetrag = Minimum

Abzug bereits erhobener Betraege: Fuer Fahrten mit Teilbetraegen (z.B. Reservierungsbetraege):

Faelliger Betrag = Endbetrag - Bereits berechnet

---

Der vollstaendige Berechnungsablauf

Hier ein schrittweises Beispiel mit echten Zahlen:

Szenario: Premium-E-Bike, 25-Minuten-Fahrt waehrend Stoßzeit

Gegeben:

• Fahrzeug: Premium-E-Bike
• Basispreise: 1,50 $ Entsperrung, 0,49 $/Min, 30 $ Tagesobergrenze
• Abonnement: Keines
• Paket: "10-Minuten-Bundle" mit 3 Entsperrungen und 20 verbleibenden Minuten
• Dynamische Regel: "Wochenend-Stoßzeit" +25 % mit 1,00 $ fest
• Aktionscode: "JETZTFAHREN" 20 % Rabatt, max 2,00 $

Schritt 1: Basiskosten

Entsperrung:    1,50 $
Zeit:           25 × 0,49 $ = 12,25 $
Zwischensumme:  13,75 $

Schritt 2: Stufen-Vorteile

Keine Stufen-Vorteile
Zwischensumme:  13,75 $

Schritt 3: Abonnement

Kein aktives Abonnement
Zwischensumme:  13,75 $

Schritt 4: Paket-Verbrauch

Paket deckt: 1 Entsperrung (1,50 $) + 20 Minuten (9,80 $)
Paket-Rabatt: 11,30 $
Verbleibend: 5 Minuten × 0,49 $ = 2,45 $
Zwischensumme:  2,45 $

Schritt 5: Dynamische Preise

Wochenend-Stoßzeit (+25 %): 2,45 $ × 1,25 = 3,06 $
Fester Zuschlag: 3,06 $ + 1,00 $ = 4,06 $
Zwischensumme:  4,06 $

Schritt 6: Aktionscode

JETZTFAHREN 20 %: 4,06 $ × 0,20 = 0,81 $
Begrenzt auf 2,00 $: 0,81 $ (unter Obergrenze)
Zwischensumme:  4,06 $ - 0,81 $ = 3,25 $

Schritt 7: Endanpassungen

Tagesobergrenze-Pruefung: 3,25 $ < 30 $ ✓
Mindestpreis-Pruefung: Uebersprungen (Paket genutzt)
Endbetrag: 3,25 $

---

Konfigurationsszenarien

Szenario 1: Nur Basispreise

Einrichtung:

• Fahrzeug: Standard-Roller
• Entsperrung: 1,00 $
• Pro Minute: 0,39 $
• Keine Pakete, Abonnements oder Aktionen

15-Minuten-Fahrt:

Entsperrung:    1,00 $
Zeit:           15 × 0,39 $ = 5,85 $
Gesamt:         6,85 $

Szenario 2: Volle Paketabdeckung

Einrichtung:

• Paket: "15-Minuten-Boost" - 1 Entsperrung, 20 Minuten

18-Minuten-Fahrt:

Basis:          1,00 $ + (18 × 0,39 $) = 8,02 $
Paket:          Deckt Entsperrung (1,00 $) + 18 Min (7,02 $)
Rabatt:         8,02 $
Faelliger Betrag: 0,00 $

Gesamte Nutzung protokolliert, 2 Minuten verbleiben im Paket.

Szenario 3: Stoßzeit + Aktion kombiniert

Einrichtung:

• Premium-Roller: 1,50 $ Entsperrung, 0,49 $/Min
• Dynamisch: "Wochenend-Stoßzeit" +25 % + 1,00 $ fest
• Aktion: "JETZTFAHREN" 20 % Rabatt, begrenzt auf 2,00 $

25-Minuten-Fahrt:

Basis:          1,50 $ + (25 × 0,49 $) = 13,75 $
Stoßzeit 25 %:  13,75 $ × 1,25 = 17,19 $
Fest:           17,19 $ + 1,00 $ = 18,19 $
Aktion 20 %:    18,19 $ × 0,20 = 3,64 $ → Begrenzt auf 2,00 $
Endpreis:       18,19 $ - 2,00 $ = 16,19 $

---

Haeufig gestellte Fragen

Koennen Pakete und Aktionscodes kombiniert werden?

Ja. Pakete werden zuerst verbraucht und reduzieren die Zwischensumme. Dann werden Aktionscodes auf den verbleibenden Betrag angewendet. Das bedeutet, Kunden erhalten den bestmoeglichen Rabatt.

Was passiert, wenn ich mehrere Pakete habe?

Das System verwendet das aelteste Paket zuerst (FIFO - First In, First Out). Sobald ein Paket aufgebraucht ist, wird das naechste verwendet.

Kann ich sowohl Minuten- als auch Streckenpreise verwenden?

Nein, Sie muessen sich pro Fahrzeugmodell fuer eines entscheiden. Das System verwendet das Feld, das einen Wert groesser als Null hat.

Wie teste ich Preise sicher?

1. Erstellen Sie ein Test-Unterkonto mit Testpreisregeln
2. Nutzen Sie die Preis-API-Tests: npm run test:pricing
3. Ueberpruefen Sie die detaillierte Aufschluesselung in der Testausgabe
4. Testen Sie niemals mit Produktionsdaten

Warum wurde der Mindestpreis nicht angewendet?

Der Mindestpreis wird uebersprungen, wenn Abonnement- oder Paketrabatte genutzt wurden. Kunden mit bezahlten Vorteilen sollten nicht mit Mindestkosten bestraft werden.

Wie interagiert die Tagesobergrenze mit Paketen?

Die Tagesobergrenze gilt fuer Basiskosten vor Paketrabatt. Wenn ein Fahrer ein Paket hat, beruecksichtigt die Obergrenze-Berechnung weiterhin die vollen Basiskosten, aber der Fahrer zahlt nur den Nach-Paket-Betrag.

---

Technische Referenz

Kernfunktionen

Datenbanktabellen

Ergebnisstruktur

Die Funktion buildRidePricing gibt zurueck:

{
  base: {
    unlockFeeCents: number
    timeFeeCents: number
    pauseFeeCents: number
    distanceFeeCents: number
    subtotalCents: number
    dailyCapApplied: boolean
  }
  tier: {
    tierName: string | null
    unlockDiscountCents: number
    timeDiscountCents: number
    freeUnlockUsed: boolean
    totalDiscountCents: number
  } | null
  subscription: {
    discountCents: number
    purchaseId: string
    usageEvent: object
  } | null
  package: {
    discountCents: number
    purchaseId: string
    usageEvent: object
  } | null
  dynamic: {
    subtotalBefore: number
    finalSubtotal: number
    multiplier: number
    adjustmentCents: number
    appliedRules: array
  }
  promo: {
    discountCents: number
    code: string
    promoId: string
  } | null
  totals: {
    baseSubtotalCents: number
    tierDiscountCents: number
    subscriptionDiscountCents: number
    packageDiscountCents: number
    dynamicAdjustmentCents: number
    promoDiscountCents: number
    finalCents: number
    amountDueCents: number
  }
}

---