Fehlerbehebung

Die kanonische Checkliste, wenn etwas im Compliance-Stack nicht funktioniert. Geht durch MDS-Endpunkte, den Policy-Ingester, Echtzeit-Durchsetzung, das Stadt-Portal und Digest-E-Mails -- in dieser Reihenfolge, weil das grob der Abhaengigkeitsbaum ist.

MDS-Endpunkte

401 bei jeder Anfrage

Symptome: Stadt-Validator gibt 401 Unauthorized auf /vehicles/status zurueck.

Pruefungen:

1. Das Bearer-Token fehlt in Authorization: Bearer <token>. Staedte fuegen das Token manchmal ohne Bearer -Praefix ein.
2. Das Token wurde widerrufen. Einstellungen -> API & Integrationen -> MDS-Tokens oeffnen und Aktivierung bestaetigen.
3. Das Token gehoert zu einem anderen Subaccount. Ein Token pro Subaccount; Staedte, die versehentlich ueber mehrere Zustaendigkeiten testen, sehen das.

Validator scheitert am version-Feld

Symptome: mds-provider-validator beklagt, dass der Response-Envelope eine andere Version als 2.0.1 meldet.

Pruefungen: bestaetigen, dass src/lib/mds/v2/response.ts const MDS_VERSION = '2.0.1' hat. Falls ein veralteter Build deployed wurde, erneut deployen.

MDS-JWT-Header fehlt in einer Antwort

Symptome: Stadt erwartet MDS-JWT: <jwt> in jeder Antwort und der Header fehlt.

Pruefungen:

1. mds_jwks_keys hat keine Zeile mit is_active = true fuer den Subaccount. /api/mds/<subaccountId>/.well-known/jwks.json einmal aufrufen, um eine Lazy-Mint zu erzwingen, dann erneut versuchen.
2. Das Schluesselpaar wurde generiert, aber die aktive Zeile hat private_key_pem beschaedigt (selten -- meist eine fehlgeleitete manuelle Bearbeitung). Sentry auf MDS sign failed-Breadcrumbs pruefen.

current_speed_limit_kph immer 0

Symptome: Fahrzeuge melden current_speed_limit_kph: 0, selbst wenn sie in einer Zone sein sollten.

Pruefungen:

1. Das Fahrzeug hat keine letzte bekannte GPS-Position. vehicles.last_lat/last_lng und vehicles.last_seen pruefen.
2. Keine Betreiberzone oder Policy-Geofence enthaelt den Punkt. SELECT * FROM zones_containing_point('<subaccountId>', <lat>, <lng>) ausfuehren und bestaetigen, dass mindestens eine Zeile zurueckkommt.
3. Der aktive Regeltyp ist no_ride statt speed -- das ist eine Sperre, kein Tempolimit. Die Statuszeile sollte is_disabled = true zeigen.

Policy-Ingester

Policy-Feed der Stadt liefert 404

Symptome: Audit-Log-Eintraege mit status = 'failed' und errors mit HTTP 404.

Pruefungen:

1. Die URL in mds_jurisdictions.policy_feed_url ist falsch. Im Terminal testen: curl -i <url>. Staedte aendern Pfade manchmal zwischen provisorischen und produktiven Endpunkten.
2. Das Auth-Token ist abgelaufen. Mit und ohne Token versuchen, um zu isolieren.

Feed validiert, aber keine policy_geofences

Symptome: Audit zeigt status = 'success' und mds_policies-Zeilen existieren, aber policy_geofences ist leer.

Pruefungen:

1. Jede Regel referenziert Geografien, die die Stadt nicht veroeffentlicht hat. errors in der Audit-Zeile pruefen -- nicht aufgeloeste Geografie-IDs sind dort gelistet.
2. Die Stadt veroeffentlichte Policies fuer einen Fahrzeugtyp, den Ihre Flotte nicht betreibt. Bestaetigen, dass die vehicle_types der Regeln mindestens einen Ihrer Typen enthalten.

Dieselbe Policy taucht in jedem Diff auf

Symptome: Jeder Poll-Diff zeigt dieselbe Policy in modified, selbst wenn nichts Wesentliches geaendert wurde.

Pruefungen:

1. Die Stadt regeneriert die Feed-Payload bei jeder Anfrage (andere published_date, Whitespace, Sortierung). Der sha256-Kurzschluss feuert nur bei bytegleichen Payloads. Bitten Sie die Stadt, ihre Serialisierung zu stabilisieren.
2. Die Stadt aendert published_date automatisch -- einige CMS tun das. Das Diff ist harmlos, aber laut; kann im Audit-Log-UI gefiltert werden.

Aktivierung feuert nie

Symptome: Eine Policy ist pending, start_date ist vorbei, aber der Status flippt nie auf active.

Pruefungen:

1. Der mds-policy-activate-Cron scheitert. /api/cron/mds-policy-activate in den Vercel-Cron-Logs pruefen.
2. Das start_date ist Ortszeit, aber als UTC ohne Konvertierung gespeichert. Der Cron vergleicht mit now() UTC; eine falsche Zeitzone im Feed laesst Aktivierung viel spaeter feuern als erwartet.

Echtzeit-Durchsetzung

Regel aktiviert, aber keine Befehle gesendet

Symptome: mds_policies.status = 'active', aber policy_enforcement_events hat keine Zeilen fuer die Regel.

Pruefungen:

1. Keine Fahrzeuge sind in der Geometrie. SELECT COUNT(*) FROM vehicles WHERE ST_Contains('<rule_geometry>', ...) -- wenn 0, gibt es nichts durchzusetzen.
2. Alle Fahrzeuge haben veraltetes GPS (>5 min). Der Skip ist beabsichtigt. Nach error = 'stale_gps'-Ereignissen in der Tabelle suchen.
3. Die Fahrzeuge haben keine verknuepfte iot_devices-Zeile. Uebersprungen mit error = 'no_iot_device'.

Befehle gesendet, aber Fahrzeuge bremsen nicht

Symptome: policy_enforcement_events zeigt command_sent_at, aber kein command_ack_at, und das Fahrzeug faehrt weiter voll.

Pruefungen:

1. OEM offline oder im Schlaf. Fahrzeug im Dashboard oeffnen und last_seen pruefen.
2. Das falsche Befehlsformat erreichte den OEM. command_response auf Fehlercode pruefen -- die meisten OEMs liefern Ablehnungscodes im Klartext.
3. Das IoT-Passwort des Fahrzeugs ist falsch. Bestaetigen, dass iot_devices.iot_password zu dem passt, was der OEM erwartet (siehe OKAI-Integration, Queclink-Integration usw.).

Sub-Flotte sieht Befehle, eine andere nicht

Symptome: OKAI-Fahrzeuge folgen der Slow-Zone, Segway-Fahrzeuge nicht (oder umgekehrt).

Pruefungen:

1. Der OEM-spezifische Versender-Zweig fehlt oder ist veraltet fuer den OEM. Bestaetigen, dass src/lib/iot/dispatch.ts einen Case fuer diesen OEM hat und das Befehlsformat zur Protokollversion des OEM passt.
2. Segway-BLE-Relay-Latenz -- der Befehl wurde gesendet, aber noch nicht bestaetigt, weil das Fahrzeug weit weg von einem Telefon ist. Das ist eine bekannte Luecke; Latenz fuer Segway kann 30 Sekunden ueberschreiten.

Stadt-Portal

Magic-Link gibt "ungueltiges Token" zurueck

Symptome: Kontakt klickt den gesendeten Link und landet auf einer Fehlerseite.

Pruefungen:

1. Das Token ist abgelaufen (15 Minuten). Ein neues anfordern lassen.
2. Die Kontaktzeile wurde geloescht oder portal_access = false.
3. Zwei Links wurden in kurzer Folge erzeugt; der erste verbraucht, der zweite scheint veraltet.

Magic-Link-E-Mail kommt nie an

Symptome: Kontakt sendet das Formular, sieht die "E-Mail pruefen"-Nachricht, keine E-Mail kommt.

Pruefungen:

1. Spam-Ordner.
2. Die E-Mail entspricht nicht einer city_contacts-Zeile exakt (case-insensitive). Die Zeile pruefen.
3. Die E-Mail-Infra hat den Versand abgewiesen (Sentry hat den Bounce). Nach Spam-Filter-Triggern in Betreff oder Body suchen.

Portal zeigt keine Fahrzeuge, obwohl Flotte eingesetzt ist

Symptome: Stadtkontakt loggt sich ein, die Flottenkarte ist leer.

Pruefungen:

1. mds_jurisdictions.bbox ist falsch -- zu eng oder zeigt woanders. Gegen eine Kartenvorschau bestaetigen.
2. Alle Fahrzeuge haben null last_lat/last_lng. Mindestens eines pruefen.

Digest-E-Mails

Digest kam nicht am erwarteten Tag an

Symptome: Stadtkontakt erwartete einen Montags-Woche-Digest, bekam keinen.

Pruefungen:

1. last_digest_sent_at liegt in der aktuellen Woche -- der Cron entschied, dass das Kadenzfenster noch nicht abgelaufen ist. Wahrscheinlich feuerte ein vorheriger Digest im selben Fenster.
2. Der Cron lief gar nicht. Vercel-Cron-Logs fuer /api/cron/compliance-digest.
3. Der Digest feuerte, aber der E-Mail-Versand erzeugte einen Fehler. city_compliance_reports pruefen -- wenn die Zeile existiert, aber keine E-Mail ankam, ist der Fehler downstream.

Digest zeigt eine fehlgeschlagene Bedingung, die Sie bereits behoben haben

Symptome: Scoreboard im Digest zeigt rot bei complaint_sla, obwohl alle Beschwerden beantwortet wurden.

Pruefungen:

1. Der Digest deckt eine abgeschlossene Periode ab (gestern fuer daily, vergangene Woche fuer weekly). Er wird nicht rueckwirkend neu berechnen. Das aktuelle Scoreboard unter /dashboard/compliance/{id} ist die Live-Sicht.

PDF-Anhang fehlt bei Monats-Digest

Symptome: Monats-Digest kommt an, aber pdf_url ist null und der Anhang fehlt.

Pruefungen:

1. Der PDF-Renderer erzeugte einen Fehler. Sentry hat den Stack-Trace. HTML/Text-Body feuert weiterhin; das PDF ist Best-Effort.

Wo in der Datenbank zu suchen ist

Wenn alles andere fehlschlaegt

Schreiben Sie an support@levyelectric.com mit:

• Subaccount-ID
• Zustaendigkeits-Slug
• Den Audit-run_id, falls das Problem im Ingester liegt
• Die policy_enforcement_events.id, falls das Problem in der Durchsetzung liegt
• Die city_compliance_reports.id, falls das Problem in einem Digest liegt

Wir haben direkten Zugang zu Logs und koennen den Fehler in der Regel innerhalb einer Stunde lokalisieren.