Zum Hauptinhalt springen

Dispatch-Eingang und Workflow

Ablauf​

  1. Webhook POST /api/dispatch/inbound (E-Mail) oder POST /api/dispatch/inbound/teams / POST /api/agencyos/v1/dispatch/intake (Teams, Phase 6) legt ein DispatchItem an und stößt die KI-Analyse an (/api/dispatch/[id]/analyze). Teams: Dedup über teamsMessageId, sourceChannel: "teams".

  2. Die KI füllt u. a. vor: Triage (Eingangskategorie, ob das Dev-Team nötig ist, strukturierte Dev-Übergabe, nächste Schritte für MEC, Rückfragen an den Absender) sowie bei redaktionellem Bedarf: Inhaltstyp, Center-Zuordnung (centerIds in Reihenfolge der Plausibilität, centerMatchNote, centerMatchAmbiguous), Kanäle, Zuständigkeit (User-ID), Fristen, Dringlichkeit, Teaser, Social-Caption (ersetzt manuelles Nachhaken und Gmail-Tags). Die Center-Liste im Prompt ist alphabetisch — das Modell darf nicht willkürlich das erste Element wählen; unbekannte UUIDs werden serverseitig verworfen (sanitizeAndSyncCenters). Anschließend sortiert reconcileDispatchAnalyzeCenterIds die Zuordnung anhand von Betreff, Mailtext und E-Mail-Verlauf (gleiche Heuristik wie die Center-Vorselektion) und stuft das Eingangs-Postfach (intakeCenterId) ab, wenn der Inhalt ein anderes Center klar benennt.

  3. „Entwurf erstellen“ erzeugt ContentIntent + ContentDraft (source: dispatch, Status PENDING) — kein direktes News; der Entwurf gehört genau einem gewählten Center. Bei mehreren angehakten Centern legt die Oberfläche fest, für welches Center angelegt wird (Standard: wahrscheinlichstes laut KI-Reihenfolge in centerIds).

  4. Redakteure bearbeiten und genehmigen unter Workflow & Freigaben (/dashboard/workflow). Deep-Link: ?highlight=<contentDraftId>. Dispatch, Freigaben und Kalender sind getrennte Seiten in der Sidebar-Gruppe Redaktionsfluss (Kontextzeile statt Schritt-Leiste). Entwurf löschen: DELETE /api/content/drafts/[draftId] — Session erforderlich; setzt DispatchItem.contentDraftId für diesen Entwurf auf null und löscht den ContentDraft (der verknüpfte ContentIntent bleibt ohne Entwurf bestehen).

  5. Bei Genehmigung legt executeContentDraft die echte Entität an (z. B. News). Anschließend:

    • DispatchItem.status → PUBLISHED
    • bei gesetztem preferredPublishAt: optional ContentSchedule (News, date_range) für den Kalender

    Gast-Freigabe: POST /api/content/drafts/[draftId]/review-link (Session) erzeugt Token; öffentlich GET/POST /api/content/review/[token] — Freigabe ruft dieselbe approveAndExecuteContentDraft-Logik auf wie das Dashboard.

    Felder / Prisma: Es werden nur die in executeContentDraft (apps/dashboard/src/lib/content-draft-execute.ts) explizit gesetzten Spalten befüllt — nicht die vollen Dashboard-Masken. Offer: Entwurf-JSON validFrom/validTo (oder startDate/endDate) → Offer.startDate / Offer.endDate. Job: u. a. type aus type, department oder employmentType; langer Text aus content → requirements (kein Prisma-Feld content am Job). Shop: Das Prisma-Modell hat shopChainId, kein chainSlug; im Entwurf können chainSlug, chainId (UUID der Kette) oder shopChainId stehen — beim Anlegen wird aufgelöst bzw. das Ketten-Feld weggelassen. openingHours als Objekt wird über serializeOpeningHoursForDb als JSON-String gespeichert (nicht "[object Object]"). Freitext bleibt erhalten. Service: Entwurf openingHours ebenfalls JSON-serialisieren wenn nötig. Fehlende SEO-, Hero- oder Shop-Verknüpfungen nach Freigabe in der jeweiligen Content-Bearbeiten-Ansicht ergänzen.

Shop-Öffnungszeiten (MCP / Dashboard)​

