Files
HiveGrid-Wireframes/hivegrid-cloud/.planning/ticket-docs/VA-P23.md
T

5.1 KiB

VA-P23 · P23 Postfach-Sync (Gmail/Outlook OAuth + Inbox + Threading + Versand)

Typ Dev (Code)
Owner Akeshan
Phase P23 — Postfach-Sync (Email-Inbox) · v2-P2
Cycle/Fenster v2-W1 — Public-API/Postfach/Abo/KI-Start · fällig 2026-07-17
Status geplant

Abhängigkeiten & Parallelität

  • Blocked by: R-P5 (Apps-Engine — EmailProviderInterface als Adapter-Pattern), R-P6 (CRM — Contact/Lead-Match), AK-P14a (Sende-Domain DKIM/SPF/DMARC aus v1 — NICHT neu bauen)
  • Blocks: —
  • Läuft parallel zu: Raffaels VR-P22 (Public-API/Webhooks) — teilt nur die Webhook-Ingest-Infra, keine Domänen-Tabellen. Eigene prisma/schema/email-inbox.prisma (AD-21); core.prisma/crm.prisma nur über FK (matched_kontakt/projekt) berühren.
  • Konflikt-Risiko: gering — additive v2-Tabellen, Versand über die User-Mailbox (Gmail/Graph), nicht über die Marketing-Sende-Domain.

Was wir bauen

Gmail- und Outlook-Postfächer der User werden bidirektional ins CRM gespiegelt: per OAuth verbunden, per Push-Sync (Gmail Pub/Sub-Watch, Microsoft Graph-Subscription) aktuell gehalten, auto-gematcht auf Contact/Lead/Projekt und im Activity-Stream sichtbar. User lesen Threads in einer Inbox-Liste mit sicherem HTML-Render und antworten/leiten weiter über die eigene Mailbox. Permission-getrennt über email.read_own vs. email.read_all. Recut: Nur der OAuth-Sync/Inbox/Threading-Teil von M09 ist v2 — die Sende-Domain stammt aus v1-P14.

Benötigte Screens (Backend bedient — Design liefert D-P23)

Screen [Route] Kern-Inhalt
Mailbox-Connect-Settings [/settings/integrations/email] Gmail/Microsoft-OAuth verbinden, Sync-Status (Initial-Sync-Progress, letzter Sync, Fehler-Banner), Reconnect/Token-Refresh, Trennen/Revoke
Inbox-Liste [/emails] Mail-Liste (Absender/Betreff/Snippet/Datum/Verknüpfungs-Badge/gelesen-Indikator) + Filter (Mailbox/verknüpft/unverknüpft/Datum) + Volltext-Suche + Bulk-Actions
Mail-Detail [/emails/:id] Thread chronologisch (kollabierbar), sicherer HTML-Render (CSP, externe Bilder blockiert/optional laden), Anhänge → Files, Verknüpfungs-Editor (Contact/Lead/Projekt + Override), Reply/Forward
Outbound-Compose [/emails/new] Neue Mail / Reply / Forward über User-Mailbox, Empfänger/Betreff/Body, Anhänge, Vorlagen-Auswahl (M098)

Definition of Done

  • OAuth-Connect Gmail (Pub/Sub-Watch) + Microsoft (Graph-Subscription + ~3-Tage-Renewal-Worker); Token-Refresh + Revoke
  • Push-Sync (kein Primär-Polling); Initial-Sync 90 Tage, resumebar mit Progress
  • Auto-Match: From-Adresse → Contact/Lead, Subject-Pattern ([Deal #123]), 1-offener-Deal-Heuristik; manueller Override sticht
  • Inbox-Liste (Filter/Suche/Bulk) + Detail (Thread + sicherer HTML-Render); Reply/Forward via User-Mailbox (Provider-Quotas) + Vorlagen
  • Anhänge landen in v1-Files; Mails erscheinen im Activity-Stream
  • email.read_own vs. email.read_all filtern Liste + Activity-Stream
  • OAuth-Tokens per DEK verschlüsselt (Token-Encryption)
  • Konnektor tenantHasModule('email_inbox'); RLS auf allen Tenant-Tabellen

Technische Bausteine

  • Entities (eigene prisma/schema/email-inbox.prisma, AD-21): EmailIntegrationMailbox (provider gmail/microsoft, oauth_tokens [DEK], connection_status), EmailIntegrationMessage (matched_kontakt_id/matched_projekt_id, thread-Zuordnung, polymorph), EmailIntegrationSyncCursor (Initial-Sync-Fortschritt + resumebar), EmailIntegrationWebhookEvent (append-only). crm.prisma/core.prisma nur über FK (AD-21).
  • Provider-Adapter über Apps-Engine (M33a/R-P5): EmailProviderInterface hinter zwei konkreten Adaptern (Gmail Pub/Sub, Microsoft Graph) — gleiches Pattern wie KWP/Telefonie. Renewal-Worker für Graph-Subscription (~3 Tage) ist kritisch.
  • Sicherer HTML-Render: CSP-gehärteter Container, externe Bilder default geblockt mit „laden"-Opt-in; Anhänge → @toolctrl/storage + FileEntityLink.
  • Auto-Match-Service: From→Kontakt, Subject-Token, 1-Deal-Heuristik; schreibt Activity (actor_kind=system) im Activity-Stream; Override-Flag persistiert.
  • is_demo_data auf seedbaren Demo-Mails; RLS überall.

Quellen (granular)

  • ROADMAP-V2.md → §v2-P2 Postfach-Sync (Screens/Features = Hauptquelle; Depends-on/Success-Criteria/Recut)
  • ENTITY-MODEL.md → Domäne 8 (EmailIntegrationMailbox/Message/SyncCursor/WebhookEvent, matched_kontakt/projekt) + Domäne 5 Activity-Stream
  • ROADMAP.md → Phase 23 · PHASE-SOURCES.md → Phase 23 (M096 Gmail-OAuth, M097 Sync/Inbox/Threading/Match, M098 Versand/Vorlagen)
  • designer-briefs/P23-postfach-sync.md (Screens, UI-Elemente, Recut-Hinweis, Gmail-CASA-/Graph-Renewal-Risiko)
  • _bmad-output/specs/M09-email-inbox.md (⚠ nur OAuth-Sync/Inbox/Threading-Teile sind v2; Sende-Domain = v1)

Dev-Nachzug (nach Davids D-P23-Delta)

  • Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
  • REQUIREMENTS/PHASE-SOURCES nachgezogen
  • Plane-Ticket VA-P23 aktualisiert