Pramienruckerstattungen uber die Fahrt

Die Fahrt ist die Quelle der Wahrheit fur jede finanzielle Buchhaltung. Eine Levy Cover Pramienruckerstattung ist zuerst eine Fahrt-Korrektur. Jede Wallet-Gutschrift ist nachgelagert.

Warum diese Regel existiert

Die Pramie ist ein Posten auf der Fahrt. Sie tragt zu rides.insurance_premium_amount, zur Fahrtgesamtsumme, zu net_deposited (nach Abzug des Versicherer-Netto-Pramien-Betrags) und zur Partner-Auszahlungsmathematik (Levy-Provision und Betreiber-Provision) bei.

Wenn das Wallet gutgeschrieben wird, ohne dass die Fahrt angepasst wird:

• Die Buchhaltung der Fahrt denkt immer noch, dass die Pramie behalten wurde.
• net_deposited ist uberhoht.
• Der Partner-Auszahlungs-Cron zahlt dem Betreiber seinen Anteil an einer Pramie aus, die tatsachlich erstattet wurde.
• Die Abrechnungsdatei des Versicherers enthalt immer noch die Pramie.
• Die Steuerabfuhrung wird falsch gemeldet.

Wenn die Ruckerstattung uber die Fahrt lauft, werden alle diese nachgelagerten Effekte durch die bestehende Buchhaltungspipeline korrekt neu berechnet.

Wann eine Pramienruckerstattung gultig ist

Eine Levy Cover Pramienruckerstattung ist nur in diesen Fallen gultig:

1. Die Fahrt hat nie begonnen. Der Motor hat innerhalb von 5 Minuten nach dem Entsperren nicht eingegriffen. Die Opt-in-Karte wurde akzeptiert, aber der Fahrer ist weggegangen.
2. Der Bind-Aufruf ist ruckwirkend fehlgeschlagen. Levy bekam eine 200-Antwort vom Versicherer, aber der Versicherer meldet spater "keine Police aktenkundig" fur diese Fahrt. Der nachtliche Versicherer-Abstimmungs-Cron markiert diese fur Operations.
3. Der Versicherer hat die Police annulliert. Selten. Der Versicherer gibt einen booking.voided-Webhook aus; Levy empfangt ihn, markiert die Fahrt fur Pramienruckerstattung.
4. Ein echter Buchhaltungsfehler. Der Fahrer wurde eine Pramie berechnet, fur die er nicht optiert hat - typischerweise ein UI-Bug oder eine veraltete Praferenz. Diese werden vor jeder Ruckerstattung diagnostiziert.

Pramienruckerstattungen werden nicht ausgelost durch:

• Eine Schadensauszahlung. Die Pramie wurde korrekt eingezogen; der Versicherer zahlt auf eine gultige Police aus. Siehe Versicherer-Auszahlungen und Wallet.
• Einen Fahrer, der nett fragt. Wir erstatten Pramien nicht aus Kulanz.
• Eine abgelehnte Schadensmeldung. Ablehnung bedeutet, dass der Versicherer nicht ausgezahlt hat; sie bedeutet nicht, dass die Police ungultig war.

Die Mechanik

Pramienruckerstattungen delegieren an die bestehende Fahrt-Ruckerstattungs-Infrastruktur. Der Fluss:

1. Operations oder der Abstimmungs-Cron identifiziert eine Pramie, die ruckerstattet werden muss.
2. Levy ruft (oder bereitet einen Aufruf an) /api/admin/insurance/policies/[id]/premium-refund vor.
3. Dieser Endpunkt:
   • Annulliert die Versicherer-Police uber die CarrierClient-Schnittstelle (wenn der Versicherer sie nicht bereits annulliert hat).
   • Gibt einen Request-Body zuruck, den der Aufrufer an die Standard-Fahrt-Ruckerstattungs-API POSTen muss: /api/rides/[ride_id]/refunds mit { destination, mode: "partial", amount: <premium_amount>, reason: "Levy Cover Pramienruckerstattung - <Grund>" }.