ThemaVerhalten
Empfohlenes Format{"regularHours":{"monday":[{"open":"10:00","close":"20:00"}],…},"specialDays":[],"announcement":""} — null = geschlossen
FreitextBleibt in der DB; Dashboard zeigt Hinweis-Banner, überschreibt nicht beim Speichern anderer Felder
SerialisierungserializeOpeningHoursForDb / normalizeShopOpeningHoursForDb in opening-hours-storage.ts — entfernt fehlerhafte Top-Level-Wochentage bei regularHours (alle Schreibpfade)
EditorcoerceShopOpeningHoursForEditor in shop-opening-hours-slots.ts; Öffnungszeiten nur bei Änderung mitsenden
Audit (read-only)node scripts/audit-shop-opening-hours.mjs
Bereinigung (Legacy-Bug)node scripts/fix-shop-opening-hours-legacy-top-level.mjs --dry-run — dann ohne --dry-run

Dispatch-Detail (/dashboard/dispatch/[id])​

  • E-Mail-Adressaten: Beim Intake (Webhook, Gmail-/Microsoft-Sync) werden An/Cc/Bcc/Reply-To in emailParticipants (JSON) gespeichert; die UI zeigt sie in der Nachrichten-Karte. Ältere Fälle ohne JSON nutzen intakeEmail als Fallback unter An. Hilfsmodule: dispatch-email-participants.ts.
  • Status: In der Registerkarte Zuordnung ist jeder Status aus dem Enum wählbar und wird mit Speichern & Zuweisen per PATCH /api/dispatch/[id] gespeichert — inkl. Eingang (INBOX), um einen Fall wieder in die Eingangs-Spalte der Board-Ansicht zu legen.
  • Verwerfen / Wiederherstellen (UX Phase 2):
    • PATCH /api/dispatch/[id] mit { "discard": true } → status: ARCHIVED, aiSuggestion.uiDiscarded (manuell).
    • PATCH /api/dispatch/[id] mit { "restoreFromDiscarded": true } → status: INBOX, Verwerfen-Metadaten zurückgesetzt, aiProcessed: false (erneute Analyse möglich).
  • Menschliche Korrektur: { "suggestedActions": [...], "humanCorrectionAt": "<ISO>", "contentType", "channels", "centerIds", "status": "IN_PROGRESS" } — strukturierte Aktionen wie in dispatch-analyze-actions.ts (shop_unpublish, shop_update, offer_import, news_import, content_draft).
  • Anhänge nachreichen: POST /api/dispatch/[id]/attachments — multipart/form-data, Feld files (mehrere Dateien möglich): Bilder (JPG, PNG, WebP, GIF) oder PDF, je max. 15 MB, max. 10 Anhänge pro Fall. Speichert über persistDispatchAttachments (Center aus intakeCenterId / erstem centerIds-Eintrag). Session + Dispatch-Zugriff (assertDispatchItemAccess). UI in der Nachrichten-Karte: Anhang hochladen; Transfer-Links (WeTransfer, Dropbox, …) nur als Hinweis, kein Auto-Download.
  • Bot-Aktion ausführen: POST /api/dispatch/[id]/execute-suggested-action Body { "actionIndex": 0 } — Session + Dispatch-Zugriff. Unterstützt:
    • shop_unpublish → Shop Status Inaktiv (kein Löschen)
    • shop_update → nur Navigation zum Shop-Editor (editUrl, Query dispatchNewName / dispatchNote) — kein automatisches Umbenennen in der DB
    • offer_import / news_import → Entwurf in Offers/News (status: Entwurf, isActive: false bei Offers), Felder aus draftTitle/draftBody — kein Auto-Publish. Antwort enthält editUrl.
  • AgencyOS/MCP (Phase 3): Gleiche Semantik unter /api/agencyos/v1/dispatch/[id] (discard, restoreFromDiscarded, suggestedActions) und POST …/execute-suggested-action. MCP: cockpit_dispatch_restore, cockpit_dispatch_discard, cockpit_dispatch_set_suggested_actions, cockpit_dispatch_execute_suggested_action.

Steuerzentrale Detail (Phase 3)​

  • Board: /dashboard/redaktionsfluss/steuerung — Karten haben Details-Dialog (Titel, Status-Chips, eine Zeile Kurzfassung; Herkunft/Technik unter Details & Herkunft collapsible; Fußzeile Ablehnen / Bearbeiten / Freigeben).
  • Deep-Link: ?highlight=dispatch:{id} öffnet den Detail-Dialog für den Dispatch-Eintrag.
  • Korrektur nach Ablehnung: Im Bucket Korrektur (abgelehnter Entwurf) zeigt der Detail-Dialog Mit Korrektur neu analysieren — Body POST /api/dispatch/[id]/analyze mit { "humanFeedback": "…" }. Der Ablehnungsgrund aus dem Content-Entwurf wird vorausgefüllt. Gespeichert in aiSuggestion.humanCorrectionNote / humanCorrectionAt. Das blinde Neu analysieren (Register KI & Triage) ignoriert Feedback weiterhin, wenn kein Text mitgeschickt wird.

