Vendor Dispatch und Magic-Link Portal

Wenn Ihre internen Techniker einen Task nicht rechtzeitig erreichen koennen - ein abgelegener Defekt, eine Wochenend-Luecke in der Schichtbesetzung oder eine Spezialreparatur, die Sie im Haus nicht abdecken - kann Levy Service die Arbeit an einen externen Vendor uebergeben. Der Vendor bekommt nie einen Levy-Login. Er arbeitet ueber ein Magic-Link-Portal, laedt Fotos und eine Rechnung hoch und verschwindet wieder.

Wann Vendor Dispatch sinnvoll ist

Die zwei haeufigsten Faelle:

1. Geografische Abdeckungsluecke - Ihre Techs sind in Mexico Beach, aber das defekte Moped steht zwei Stunden entfernt in Apalachicola
2. SLA Breach Auto-Escalation - ein critical-Task ist 30 Minuten lang nicht beansprucht, und die Rule Engine eskaliert automatisch an einen nahen Partner

Vendor hinzufuegen

Vendors leben in der Tabelle vendors und werden unter /dashboard/vendors verwaltet.

Einen Task dispatchen

Aus dem Side Drawer eines Tasks klicken Sie Dispatch to Vendor. Ein Dialog oeffnet sich mit:

• Einem Vendor-Picker (gefiltert auf Vendors in Reichweite des Fahrzeugs)
• Einem Freitext-Feld fuer Anweisungen
• Einem Send-Button

Beim Submit:

1. Eine vendor_dispatches-Zeile wird geschrieben
2. Ein Magic-Link-Token wird gemintet und an die Kontakt-E-Mail des Vendors gesendet
3. Hat der Vendor eine Webhook-URL, geht ein signierter POST darauf (HMAC-SHA256 ueber den Body, Secret in vendors.webhook_secret)
4. Die Spalte external_vendor_id des Tasks wird gesetzt; der Side Drawer wechselt auf eine Vendor-Status-Oberflaeche

Der Magic Link ist 7 Tage gueltig und an genau diesen Task gebunden - Vendors koennen damit nicht Ihre anderen Auftraege sehen.

Was der Vendor sieht

Der Vendor oeffnet den Link in einem beliebigen Browser. Er landet unter /api/vendor/[token]/tasks und sieht:

• Task-Beschreibung und Priority
• Letzten bekannten GPS-Standort des Fahrzeugs mit einem "Navigate"-Button
• Foto-Upload-Feld
• Textarea fuer Resolution Notes
• Rechnungsformular (Position + Gesamtbetrag)

Er sieht keine anderen Tasks, keine anderen Fahrzeuge, keine Kundendaten - nichts ausserhalb seines zugewiesenen Dispatchs.

Der Vendor-Ablauf

1. Vendor oeffnet den Magic Link
2. Tippt Accept - Task wechselt von assigned zu in_progress, und Levy bekommt einen Webhook zurueck
3. Faehrt zum Fahrzeug, erledigt die Arbeit
4. Laedt Fotos ueber das Portal hoch
5. Fuellt das Rechnungsformular aus und submitted

Das Submit schreibt eine task_vendor_invoices-Zeile und, sofern STRIPE_SECRET_KEY konfiguriert ist, erstellt eine Stripe Invoice im Namen des Vendors auf Ihrem Account. Die Vendor-Gesamtkosten rollen automatisch in tasks.total_cost_cents.

SLA-getriebene Auto-Eskalation

Die schlagkraeftigste Version von Vendor Dispatch ist die Regel, die ihn automatisch ausloest.

{
  "trigger_type": "time",
  "trigger_config": {
    "cron": "every 5 minutes",
    "condition": "task.status = 'created' AND task.created_at < NOW() - INTERVAL '30 min' AND task.priority IN ('high', 'critical')"
  },
  "action_config": {
    "escalate_to_vendor": "nearest"
  }
}

Richten Sie das ein, und jeder kritische Task, den Ihr internes Team nicht innerhalb von 30 Minuten beansprucht hat, geht automatisch an den naechstgelegenen Vendor in Reichweite. Die meisten Flotten mit 24/7-Betrieb nutzen das fuer Naechte und Wochenenden.

Webhook Payloads

Verdrahten Sie einen Inbound-Webhook unter /api/webhooks/vendor/[vendor_id], kann das System des Vendors Statusupdates und Rechnungen pushen, ohne das Portal zu durchlaufen. Der Endpunkt erwartet eine HMAC-SHA256-Signatur im Header X-Levy-Signature. Unterstuetzte Events: task.accepted, task.in_progress, task.resolved, task.invoice_uploaded.

Das Secret des Vendors liegt in vendors.webhook_secret und wird ueber die Vendor-Edit-Seite rotiert.

Kosten und Abstimmung

Vendor-Rechnungen erscheinen an drei Stellen im Dashboard:

• Task Detail - Invoice-PDF-Link im Side Drawer
• Vehicle Lifetime Cost - in die fahrzeugbezogene Gesamtsumme aufgenommen
• Monthly P&L - eigener "Vendor Cost"-Stacked Bar im Analytics-Chart

Ist Stripe konfiguriert, ist jede Rechnung auch eine echte Stripe Invoice, die der Vendor zahlen kann (oder die Sie ihm zahlen, je nach Seite der Beziehung). Die Stripe Invoice ID liegt zur Abstimmung in task_vendor_invoices.stripe_invoice_id.

Phase-Hinweis

Vendor Dispatch ist das Phase-4-Deliverable. Es ist partnerschaftsabhaengig - die Rule Engine und das Magic-Link-Portal sind fuer jede Flotte live, aber konkrete Vendor-Partnerschaften (im Velofix-Stil) werden je Region verhandelt. Sprechen Sie mit Ihrem Levy CSM, wenn Sie einen Partner in Ihrem Markt brauchen.