4. Die Fahrt-Ruckerstattungs-API:
   • Erfasst eine ride_refunds-Zeile.
   • Ruft das update_ride_net_deposited RPC auf, damit net_deposited korrekt ist.
   • Gibt die Wallet-Gutschrift aus (wenn destination = "wallet") uber den Standard-Ruckerstattungs-Helper, der eine echte ride_refunds-Zeile erfordert.
   • Berechnet Partner-Auszahlungen neu.

Der Pramienruckerstattungs-Helper src/lib/insurance/premium-refund.ts ruft creditWalletForRefund nicht direkt auf. Er gibt den Ruckerstattungs-Request-Body zuruck. Die tatsachliche Wallet-Gutschrift findet innerhalb der Fahrt-Ruckerstattungs-API statt, mit vollstandiger Pruffahigkeit.

Was der Betreiber sieht

Eine Pramienruckerstattung erscheint im Fahrtdetail als:

• Eine ride_refunds-Zeile mit Grund "Levy Cover Pramienruckerstattung - <spezifischer Grund>".
• Ein aktualisiertes net_deposited, das die Pramie ausschliesst.
• Eine Wallet-Gutschrift (wenn das Ruckerstattungsziel das Wallet war), verknupft mit der ride_refunds-Zeile, nicht mit einer insurance_claims-Zeile.

Wichtig ist, dass insurance_premium_amount der Fahrt nicht auf null gesetzt wird. Die ursprungliche Pramie wird weiterhin zu Prufzwecken erfasst; die Ruckerstattung wird als separate Anpassung erfasst. Dies spiegelt wider, wie partielle Tarifanpassungen anderswo auf der Plattform funktionieren.

Versichererseitig annullierte Policen

Wenn der Versicherer eine Police annulliert, erhalt Levy einen booking.voided-Webhook. Der Webhook-Handler:

1. Setzt ride_insurance_policies.voided_at = now().
2. Protokolliert den Annullierungsgrund.
3. Erstellt eine premium_refund_required-Aufgabe fur Operations.
4. Erstattet die Pramie nicht automatisch. Ein Mensch uberprufut die Annullierung und leitet die Ruckerstattung uber die Fahrt-Ruckerstattungs-API.

Der Grund fur den Menschen in der Schleife: Versicherer-Annullierungen konnen durch Betrugssignale, Fahrer-KYC-Fehler oder Policenfehler ausgelost werden. Einige dieser Szenarien rechtfertigen eine Ruckerstattung; einige nicht. Standardmassige automatische Ruckerstattung riskiert die Auszahlung auf betrugerische Annullierungen.

Was Sie absolut nicht tun konnen

Folgende sind direkte Verletzungen von CLAUDE.md und brechen das Buchhaltungsmodell:

• Direktes UPDATE auf customers.wallet_balance, um den Pramienbetrag wieder hinzuzufugen.
• Direktes INSERT in wallet_transactions mit dem Pramienbetrag als manuelle Gutschrift.
• Aufrufen von creditWalletForRefund ohne ride_refund_id und ohne insurance_claim_id und ohne umschliessende Fahrt-Korrektur.
• Einfugen einer insurance_claims-Zeile als Workaround, um eine insurance_claim_payout-Wallet-Gutschrift fur eine wirkliche Pramienruckerstattung zu erstellen. Das sind kategorisch unterschiedliche Ereignisse und das Schema erzwingt die Unterscheidung.

Wenn Sie versucht sind, eines dieser Dinge zu tun, weil die API nicht erreichbar ist, ist die richtige Antwort zu warten oder zu eskalieren, nicht zu umgehen.

Warum diese Leitplanke nicht verhandelbar ist

Dies ist dieselbe Regel, die jeden anderen Ruckerstattungs-Fluss auf der Plattform schutzt: Fahrtgebuhrenkorrekturen, automatische Ruckerstattungen, Rider Score Belohnungen, Schadensgebuhren. Das Muster ist im gesamten Codebase konsistent. Versicherungspramien sind nicht besonders - sie sind ein Posten auf der Fahrt und werden wie ein Posten auf der Fahrt ruckerstattet.

Die vollstandige Leitplanke ist im CLAUDE.md des Projekts unter "Refunds & Fare Adjustments" dokumentiert. Diese Seite ist die versicherungsspezifische Anwendung dieser Regel.

---