Levy Cover Fehlerbehebung

Diese Seite behandelt die haufigsten Fehlerzustande fur Levy Cover und wie man sie diagnostiziert. Die meisten Probleme landen in einem von vier Eimern: Konfiguration, Versicherer-Ausfall, Webhook-Lucken oder Buchhaltungs-Drift.

Opt-in-Karte erscheint nie beim Entsperren

Symptom: Fahrer entsperrt ein Fahrzeug, keine Levy Cover Karte erscheint, die Fahrt geht ohne Angebot weiter.

Wahrscheinlichste Ursachen (in der Reihenfolge):

1. Unterkonto-Toggle aus. Prufen Sie /dashboard/insurance/settings. Bestatigen Sie, dass Levy Cover fur das Unterkonto aktiviert ist.
2. Jurisdiktion nicht abgedeckt. Der Entsperrort lost zu einer Region auf, die als available: false in der Matrix markiert ist. Siehe Jurisdiktionsmatrix. Prufen Sie /api/admin/insurance/jurisdiction-matrix fur den aktuellen Matrix-Zustand.
3. Versicherer-Anmeldedaten fehlen. CoverGeniusClient wirft CarrierNotConfiguredError. In Produktion verbirgt das die Karte vollig. Bestatigen Sie, dass COVER_GENIUS_API_KEY und COVER_GENIUS_PARTNER_ID in der bereitgestellten Umgebung gesetzt sind.
4. Versicherer hat keine Stufen zuruckgegeben. Der Versicherer kann ablehnen, auf bestimmte Risikoprofile zu quotieren (z.B. ein brandneuer Fahrer ohne Historie in einer Hochrisikozone). Prufen Sie die Angebotsantwort in Logs.
5. Angebot Zeituberschreitung. Das 2-Sekunden-Budget beim Entsperren ist abgelaufen. Die Fahrt geht ohne das Angebot weiter, was das beabsichtigte Fail-Open-Verhalten ist.
6. Fahrerpraferenz auf "immer ablehnen" gesetzt. Wenn der Fahrer die persistente Praferenz aus geschaltet hat, ist die Karte verborgen, bis er sie wieder aktiviert.

Diagnostische Abfragen:

• SELECT * FROM insurance_offerings WHERE subaccount_id = '<id>' - aktivierte Zeilen bestatigen.
• SELECT * FROM ride_insurance_policies WHERE ride_id = '<ride id>' - bestatigen, ob ein Angebot/eine Bindung tatsachlich stattgefunden hat.
• Logs: nach quote.requested und quote.failed Ereignissen um den Entsperr-Zeitstempel herum suchen.

Bind hat 200 zuruckgegeben, aber keine Police in DB

Symptom: Logs zeigen einen erfolgreichen POST /bookings-Aufruf, aber ride_insurance_policies hat keine Zeile.

Wahrscheinliche Ursachen:

1. Webhook-URL nicht registriert. Einige Versicherer-Integrationen bestatigen die Bindung uber den eingehenden booking.confirmed-Webhook. Wenn dieser Webhook nie ankommt, protokolliert Levy die Anfrage unbegrenzt als in Bearbeitung.
2. Webhook-Signatur fehlgeschlagen. Das Ereignis kam an, aber signature_verified = false. Prufen Sie insurance_webhook_log.
3. Die Bindung war beim Versicherer erfolgreich, aber das Antwort-Payload war fehlerhaft. Selten; normalerweise nur ein Sandbox-Problem.

Losung: Fuhren Sie den Versicherer-Abstimmungs-Cron manuell aus:

curl -X POST https://fleets.levyelectric.com/api/cron/insurance-carrier-reconciliation

Der Cron prufut gebundene Policen gegen den Versicherer und repariert fehlende Fahrt-Versicherungs-Stempel. Wenn der Versicherer die Police als gultig meldet, wird die Zeile mit bound_at zuruckdatiert auf die ursprungliche Bindezeit erstellt.