Backfill historischer ARCHIVED-Einträge (optional)​

Kein automatisches Skript — siehe docs/DISPATCH-ARCHIVED-BACKFILL.md. Auto-Filter (uiDiscarded, discardReason: noise_filter) gilt für neue Imports; Log-Backfill würde falsche Daten riskieren.

KI-Analyse (Dispatch & allgemein)​

  • E-Mail-Inhalt für die KI: POST /api/dispatch/[id]/analyze zieht den Klartext aus bodyText; ist bodyHtml (z. B. Postmark HtmlBody) deutlich länger oder der Plaintext nur ein Stub, wird htmlToPlainText(bodyHtml) verwendet. Sehr lange Mails, Center- und Bearbeiter-Listen werden token-budgetiert gekürzt (Kopf+Schwanz, HTML entfernt) — Ziel ~6 000 Input-Tokens inkl. System-Prompt (dispatch-analyze-prompt.ts). Optional: DISPATCH_ANALYZE_MAX_BODY_CHARS (Standard 24 000, min 4 000, max 80 000) als Obergrenze nur für den Mail-Text. Modell: DISPATCH_ANALYZE_MODEL (Env) überschreibt; sonst gültiges KI-Config-Modell, Legacy gpt-4/gpt-3.5-turbo werden automatisch auf gpt-4o-mini upgegradet (8k-Kontext + kein JSON-Mode). Bei context_length_exceeded ein Retry mit halbiertem Budget. Größere Modelle: bis 8192 Completion-Tokens. In Development liefert die Route bei 500 zusätzlich detail mit der Fehlermeldung.
  • Felder in aiSuggestion (Auszug): intakeCategory, primaryOwner, needsDevTeam, mecNextSteps, questionsForSender, devHandoff (Titel, Problem, URLs, Repro, suspectedLayer, Priorität), centerIds / centerNames (Mehrfachtreffer möglich, Reihenfolge = beste Vermutung zuerst), centerMatchNote (Begründung aus Mail), centerMatchAmbiguous, dazu die bisherigen Content-Felder (type news/offer/event oder none wenn kein Post). Ziel: kleines MEC-Team kann Mails ohne langes Ermitteln zuordnen. Zusätzlich optional customerCommunication: strukturierter Vorschlag für persönliche Rückmeldung an den Absender (Betreff, E-Mail-Text, Kanalhinweis) — wird bei „Entwurf erstellen“ in ContentDraft.data übernommen, damit Betreuer die Beziehungspflege nicht verlieren.
  • Manueller Workflow (ohne neue DB-Spalte): Unter aiSuggestion.workflow — handoffToDev (boolean), handoffToDevAt (ISO, gesetzt beim ersten Aktivieren), handoffNote (optional). Wird über PATCH /api/dispatch/[id] mit Body workflowPatch gespeichert; bei Re-Analyse bleibt workflow durch Merge erhalten (siehe dispatch-workflow.ts).
  • Dispatch-Übersicht: Filter nach Triage-Kategorie (intakeCategory), „Dev nötig / übergeben“ kombiniert needsDevTeam oder workflow.handoffToDev.
  • Explainability (serverseitig): Nach jeder erfolgreichen Analyze berechnet dispatch-analyze-explanation.ts aus vorhandenen KI-Feldern aiSuggestion.analyzeExplanation (lines, subjectVerified, generatedAt) — kein Extra-LLM. UI: aufklappbare Begründung im Dispatch-Detail; Badge „Betreff einbezogen“, wenn der Betreff in der Heuristik in Summary/Center-Note vorkommt. Analyze bricht mit 400 ab, wenn subject leer ist.
  • Korrektur aus der Liste: Postfach-Karte Korrektur → Sheet → POST /api/dispatch/[id]/analyze mit humanFeedback. Optional { "rememberSenderNote": true } speichert den Text in organizations.dispatch_sender_hints (JSON-Map pro Absender-E-Mail, max. 80 Einträge). Gespeicherte Hinweise fließen in künftige Analysen (GET /api/dispatch/[id]/sender-hint für Vorausfüllung).
  • Dispatch: POST /api/dispatch/[id]/analyze — optional JSON-Body { "humanFeedback": "…" } (max. 4000 Zeichen) für Re-Analyse nach menschlicher Korrektur; wird in den User-Prompt eingebettet und als humanCorrectionNote persistiert. Nutzt die globale KI-Konfiguration (getAIConfig) und den zentralen HTTP-Client openAIChatCompletion (apps/dashboard/src/lib/openai-chat.ts). Auth: Dashboard-Session mit Dispatch-Zugriff (dispatch-access.ts), oder interner Header X-Internal-Dispatch mit dem Wert aus DISPATCH_WEBHOOK_SECRET (Fallback internal) — so wie triggerDispatchAnalyze nach Inbound/Manuell-Create. Leere oder relative baseUrl in der DB würden früher zu fetch("/chat/completions") führen – der Client normalisiert auf https://api.openai.com/v1 bzw. OPENAI_API_BASE_URL. Unterstützt das konfigurierte Modell keinen OpenAI-JSON-Mode (response_format: json_object, z. B. älteres gpt-4), wird automatisch ein zweiter Aufruf ohne JSON-Mode ausgeführt; die Antwort wird wie Klartext in JSON geparst (inkl. Markdown-Codeblöcken).
  • Allgemein (Dashboard): POST /api/ai/chat – Session erforderlich, Body: messages[], optional centerId, model, temperature, max_tokens, response_format. Antwort: { success, content }.

