8.3 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 —EmailProviderInterfaceals 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. Eigeneprisma/schema/email-inbox.prisma(AD-21);core.prisma/crm.prismanur ü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 (pureemail-match.ts, 14 Edge-Case-Tests; Override blockt Re-Match, Auditemail_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+ FileEntityLinkemail_message;email_received/email_sentvia logActivity, actor_kind system) email.read_ownvs.email.read_allfiltern 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 realemail-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.prismanur über FK (AD-21). - Provider-Adapter über Apps-Engine (M33a/R-P5):
EmailProviderInterfacehinter 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-StreamROADMAP.md→ Phase 23 · Milestones: (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)
Dev-Nachzug (nach Davids D-P23-Delta)
- Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
- REQUIREMENTS/ROADMAP nachgezogen
- Plane-Ticket
VA-P23aktualisiert