Pramie nicht auf der Fahrtquittung

Symptom: Der Fahrer hat sich angemeldet, die Police wurde gebunden, aber die Quittung zeigt den Levy Cover Posten nicht.

Ursachen:

1. applyRideInsuranceToPricing wurde nicht aufgerufen. Prufen Sie, dass src/lib/rides/process-ride-completion.ts der Pfad ist, den der Abschluss genommen hat. Die Mobile-End-, Admin-Force-End-, Internal-Ride-End- und Auto-End-Pfade wenden alle diesen Helper an - wenn ein neuer Ride-End-Pfad hinzugefugt wurde, muss er den Helper ebenfalls anwenden.
2. Die Bindung ist passiert, aber der Versicherer hat die Police vor Fahrtende annulliert. Prufen Sie ride_insurance_policies.voided_at. Wenn gesetzt, wurde die Pramie korrekt von der Quittung ausgeschlossen.
3. Stripe Connect Buchung fehlgeschlagen. Die Pramie ist Teil der Fahrtgesamtsumme; wenn die Gesamtsumme nicht erfolgreich gebucht wurde, wird kein Posten generiert. Standard-Zahlungswiederholung gilt.

Diagnose: SELECT id, total_cost, insurance_premium_amount FROM rides WHERE id = '<ride>'. Wenn insurance_premium_amount befullt ist, aber total_cost ihn nicht einschliesst, hat die Abschluss-Pipeline den Helper nicht angewendet.

Schadensfotos konnen nicht hochgeladen werden

Symptom: Fahrer versucht, ein Foto auf dem Schadensbildschirm hochzuladen, der Upload schlagt fehl.

Ursachen:

1. insurance-claims Storage Bucket fehlt. Bestatigen Sie, dass der Bucket mit Fahrer-Upload + Read-Richtlinien und Service-Rollen-Management-Richtlinie existiert. Die Migration 20270601120100_09_* erstellt ihn.
2. Signierte URL abgelaufen. Signierte URLs fur Foto-Upload haben eine kurze TTL. Wenn der Fahrer zu lange auf dem Bildschirm gesessen hat, lauft die URL ab. Die App sollte automatisch erneut abrufen; wenn nicht, starten Sie den Schadensfluss neu.
3. Dateigrosse oder Typ abgelehnt. Die Bucket-Richtlinie beschrankt auf Bild-MIME-Typen bis zu 25 MB pro Datei.

Schaden steckt tagelang in submitted fest

Symptom: Ein Schaden wird eingereicht, der Betreiber sieht ihn in der Liste, aber er bewegt sich nie zu under_review oder weiter.

Ursachen:

1. Webhook verpasst. Der Versicherer hat den Schaden bewegt, aber der Webhook hat Levy nie erreicht. Prufen Sie insurance_webhook_log auf fehlgeschlagene Zustellungen um die Zeit der erwarteten Statusanderung herum.
2. Versichererseitige Sachbearbeiter-Verzogerung. Cover Genius prufut typischerweise innerhalb von 48-72 Stunden. Slice kann in einigen Jurisdiktionen langer dauern.
3. Erforderliche Informationen fehlen. Einige Versicherer senden einen claim.requires_info-Webhook, der zusatzliche Daten anfordert. Prufen Sie das Schadensdetail auf einen "Versicherer anfordernd"-Vermerk.

Aktion: Betreiber konnen an Levy-Support eskalieren, der den Versicherer uber den Partnerkanal verfolgen kann. Betreiber konnen weder Einspruche einreichen noch Statusanfragen direkt beim Versicherer stellen.

Webhook-Signaturfehler

Symptom: insurance_webhook_log zeigt signature_verified = false.

Ursachen:

1. COVER_GENIUS_WEBHOOK_SECRET stimmt nicht uberein. Am haufigsten. Holen Sie das aktuelle Geheimnis aus dem Cover Genius Portal erneut ab und aktualisieren Sie die Umgebungsvariable.
2. Die Webhook-URL der falschen Umgebung ist registriert. Sandbox-Ereignisse kommen am Produktions-Endpunkt an oder umgekehrt. Registrieren Sie die korrekte URL erneut im Versicherer-Portal.
3. Replay oder Out-of-Order-Zustellung. Duplikat-Schlussel-Handling auf UNIQUE (carrier, event_id) gibt { duplicate: true } zuruck. Echte Signaturfehler unterscheiden sich von Duplikat-Handling - prufen Sie das Feld signature_verified der Zeile.

Versicherer-Ausfall

Symptom: Angebot-Aufrufe haben Zeituberschreitung, Bind-Aufrufe geben 5xx zuruck, die Opt-in-Karte hort auf zu erscheinen.

Verhalten:

• Angebote Zeituberschreitung -> Fail Open, Fahrt geht ohne Angebot weiter, insurance_offered = false.
• Bestehende gebundene Policen bleiben gultig. Der Versicherer ehrt sie weiterhin, wenn Schaden schliesslich eingereicht werden.
• Ausstehende Schaden sitzen in ihrem aktuellen Status, bis der Versicherer sich erholt und sie verarbeitet.

Aktion:

• Bestatigen Sie den Ausfall auf der Cover Genius Statusseite oder uber den Partnerkanal.
• Kommunizieren Sie an betroffene Betreiber, wenn der Ausfall 1 Stunde uberschreitet.
• Binden Sie Policen wahrend des Ausfalls nicht manuell. Es gibt keinen Pfad, dies sicher zu tun - wenn der Versicherer die Bindung nicht tatsachlich empfangen hat, ist die Fahrt unversichert.

Pramie berechnet, aber Fahrer behauptet, nicht zugestimmt zu haben

Symptom: Fahrer-Support-Ticket sagt "Ich habe der Versicherung nicht zugestimmt, aber ich wurde berechnet."

Diagnose:

• Prufen Sie ride_insurance_policies fur die Fahrt. Wenn eine Zeile mit einem bound_at-Zeitstempel existiert, wurde ein Opt-in-Ereignis erfasst.
• Prufen Sie das Feld policy_wording_version fur den Text, den der Fahrer gezeigt bekam.
• Prufen Sie die persistente Praferenz des Fahrers - "Meine Wahl erinnern" auf akzeptieren gesetzt bedeutet, dass zukunftige Fahrten automatisch binden.

Losung:

• Wenn der Fahrer wirklich nicht zugestimmt hat (ein UI-Bug oder eine veraltete Auto-Inklusiv-Praferenz), folgen Sie dem Pramienruckerstattungs-Pfad. Siehe Pramienruckerstattungen uber die Fahrt.
• Wenn der Fahrer zugestimmt hat, aber vergessen hat - der Text war klar und der Bindungsstempel ist intakt - erklaren Sie den Quittungsposten und den Praferenz-Toggle. Keine Ruckerstattung.

Tests schlagen fehl

Die vollstandige Test-Suite liegt unter src/lib/insurance/__tests__/. Es gibt 8 Dateien und 36 Tests. Um sie auszufuhren:

npx vitest run src/lib/insurance/__tests__/ src/lib/rides/__tests__/durable-completion-jobs.test.ts

Haufige Fehler:

• Umgebungsvariablen wahrend Testlaufen gesetzt. Wenn die Test-Umgebung COVER_GENIUS_API_KEY gesetzt hat, kann die Registry den echten Client statt des Mocks auswahlen. Verwenden Sie setCarrierRegistryForTests zum Festlegen.
• Migrations-Drift. Wenn ein Entwickler die Migrationsdateien lokal bearbeitet, konnen die Test-Fixtures vom Schema abdriften. Setzen Sie die lokale DB zuruck und fuhren Sie erneut aus.

---