Social-Agent Pilot (Phase 3)​

  • Social-Agent Pilot (UI) — Organisation oder Center-Abweichung im Tab Social-Freigabe-Pool. Optional Env DISPATCH_SOCIAL_AGENT_PILOT_CENTER_IDS (Union). Pilot-Center: POST /api/dispatch/[id]/create-draft mit Social reicht automatisch zur Freigabe ein (in_review, Freigabe-Pool nötig). Ohne Pool: autoSubmitSkippedReason: no_review_pool.
  • Konfidenz-Routing (Phase 5): contentQualityScore + contentRiskScore → Gate = min(Q, 1−R). Bei Pilot + Auto-Publish + Gate ≥ Schwellwert: direkte Veröffentlichung; sonst in_review. UI: Center → Social-Freigabe-Pool. Auto-Publish bleibt standardmäßig aus — menschliche Freigabe ist der gewünschte Endpunkt.
  • Auto-Entwurf nach KI (Phase 7): Schalter dispatchAutoDraftEnabled (Org/Center), in der UI unabhängig vom Social-Agent-Pilot bedienbar. Nach Analyze: maybeTriggerDispatchAutoDraft — legt den Entwurf an und reicht ihn zur Freigabe ein (forceReviewOnly), sofern ein Freigabe-Pool existiert. Ohne Pool: autoSubmitSkippedReason: no_review_pool, der Fall bleibt in der Dispatch-Prüfung. Geeignete, bereits gespeicherte Bild-Anhänge gehen als Medien mit — pickStoredDispatchImageUrls sortiert über dispatch-attachment-image-heuristics (Inhaltsmotiv vor Signatur-Logo). Im Dispatch-Detail: Social-Bild-Picker mit Rollen-Hinweis; Korrektur-Chips u. a. „Falsches Bild: Signatur“. Mehrdeutiges Center (center_ambiguous) bleibt in der Prüfung mit Zuordnung im Dispatch-Detail. Lib: dispatch-create-draft.ts. Freigeben/Ablehnen für Berechtigte im Dispatch-Detail; Steuerzentrale nur für Ops-Rollen.
  • Analyze Post-Processing: dispatch-analyze-post-process.ts — nach KI: content_publish + type: none → news/offer/event; Schließungs-Mails: Reopening-Datum nicht als preferredPublishAtIso.
  • Badges: GET /api/dispatch liefert awaitingDraftCount (KI fertig, kein Entwurf); Home-Chip „Entwurf offen“.
  • API: GET /api/dispatch/social-agent-pilot-centers (Session) — Liste der Pilot-Center aus der Env.

Siehe Social-Agent-Modus.

