Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/VA-P23.md
T
2026-07-08 16:15:37 +02:00

8.5 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 (Renewal-Cron deckt Graph ~3 Tage UND Gmail-Watch ~7 Tage; Live-Connect-Run braucht Staging-OAuth-Creds → VEXT-5)
  • Push-Sync (kein Primär-Polling); Initial-Sync 90 Tage, resumebar mit Progress (Fallback-Poll erst nach 4 h Stille; Resume via pageToken/nextLink im Cursor-Progress-JSON, getestet)
  • Auto-Match: From-Adresse → Contact/Lead, Subject-Pattern ([Projekt #123]), 1-offenes-Projekt-Heuristik; manueller Override sticht (pure email-match.ts, 14 Edge-Case-Tests; Override blockt Re-Match, Audit email_match_changed)
  • Inbox-Liste (Filter/Suche/Bulk) + Detail (Thread + sicherer HTML-Render); Reply/Forward via User-Mailbox (Provider-Quotas) + Vorlagen (funktional komplett; finale Optik blockiert bis Davids D-P23/VD-P23-Delta)
  • Anhänge landen in v1-Files; Mails erscheinen im Activity-Stream (lazy Import → File source email_attachment + FileEntityLink email_message; email_received/email_sent via logActivity, actor_kind system)
  • email.read_own vs. email.read_all filtern Liste + Activity-Stream (Maskierung „E-Mail-Aktivität (nicht einsehbar)" im CRM-Timeline-Loader)
  • OAuth-Tokens per DEK verschlüsselt (Token-Encryption) (tenant-envelope AD-8, nie in VMs selektiert)
  • Konnektor tenantHasModule('email_inbox'); RLS auf allen Tenant-Tabellen (FeatureKey real email-inbox — kebab-case-Konvention in packages/entitlements, Abweichung vom DoD-Wortlaut mit User-OK 2026-07-02; RLS-Gate-Test 7/7 grün)

Umsetzungs-Notiz (2026-07-02, Akeshan + Agent)

Stand: 8/8 DoD funktional = ~94 % done (konservativ: DoD 4 „teilweise" bis Davids Delta) — selbst machbar offen: 0. Extern blockiert: (a) finale UI-Optik nach VD-P23/Davids Delta (Dev-Nachzug unten), (b) Gmail-Prod-Breite nach Google-Review/CASA (VEXT-5, Brücke = Gmail-Testmodus + Outlook), (c) Live-Connect-/Staging-Verifikation sobald OAuth-Creds + Pub/Sub-Topic in der Umgebung stehen.

Proof: Branch feat/VA-P23, 9 Commits (d1597900b S1 … 7eb84b24c S10), lokal, nicht gepusht. 222 gezielte Tests grün (31 Dateien: Provider-Clients, Mapping, Match-Edge-Cases, Sync-Engine inkl. Resume/Renewal, Webhook-Kontrakte, Sanitizer-XSS-Fixtures, VMs, Sidebar-/Permission-/Entitlements-Kontrakte). RLS-Gate-Beweis rls-email-inbox-isolation 7/7 gegen db-push-DB. prisma validate grün, verify:i18n Exit 0, typecheck (db/entitlements/integrations/view-models/queue/worker/web) 0 Fehler. AD-21: nur db push auf dem Branch, Merge-Migration folgt beim main-Merge.

Bausteine: prisma/schema/email-inbox.prisma (4 Modelle, bare Skalare) + prisma/rls/email-inbox-isolation.sql · packages/integrations: gmailApi/graphMailApi (fetch-only), email-message-mapping (geteilt Web+Worker), email-match(+hook), email-worker-tasks.server (Drain/Initial-Sync resumebar/Renewal beide Provider/Stale-Poll/Cleanup) · Worker: 6 Crons in email-inbox-maintenance-cron · Web: Modul apps/web/app/modules/emailInbox (Access-Guard 404-Semantik, DEK-ConnectionService, SendService mit Threading-Headern + Graph-202-Spiegel-Dedupe via internetMessageId, dompurify-Sanitizer mit Bilder-Opt-in, Attachment-Import 15 MB), Routen /emails, /emails/:id, /emails/new, /settings/integrations/email, Webhooks webhooks.email.{google,microsoft}, OAuth-Callbacks, Sidebar-Eintrag (Gate email-inbox + email.read_own) · Permissions email.read_own/read_all/write · e2e tests/e2e/email-inbox.spec.ts.

Env-Vars (Deploy-Nachzug, Namen analog GOOGLE_CALENDAR_*): GOOGLE_GMAIL_CLIENT_ID/_CLIENT_SECRET/_REDIRECT_URI/_PUBSUB_TOPIC/_WEBHOOK_URL/_PUBSUB_VERIFICATION_TOKEN · MICROSOFT_MAIL_CLIENT_ID/_CLIENT_SECRET/_REDIRECT_URI/_TENANT/_WEBHOOK_URL. Redirect-URIs: /integrations/email/{google|microsoft}/oauth/callback.

Bewusst v1-schlank (Spec-konform): Volltext via ILIKE (tsvector/Meili = v2-Notiz), Graph-Attachments >3 MB ($value-Stream) deferred, BCC-Logging-Brücke bleibt AK-P14a, kein Rich-Text-Editor im Compose (Plain-Text + zitiertes Original; finale UI kommt mit Davids Delta).

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 → @hivegrid/storage + FileEntityLink.
  • Auto-Match-Service: From→Kontakt, Subject-Token, 1-offenes-Projekt-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