Dispatch-Eingang und Workflow
Ablauf
-
Webhook
POST /api/dispatch/inbound(E-Mail) oderPOST /api/dispatch/inbound/teams/POST /api/agencyos/v1/dispatch/intake(Teams, Phase 6) legt einDispatchIteman und stößt die KI-Analyse an (/api/dispatch/[id]/analyze). Teams: Dedup überteamsMessageId,sourceChannel: "teams". -
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 (
centerIdsin 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 sortiertreconcileDispatchAnalyzeCenterIdsdie 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. -
„Entwurf erstellen“ erzeugt
ContentIntent+ContentDraft(source: dispatch, StatusPENDING) — kein direktesNews; 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 incenterIds). -
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; setztDispatchItem.contentDraftIdfür diesen Entwurf aufnullund löscht denContentDraft(der verknüpfteContentIntentbleibt ohne Entwurf bestehen). -
Bei Genehmigung legt
executeContentDraftdie echte Entität an (z. B.News). Anschließend:DispatchItem.status→PUBLISHED- bei gesetztem
preferredPublishAt: optionalContentSchedule(News,date_range) für den Kalender
Gast-Freigabe:
POST /api/content/drafts/[draftId]/review-link(Session) erzeugt Token; öffentlichGET/POST /api/content/review/[token]— Freigabe ruft dieselbeapproveAndExecuteContentDraft-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-JSONvalidFrom/validTo(oderstartDate/endDate) →Offer.startDate/Offer.endDate. Job: u. a.typeaustype,departmentoderemploymentType; langer Text auscontent→requirements(kein Prisma-Feldcontentam Job). Shop: Das Prisma-Modell hatshopChainId, keinchainSlug; im Entwurf könnenchainSlug,chainId(UUID der Kette) odershopChainIdstehen — beim Anlegen wird aufgelöst bzw. das Ketten-Feld weggelassen.openingHoursals Objekt wird überserializeOpeningHoursForDbals JSON-String gespeichert (nicht"[object Object]"). Freitext bleibt erhalten. Service: EntwurfopeningHoursebenfalls 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)
| Thema | Verhalten |
|---|---|
| Empfohlenes Format | {"regularHours":{"monday":[{"open":"10:00","close":"20:00"}],…},"specialDays":[],"announcement":""} — null = geschlossen |
| Freitext | Bleibt in der DB; Dashboard zeigt Hinweis-Banner, überschreibt nicht beim Speichern anderer Felder |
| Serialisierung | serializeOpeningHoursForDb / normalizeShopOpeningHoursForDb in opening-hours-storage.ts — entfernt fehlerhafte Top-Level-Wochentage bei regularHours (alle Schreibpfade) |
| Editor | coerceShopOpeningHoursForEditor 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 nutzenintakeEmailals 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 indispatch-analyze-actions.ts(shop_unpublish,shop_update,offer_import,news_import,content_draft). - Anhänge nachreichen:
POST /api/dispatch/[id]/attachments—multipart/form-data, Feldfiles(mehrere Dateien möglich): Bilder (JPG, PNG, WebP, GIF) oder PDF, je max. 15 MB, max. 10 Anhänge pro Fall. Speichert überpersistDispatchAttachments(Center ausintakeCenterId/ erstemcenterIds-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-actionBody{ "actionIndex": 0 }— Session + Dispatch-Zugriff. Unterstützt:shop_unpublish→ Shop Status Inaktiv (kein Löschen)shop_update→ nur Navigation zum Shop-Editor (editUrl, QuerydispatchNewName/dispatchNote) — kein automatisches Umbenennen in der DBoffer_import/news_import→ Entwurf in Offers/News (status: Entwurf,isActive: falsebei Offers), Felder ausdraftTitle/draftBody— kein Auto-Publish. Antwort enthälteditUrl.
- AgencyOS/MCP (Phase 3): Gleiche Semantik unter
/api/agencyos/v1/dispatch/[id](discard,restoreFromDiscarded,suggestedActions) undPOST …/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]/analyzemit{ "humanFeedback": "…" }. Der Ablehnungsgrund aus dem Content-Entwurf wird vorausgefüllt. Gespeichert inaiSuggestion.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]/analyzezieht den Klartext ausbodyText; istbodyHtml(z. B. PostmarkHtmlBody) deutlich länger oder der Plaintext nur ein Stub, wirdhtmlToPlainText(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, Legacygpt-4/gpt-3.5-turbowerden automatisch aufgpt-4o-miniupgegradet (8k-Kontext + kein JSON-Mode). Beicontext_length_exceededein Retry mit halbiertem Budget. Größere Modelle: bis 8192 Completion-Tokens. In Development liefert die Route bei 500 zusätzlichdetailmit 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 (typenews/offer/eventodernonewenn kein Post). Ziel: kleines MEC-Team kann Mails ohne langes Ermitteln zuordnen. Zusätzlich optionalcustomerCommunication: strukturierter Vorschlag für persönliche Rückmeldung an den Absender (Betreff, E-Mail-Text, Kanalhinweis) — wird bei „Entwurf erstellen“ inContentDraft.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 überPATCH /api/dispatch/[id]mit BodyworkflowPatchgespeichert; bei Re-Analyse bleibtworkflowdurch Merge erhalten (siehedispatch-workflow.ts). - Dispatch-Übersicht: Filter nach Triage-Kategorie (
intakeCategory), „Dev nötig / übergeben“ kombiniertneedsDevTeamoderworkflow.handoffToDev. - Explainability (serverseitig): Nach jeder erfolgreichen Analyze berechnet
dispatch-analyze-explanation.tsaus vorhandenen KI-FeldernaiSuggestion.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, wennsubjectleer ist. - Korrektur aus der Liste: Postfach-Karte Korrektur → Sheet →
POST /api/dispatch/[id]/analyzemithumanFeedback. Optional{ "rememberSenderNote": true }speichert den Text inorganizations.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-hintfü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 alshumanCorrectionNotepersistiert. Nutzt die globale KI-Konfiguration (getAIConfig) und den zentralen HTTP-ClientopenAIChatCompletion(apps/dashboard/src/lib/openai-chat.ts). Auth: Dashboard-Session mit Dispatch-Zugriff (dispatch-access.ts), oder interner HeaderX-Internal-Dispatchmit dem Wert ausDISPATCH_WEBHOOK_SECRET(Fallbackinternal) — so wietriggerDispatchAnalyzenach Inbound/Manuell-Create. Leere oder relativebaseUrlin der DB würden früher zufetch("/chat/completions")führen – der Client normalisiert aufhttps://api.openai.com/v1bzw.OPENAI_API_BASE_URL. Unterstützt das konfigurierte Modell keinen OpenAI-JSON-Mode (response_format: json_object, z. B. älteresgpt-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[], optionalcenterId,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-draftmit 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; sonstin_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 —pickStoredDispatchImageUrlssortiert überdispatch-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 alspreferredPublishAtIso. - Badges:
GET /api/dispatchliefertawaitingDraftCount(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:
centerIdswird vorbelegt. Bei Organisations-Match:intake_organization_idgesetzt,centerIdsleer — 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(BearerCRON_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äfixgmail:/graph:. - Matching:
apps/dashboard/src/lib/dispatch-intake-config.ts—extractInboundRecipientEmails,matchIntakeRecipient. - Sichtbarkeit (Queue + Home-Badge):
GET /api/dispatchund Dashboard-Home zählen Items mitcenterIds/intakeCenterIdin erlaubten Centern oderintakeOrganizationIdin den scoped Orgs des Users (buildDispatchListWhereindispatch-access.ts). Org-Intake ohne Center-Vorbelegung erscheint damit in der Queue. - Manuell erfasste Mails:
POST /api/dispatchsetztintakeCenterId/intakeOrganizationIdaus UI-Kontext (Postfach-Anbindung-Center, Org-Filter) bzw. Session-Fallback — sonst fehlt Org-Scope undPOST /api/dispatch/[id]/analyzeantwortet mit 403. KI-Analyse nutztsanitizeApiKey(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, HeaderX-Dispatch-Secretfür E-Mail-Inbound; derselbe Wert (Fallbackinternal) alsX-Internal-Dispatchfür serverseitige KI-Trigger (triggerDispatchAnalyze→/api/dispatch/[id]/analyze).DISPATCH_INTAKE_STRICT_MATCH– optionaltrue, Empfänger muss konfiguriertem Center- oder Organisations-Postfach entsprechen.DISPATCH_TEAMS_WEBHOOK_SECRET– optional, HeaderX-Dispatch-Teams-Secretfü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