Postfach-Anbindung pro Center und Organisation (Okt 2026)​

  • Schema Center: shopping_centers.dispatch_intake_* — wie bisher.
  • Schema Organisation: organizations.dispatch_intake_email, dispatch_intake_provider (webhook | microsoft_graph | gmail), dispatch_intake_agency_os_mailbox, dispatch_intake_configured_at.
  • Dispatch-Item: intake_email, intake_center_id, intake_organization_id — beim E-Mail-Inbound gesetzt, wenn Empfänger (To/Cc/Postmark/SendGrid) einer konfigurierten Adresse entspricht.
  • Routing: Center-Postfächer haben Vorrang vor Organisations-Postfächern (gleiche Adresse → Center). Bei Center-Match: centerIds wird vorbelegt. Bei Organisations-Match: intake_organization_id gesetzt, centerIds leer — Center-Zuordnung per KI-Triage oder manuell.
  • API: GET/PATCH /api/centers/[centerId]/dispatch-intake · GET/PATCH /api/organizations/[slug]/dispatch-intake (Session: SUPER_ADMIN, CENTER_ADMIN, ORG_MARKETING_MANAGER; Org-Scope geprüft).
  • UI: /dashboard/dispatch → Karte „Postfach-Anbindung“ — Umschalter Center vs. Organisation.
  • Google Workspace (DWD): Service-Account impersoniert Postfach (GOOGLE_GMAIL_SERVICE_ACCOUNT_JSON). Connect: POST …/dispatch-intake/connect-gmail. Cron: POST /api/cron/dispatch-gmail-sync (Bearer CRON_SECRET).
  • Microsoft 365 (delegiert): OAuth im Cockpit — GET …/dispatch-intake/microsoft/connect, Callback /api/dispatch-intake/microsoft/callback. Refresh-Token pro Center/Org in DB. Gleicher Cron importiert Microsoft-INBOX.
  • Legacy AgencyOS: Optionales Feld AgencyOS-Postfach; Graph-Webhooks weiterhin in AgencyOS Mail Interceptor. Siehe Postfach-Anbindung (Nutzer).
  • Dedup: dispatch_item.external_message_id (unique) — Präfix gmail: / graph:.
  • Matching: apps/dashboard/src/lib/dispatch-intake-config.ts — extractInboundRecipientEmails, matchIntakeRecipient.
  • Sichtbarkeit (Queue + Home-Badge): GET /api/dispatch und Dashboard-Home zählen Items mit centerIds/intakeCenterId in erlaubten Centern oder intakeOrganizationId in den scoped Orgs des Users (buildDispatchListWhere in dispatch-access.ts). Org-Intake ohne Center-Vorbelegung erscheint damit in der Queue.
  • Manuell erfasste Mails: POST /api/dispatch setzt intakeCenterId/intakeOrganizationId aus UI-Kontext (Postfach-Anbindung-Center, Org-Filter) bzw. Session-Fallback — sonst fehlt Org-Scope und POST /api/dispatch/[id]/analyze antwortet mit 403. KI-Analyse nutzt sanitizeApiKey (maskierte DB-Keys → ENV-Fallback); ohne Key: HTTP 503 mit Hinweis auf Einstellungen → KI.
  • Strict mode: DISPATCH_INTAKE_STRICT_MATCH=true → 422, wenn mindestens ein Center- oder Organisations-Postfach konfiguriert ist, aber kein Empfänger passt.

Migrationen: 20261001120000_add_dispatch_intake_config_SAFE.sql, 20261001143000_add_org_dispatch_intake_config_SAFE.sql

Umgebung​

  • DISPATCH_WEBHOOK_SECRET – optional, Header X-Dispatch-Secret für E-Mail-Inbound; derselbe Wert (Fallback internal) als X-Internal-Dispatch für serverseitige KI-Trigger (triggerDispatchAnalyze → /api/dispatch/[id]/analyze).
  • DISPATCH_INTAKE_STRICT_MATCH – optional true, Empfänger muss konfiguriertem Center- oder Organisations-Postfach entsprechen.
  • DISPATCH_TEAMS_WEBHOOK_SECRET – optional, Header X-Dispatch-Teams-Secret für Teams-Inbound (Fallback: DISPATCH_WEBHOOK_SECRET).
  • AGENCYOS_TEAMS_DISPATCH_INTAKE_URL + AGENCYOS_TEAMS_NOTIFY_SECRET – optionaler Ops-Hook bei neuem Teams-Dispatch.
  • DISPATCH_SOCIAL_AGENT_PILOT_CENTER_IDS – optionaler Env-Override zum UI-Schalter (Pilot-Center).

Gmail DWD: GOOGLE_GMAIL_SERVICE_ACCOUNT_JSON, optional DISPATCH_GMAIL_ALLOWED_DOMAINS.

Microsoft OAuth (Cockpit + optional AgencyOS): AZURE_AD_CLIENT_ID, AZURE_AD_CLIENT_SECRET, AZURE_AD_TENANT_ID — Redirect …/api/dispatch-intake/microsoft/callback.

Cron: CRON_SECRET für POST /api/cron/dispatch-gmail-sync (Gmail + Microsoft OAuth-Postfächer).

Legacy​

Ältere Einträge können contentDraftId noch als frühere News-ID führen; neue Einträge verwenden die ContentDraft-ID bis zur Freigabe, danach wird die ID ggf. auf die veröffentlichte Content-ID aktualisiert.

Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /developer-guide/dispatch-und-workflow