68 lines
8.3 KiB
Markdown
68 lines
8.3 KiB
Markdown
# 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
|
|
- [x] 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)*
|
|
- [x] **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)*
|
|
- [x] **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`)*
|
|
- [x] 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)*
|
|
- [x] 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)*
|
|
- [x] `email.read_own` vs. `email.read_all` filtern Liste **+** Activity-Stream *(Maskierung „E-Mail-Aktivität (nicht einsehbar)" im CRM-Timeline-Loader)*
|
|
- [x] OAuth-Tokens per **DEK** verschlüsselt (Token-Encryption) *(tenant-envelope AD-8, nie in VMs selektiert)*
|
|
- [x] 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 · 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-P23` aktualisiert
|