Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,569 @@
---
module: 9
title: Email Inbox + Sync (Gmail/Outlook)
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-7, LP-9, LP-10, LP-11, LP-13]
spec_style: requirements-pur
---
# Modul 9 — Email Inbox + Sync
> **Detail-Spec gemäß LP-9.** Verbindet die Mailbox(en) eines Tenants (Gmail / Outlook) mit dem CRM. Jede eingehende Mail wird mit Kontakten/Deals/Projekten verknüpft und im Activity-Stream sichtbar. Liefert das Sending-Domain-Fundament (DKIM/SPF/DMARC) für Modul 10. Bildet zusammen mit M10 die Ablöse-Komponente für HubSpot-Mail-Tools (LP-7).
## Themenblöcke
```
A. Datenmodell
B. Mailbox-Connect (OAuth Gmail / Microsoft)
C. Sending-Domain (DKIM/SPF/DMARC) als Plattform-Fundament
D. Sync-Strategie (Push-Webhooks statt Polling)
E. Auto-Match-Logik (Mail → Kontakt / Deal / Projekt)
F. Inbox-View (Liste + Detail)
G. Outbound-Compose
H. Activity-Stream-Integration
I. Permissions
J. Provider-Adapter (LP-11)
K. Phase 2
```
---
## Block A — Datenmodell
### EmailIntegrationMailbox
Pro Tenant-User eine verbundene Mailbox. Tenant-scoped (RLS).
- `id`, `tenant_id`, `created_at`, `updated_at`
- `owner_user_id` (FK auf TenantUser — wem gehört die Mailbox)
- `provider` (Enum: `gmail | microsoft`)
- `email_address` (unique pro Tenant)
- `display_name`
- `oauth_access_token_encrypted`, `oauth_refresh_token_encrypted`, `oauth_token_expires_at`
- `oauth_scope_granted` (Liste der gewährten Scopes)
- `sync_status` (Enum: `connecting | active | paused | error | revoked`)
- `last_sync_at`, `last_error_text`
- `webhook_subscription_id` (Provider-spezifisch — Gmail: Pub/Sub-Topic, Microsoft: Subscription-ID)
- `webhook_expires_at` (Microsoft-Subscriptions laufen nach 3 Tagen ab → Renewal-Job)
- `is_default_for_user` (Boolean — falls User mehrere Mailboxen hat)
- `archived_at`
**Indizes:** `(tenant_id, owner_user_id)`, `(tenant_id, email_address)`, `(sync_status, webhook_expires_at)` für Renewal-Worker.
### EmailIntegrationMessage
Spiegel der Mails aus der angebundenen Mailbox. Tenant-scoped.
- `id`, `tenant_id`, `mailbox_id`, `created_at`
- `provider_message_id` (Gmail-`id` / Microsoft-`internetMessageId`) — unique pro Mailbox
- `provider_thread_id` (Gmail-`threadId` / Microsoft-`conversationId`)
- `direction` (Enum: `inbound | outbound`)
- `from_address`, `from_name`
- `to_addresses[]`, `cc_addresses[]`, `bcc_addresses[]`
- `subject`
- `body_html`, `body_text`
- `received_at`, `sent_at`
- `is_read` (gespiegelt aus Provider)
- `is_starred` (gespiegelt)
- `provider_labels[]` / `provider_folders[]` (z.B. `INBOX`, `SENT`, `Drafts`)
- `has_attachments` (Boolean)
- `matched_contact_id` (FK, nullable)
- `matched_company_id` (FK, nullable)
- `matched_deal_id` (FK, nullable)
- `matched_project_id` (FK, nullable)
- `match_confidence` (Enum: `high | medium | low | manual | none`)
- `manual_override_at`, `manual_override_user_id` (User hat Match-Zuordnung manuell gesetzt)
- `archived_at` (Soft-Delete im HiveGrid — Provider bleibt unberührt)
**Indizes:**
- `(tenant_id, mailbox_id, received_at DESC)` — Listen-View
- `(tenant_id, matched_contact_id, received_at DESC)` — Activity-Stream am Kontakt
- `(tenant_id, matched_deal_id, received_at DESC)`
- `(tenant_id, provider_message_id)` unique
- `(tenant_id, provider_thread_id)` für Thread-Aggregation
- Trigram-Index auf `subject`, `from_address`, `body_text` für Volltext-Suche
### EmailIntegrationSyncCursor
Pro Mailbox ein Cursor für Initial-Sync und inkrementelle Pulls.
- `id`, `tenant_id`, `mailbox_id` (unique)
- `provider_history_id` (Gmail: `historyId` / Microsoft: `deltaToken`)
- `initial_sync_status` (Enum: `pending | running | completed | failed`)
- `initial_sync_progress` (Integer 0-100, nur während `running`)
- `last_cursor_advance_at`
- `error_text` (nullable)
### EmailIntegrationWebhookEvent
Roh-Log der eingegangenen Push-Events vom Provider. Append-only.
- `id`, `tenant_id`, `mailbox_id`, `received_at`
- `provider` (Enum)
- `event_payload` (JSONB — kompletter Provider-Push)
- `processing_status` (Enum: `received | processing | done | failed | discarded`)
- `processed_at`, `error_text`
- `derived_message_ids[]` (welche `EmailIntegrationMessage` aus dem Event entstanden sind)
**Retention:** 30 Tage, danach gelöscht (außer `failed` → 90 Tage für Diagnose).
### Email (HiveGrid-eigene Mails — getrennt von Mailbox-Spiegel)
Repräsentiert *eigene* Mails, die HiveGrid sendet (Booking-Bestätigungen, System-Mails, später Trigger-Mails). Nicht zu verwechseln mit EmailIntegrationMessage (gespiegelte User-Mailbox-Mails).
- `id`, `tenant_id`, `created_at`
- `purpose` (Enum: `booking_confirmation | system_notification | password_reset | invitation | acceptance_protocol | manual_outbound`)
- `from_sender_id` (FK auf TenantSendingDomain bzw. EmailSender — siehe Block C)
- `to_address`, `to_name`
- `cc_addresses[]`, `bcc_addresses[]`
- `subject`, `body_html`, `body_text`
- `delivery_status` (Enum: `queued | sending | delivered | bounced | rejected | failed`)
- `provider_message_id` (von SMTP-Provider)
- `bounce_type` (Enum: `hard | soft | null`)
- `bounce_reason` (Klartext)
- `sent_at`, `delivered_at`, `bounced_at`
- `related_contact_id`, `related_company_id`, `related_deal_id`, `related_project_id` (FKs nullable)
- `archived_at`
**Indizes:** `(tenant_id, related_contact_id, sent_at DESC)`, `(tenant_id, delivery_status, sent_at DESC)`.
### EmailRead
Tracking für *gelesen-durch-Empfänger* (transaktionale Mails von HiveGrid). Pixel-Tracking optional pro Email.
- `id`, `email_id` (FK auf Email), `tenant_id`
- `read_at`
- `reader_ip`, `reader_user_agent` (optional, DSGVO-Hinweis im Footer)
### EmailAttachment
Anhänge für sowohl `EmailIntegrationMessage` als auch `Email`.
- `id`, `tenant_id`
- `parent_kind` (Enum: `integration_message | email`)
- `parent_id`
- `filename`, `mime_type`, `size_bytes`
- `storage_path` (Scaleway-Bucket-Pfad: `tenants/{tenantId}/emails/{messageId}/{filename}`)
- `provider_attachment_id` (für Lazy-Download von Provider-Side falls Attachment nicht in Initial-Body geladen)
- `download_status` (Enum: `pending | downloaded | failed`)
### TenantSendingDomain
Verifizierte Domain, über die der Tenant *eigene* Mails versendet (transaktional + Marketing).
- `id`, `tenant_id`, `created_at`
- `domain` (z.B. `geerkens.de`)
- `dkim_public_key`, `dkim_private_key_encrypted`, `dkim_selector`
- `dkim_dns_record_text` (was der User in DNS eintragen muss)
- `spf_dns_record_text`
- `dmarc_dns_record_text`
- `verification_status` (Enum: `pending | verifying | verified | failed`)
- `verification_last_check_at`, `verification_error`
- `is_default_for_tenant` (Boolean)
- `archived_at`
**Indizes:** `(tenant_id, verification_status)`, `(domain)` global-unique.
### TenantInboundAddress
System-generierte Inbound-Adresse pro Tenant für Form-Integrationen / Email-zu-Lead.
- `id`, `tenant_id`, `created_at`
- `local_part` (z.B. `tenant-abc-leads`)
- `full_address` (z.B. `tenant-abc-leads@in.hivegrid.de`)
- `purpose` (Enum: `lead_inbox | bcc_logging | reply_routing`)
- `archived_at`
---
## Block B — Mailbox-Connect (OAuth)
### Connect-Flow Gmail
1. User in `/{tenant}/settings/integrations/email/` klickt *„Gmail verbinden"*
2. Redirect zu Google-OAuth mit Scopes: `gmail.modify`, `gmail.send`, `gmail.labels`, `userinfo.email`
3. Callback → Tokens werden encrypted gespeichert (`EmailIntegrationMailbox`)
4. System legt Pub/Sub-Subscription auf User-Mailbox an (Gmail-Watch-API)
5. Initial-Sync-Job: letzte 90 Tage Mails laden (oder konfigurierbar — Default 90)
6. `sync_status` → `active`
### Connect-Flow Microsoft (Outlook / Microsoft 365)
1. User klickt *„Outlook verbinden"*
2. Redirect zu Microsoft-OAuth mit Scopes: `Mail.ReadWrite`, `Mail.Send`, `User.Read`, `offline_access`
3. Callback → Tokens encrypted gespeichert
4. System legt Microsoft-Graph-Subscription auf `/me/messages` an (3 Tage Lebenszeit → Renewal-Job)
5. Initial-Sync analog Gmail (delta-API, letzte 90 Tage)
6. `sync_status` → `active`
### Connect-Flow für Tenant-Sending-Domain (DKIM)
1. Tenant-Admin in `/{tenant}/settings/integrations/email/sending-domain/` klickt *„Domain verbinden"*
2. Eingabe: Domain (z.B. `geerkens.de`)
3. System generiert DKIM-Schlüssel-Paar, baut DNS-TXT-Records (DKIM, SPF, DMARC)
4. UI zeigt **Klartext-Anleitung** mit Copy-to-Clipboard pro Record + Hinweis: *„Diese 3 Einträge bei deinem DNS-Anbieter (z.B. Strato, Hetzner, IONOS) anlegen. Wir prüfen automatisch alle 5 Minuten."*
5. Hintergrund-Job pollt DNS alle 5 Minuten bis Verification-Status `verified` oder Timeout 7 Tage
6. Bei `verified`: Domain ist sendebereit für transaktionale Mails (Modul 9) und Marketing-Mails (Modul 10)
### Reconnect / Token-Refresh
- Token-Refresh-Worker läuft alle 30 Min und erneuert Tokens, die in <2h ablaufen
- Bei Refresh-Fehler (User hat OAuth widerrufen) → `sync_status = revoked`, Klartext-Notification an User: *„Deine Gmail-Verbindung wurde unterbrochen — bitte erneut verbinden. [Verbindung erneuern]"*
### Disconnect
- User klickt *„Verbindung trennen"*
- Bestätigungs-Dialog mit Klartext: *„Wenn du trennst, werden keine neuen Mails mehr gespiegelt. Bisher gespiegelte Mails bleiben im CRM erhalten. Du kannst die Verbindung später wieder herstellen."*
- System ruft Provider-Token-Revoke-Endpoint auf
- `sync_status = revoked`
- Tokens werden aus DB gelöscht (encrypted, aber Defense-in-Depth)
- Webhook-Subscription beim Provider gekündigt
---
## Block C — Sending-Domain (Pflicht-Fundament für M10)
### DKIM-Setup-Anforderungen
- DKIM ist **Pflicht** für jede Sending-Domain (Marketing-Mails ohne DKIM werden von Gmail/Outlook im Spam landen)
- DKIM-Selector pro Tenant generiert (z.B. `hg-{tenant-slug}`)
- Schlüssel-Länge: 2048 Bit
- DKIM-Private-Key wird verschlüsselt gespeichert (KMS-managed-Key in Scaleway)
### SPF-Empfehlung
- Tenant erweitert seinen SPF-Record um `include:_spf.hivegrid.de`
- Falls SPF noch nicht existiert → System schlägt vollständigen Record vor
### DMARC-Empfehlung
- Empfohlen: `v=DMARC1; p=quarantine; rua=mailto:dmarc-reports@hivegrid.de; ruf=mailto:dmarc-reports@hivegrid.de`
- Optional, nicht Pflicht für M10-Versand
### Verification-Logik
- Cron-Job alle 5 Min prüft Domains mit Status `pending` oder `verifying`
- DKIM-Check: DNS-TXT-Lookup auf `{selector}._domainkey.{domain}`
- SPF-Check: DNS-TXT-Lookup auf `{domain}` mit Pattern-Match
- Bei allen 3 OK → Status `verified`
- Bei 7 Tagen ohne Erfolg → Status `failed` + Klartext: *„Wir konnten deine DNS-Einträge nach 7 Tagen nicht finden. [Anleitung erneut anzeigen] [Support kontaktieren]"*
### Tenant ohne eigene Domain (Fallback)
- Phase 1: kein Versand möglich ohne verifizierte Sending-Domain für Marketing
- Transaktionale Mails (Booking-Confirmation, etc.) gehen über System-Domain `noreply@hivegrid.de` (mit Tenant-Branding im Klartext)
- Klartext im Marketing-Modul (M10): *„Bevor du Marketing-Mails versendest, musst du eine eigene Sending-Domain einrichten. [Domain einrichten]"*
---
## Block D — Sync-Strategie (Push statt Polling)
### Gmail Push (Pub/Sub)
- Pro Mailbox: Watch-API legt Pub/Sub-Subscription auf User-Inbox an
- Pub/Sub liefert HTTPS-Push an `/api/v1/webhooks/email/gmail`
- Push enthält nur `historyId` — kein Mail-Body
- Worker holt mit `historyId` die Diff-Liste über Gmail-API
- Pro neue Message: Body laden, in `EmailIntegrationMessage` einfügen, Auto-Match auslösen
### Microsoft Push (Graph-Subscriptions)
- Pro Mailbox: Subscription auf `/me/messages` mit Lifetime 4230 Min (~3 Tage)
- Push an `/api/v1/webhooks/email/microsoft`
- Renewal-Worker erneuert Subscription täglich
### Fallback-Polling
- Falls Webhook 4h kein Event liefert (Mailbox aktiv aber kein Push) → Worker pollt 1× pro Stunde als Sicherheitsnetz
- `last_sync_at` wird bei jedem erfolgreichen Sync (Push oder Poll) aktualisiert
### Initial-Sync
- Hintergrund-Job lädt letzte 90 Tage Mails
- Progress sichtbar in UI: *„Initial-Sync läuft — 1.234 von 5.678 Mails geladen (22%)"*
- Bei Abbruch resumefähig über `provider_history_id`-Cursor
### Klartext-Diagnose im Sync-Status (LP-10)
- `connecting`: *„Wir richten deine Mailbox-Verbindung ein, das dauert wenige Sekunden..."*
- `active`: keine Anzeige (Default-Zustand)
- `paused`: *„Sync pausiert — [Sync starten]"*
- `error`: spezifischer Fehlertext, z.B. *„Wir konnten Google nicht erreichen (HTTP 503). Wir versuchen es erneut in 5 Min. [Manuell prüfen]"*
- `revoked`: *„Deine Mailbox-Verbindung wurde widerrufen. [Erneut verbinden]"*
---
## Block E — Auto-Match-Logik
### Mail → Kontakt (über Email-Adresse)
1. Beim Eingang einer Mail: `from_address` wird gegen `ContactEmail` und `Lead.email` (in Tenant-Scope) gematcht
2. **Hard-Match (high confidence):** exakte Email-Übereinstimmung mit Contact → `matched_contact_id` gesetzt + `match_confidence = high`
3. **Hard-Match (high confidence):** Email-Übereinstimmung mit Lead → `matched_contact_id` bleibt null, aber Activity wird am Lead erzeugt
4. **No-Match:** keine Zuordnung → in Inbox sichtbar, manuell zuordbar
5. Bei *outbound* Mails: `to_addresses` werden gematcht (alle Empfänger gegen Contacts geprüft, primärer Match auf erstem Treffer)
### Mail → Deal (über Subject-Pattern)
1. Subject wird auf Patterns geprüft:
- `[Deal #123]` → Deal-ID 123 zuordnen
- `[Auftrag #456]` → Project-ID 456 zuordnen
- `[Lead #789]` → Lead-ID 789 zuordnen
2. ID muss im Tenant existieren, sonst Pattern ignoriert
3. Patterns sind Tenant-konfigurierbar in Phase 2 (Phase 1: hartcodiert)
4. Match-Confidence: `high` falls Pattern matched
### Mail → Deal (über Kontakt-Verknüpfung — Heuristik)
- Falls `matched_contact_id` gesetzt UND der Kontakt hat genau 1 offenen Deal → Deal automatisch zuordnen mit `match_confidence = medium`
- Falls Kontakt mehrere offene Deals → keine Auto-Zuordnung, manuell in UI
### Manuelle Zuordnung
- Im Mail-Detail-View: User kann manuell *„Zu Kontakt zuordnen"* / *„Zu Deal zuordnen"* / *„Zu Projekt zuordnen"*
- `manual_override_at` + `manual_override_user_id` werden gesetzt
- Manuelle Zuordnung überschreibt Auto-Match
- Auto-Match-Logik versucht **nicht erneut** zu matchen, falls `manual_override_at` gesetzt
### Edge-Cases
- **Mehrere Contacts mit gleicher Email** (z.B. private + geschäftliche Adresse identisch): primärer Contact (mit `is_primary` Email) wird gewählt; UI-Hinweis: *„Diese Email gehört zu mehreren Kontakten. Aktuell zugeordnet: [Name]. [Anders zuordnen]"*
- **Eigene Mails an eigene Mailbox** (User schreibt sich selbst): `direction = outbound`, kein Auto-Match auf Contact (eigene Email-Adresse ist in `EmailIntegrationMailbox` registriert und wird ausgeschlossen)
- **Newsletter / Bulk-Sender** (List-Unsubscribe-Header vorhanden): keine Auto-Verknüpfung mit Contact, Mail wird in Inbox als *„Newsletter / Bulk"* gekennzeichnet
---
## Block F — Inbox-View
### Liste (`/{tenant}/emails`)
**Zu zeigende Daten pro Eintrag:**
- Absender (Name + Email)
- Betreff
- Snippet (erste 100 Zeichen Body)
- Empfangsdatum (relativ, < 7 Tage; absolut sonst)
- Verknüpfter Kontakt / Deal / Projekt (falls gemacht)
- Read/Unread-Indikator
- Anhang-Indikator (falls vorhanden)
- Mailbox-Indikator (falls User mehrere Mailboxen hat)
**Benötigte UI-Elemente:**
- Tabellarische oder Listen-Anzeige
- Such-Funktion (Volltext über Subject + Body + Absender)
- Filter:
- Mailbox (Multi-Select, wenn User mehrere hat)
- Direction (`inbound | outbound | all`)
- Read-Status (`gelesen | ungelesen | alle`)
- Verknüpft-mit (`Kontakt | Deal | Projekt | nicht verknüpft`)
- Datum (Date-Range-Picker)
- Anhang (Boolean)
- Bulk-Auswahl + Bulk-Actions (Read/Unread markieren, Archivieren)
- Pagination (Cursor-basiert, 50 pro Page)
- Toggle „Archivierte anzeigen"
**Operationen:**
- Klick auf Zeile → Detail-View
- Bulk-Read-/Unread-Markierung (sync zurück zum Provider)
- Bulk-Archive im HiveGrid (Provider unangetastet)
**Performance:**
- Index `(tenant_id, mailbox_id, received_at DESC)`
- Trigram-Index für Volltext-Suche
- Permissions-Filter: `email.read_own` zeigt nur eigene Mailboxen, `email.read_all` zeigt alle Tenant-Mailboxen
### Detail (`/{tenant}/emails/:id`)
**Zu zeigende Daten:**
- Vollständige Mail (From, To, CC, Subject, Body-HTML)
- Empfangsdatum + Mailbox
- Anhänge (Liste mit Download-Link)
- Verknüpfter Kontakt / Deal / Projekt (klickbar zu Detail-View)
- Match-Confidence + Hinweis: *„Auto-erkannt"* / *„Manuell zugeordnet von [User]"*
- Thread-Anzeige (alle Mails mit gleichem `provider_thread_id`, chronologisch)
**Benötigte UI-Elemente:**
- Mail-Body-Render (HTML mit Content-Security-Policy: keine externen Scripts, externe Bilder hinter „Bilder anzeigen"-Toggle)
- Attachment-Liste mit Download
- Thread-Aggregat (collapsed/expanded)
- Reply / Reply-All / Forward-Funktionen (öffnet Compose mit Pre-Fill)
- Verknüpfungs-Editor (Kontakt / Deal / Projekt zuordnen oder ändern)
- Read/Unread-Toggle
- Archivieren-Funktion
**Operationen:**
- Reply / Reply-All / Forward
- Verknüpfungen ändern (manuelle Override)
- Anhang downloaden
- Mail im Provider öffnen (Deep-Link zu Gmail/Outlook-Web)
- Archivieren
**Klartext-Hinweise:**
- Externe Bilder geblockt: *„Externe Bilder geladen? [Anzeigen]"*
- Mail nicht zugeordnet: *„Diese Mail ist keinem Kontakt zugeordnet. [Zu Kontakt zuordnen] [Neuen Kontakt anlegen]"*
---
## Block G — Outbound-Compose
### Compose-Funktion
**Aufruf:**
- Aus Kontakt-Detail: *„Email schreiben"* → Empfänger vorausgefüllt mit Primary-Email
- Aus Deal-Detail: *„Email schreiben"* → Empfänger = primärer Kontakt am Deal, Subject pre-fill `[Deal #123] `
- Aus Projekt-Detail: analog mit `[Auftrag #456] `
- Aus Inbox-Detail (Reply/Forward): Empfänger und Subject vorgegeben
- Standalone aus `/{tenant}/emails/new`: leerer Compose
**Benötigte UI-Elemente:**
- Empfänger-Felder (To, CC, BCC) mit Auto-Complete aus Contacts
- Subject-Feld
- Body-Editor (Rich-Text — Bold/Italic/Link/Liste/Bilder/Inline-Attachments)
- Anhang-Upload (max. 25 MB pro Mail Provider-Limit)
- Mailbox-Auswahl (falls User mehrere Mailboxen hat — Default: Default-Mailbox des Users)
- Send-Funktion + Save-as-Draft-Funktion
- Schedule-Send (Phase 2)
**Send-Pfad:**
- Mail wird über die verbundene User-Mailbox gesendet (Gmail-API `messages.send` / Microsoft-Graph `sendMail`)
- Provider-Side erscheint die Mail im *Sent*-Folder des Users (nativ)
- HiveGrid spiegelt die gesendete Mail nach erfolgreichem Send als `EmailIntegrationMessage` mit `direction = outbound`
- Activity-Stream-Eintrag wird erzeugt
**Klartext-Fehler:**
- Mailbox nicht verbunden: *„Du hast keine Mailbox verbunden. [Mailbox verbinden]"*
- Send-Fehler: *„Mail konnte nicht gesendet werden — Google meldet 'Quote exceeded'. In 1h erneut versuchen oder anderen Account verwenden. [Erneut versuchen]"*
- Empfänger ohne Email: *„Der Kontakt hat keine Email-Adresse hinterlegt. [Email ergänzen]"*
**BCC-Logging-Adresse:**
- Optional: User kann in Settings aktivieren *„Beim Senden BCC an `tenant-{tenantId}-log@in.hivegrid.de`"*
- Für Edge-Case: User schreibt Mail aus nativem Gmail-Client, möchte trotzdem im CRM loggen → BCC-Adresse erzeugt automatisch eine `EmailIntegrationMessage`-Entry mit Auto-Match
---
## Block H — Activity-Stream-Integration
### Activity-Typen die M9 produziert
- `email_received` — eingehende Mail mit gemachtem Match
- `email_sent` — ausgehende Mail
- `email_unmatched` (Phase 2 — falls UX zeigt: „neue ungeordnete Mail")
- `email_match_changed` — Audit-Event bei manuellem Override
### Verknüpfungen
- Activity erscheint im Stream der gematchten Entity (Contact / Deal / Project / Lead)
- `summary_text` Beispiel: *„Eingehende Mail von Max Mustermann: ‚Anfrage Wartung'"*
- `metadata` enthält: Mailbox-ID, Provider-Message-ID, Subject, Snippet
- Klick auf Activity → öffnet Mail-Detail-View
### Permission-Wirkung
- Activity sichtbar nur für User mit `email.read_own` (eigene Mailboxen) bzw. `email.read_all`
- Falls User keine Email-Permissions hat: Activity zeigt nur *„Email-Aktivität (nicht einsehbar)"* ohne Details
---
## Block I — Permissions
### Permission-IDs
| Permission | Erlaubt |
|---|---|
| `email.read_own` | Eigene verbundene Mailbox-Mails sehen |
| `email.read_all` | Alle Tenant-Mailbox-Mails sehen |
| `email.write` | Mails verfassen + senden über eigene Mailbox |
| `email.admin` | Sending-Domain einrichten, Inbound-Adressen verwalten, fremde Mailbox-Connections trennen |
### Bundle-Mapping
| Bundle | Atomare Permissions |
|---|---|
| `email.none` | (keine) |
| `email.read_own` | `email.read_own` + `email.write` (eigene Mailbox schreiben können ist Standard) |
| `email.read_all` | `email.read_own` + `email.read_all` + `email.write` |
| `email.admin` | alle obigen + `email.admin` |
### Anwendung in Routes
- `/{tenant}/emails` → `email.read_own` oder `email.read_all`
- `/{tenant}/emails/:id` → analog (mit Owner-Check bei `read_own`: nur Mails aus Mailbox des Users)
- `/{tenant}/emails/new` (Compose) → `email.write` + verbundene Mailbox
- `/{tenant}/settings/integrations/email/` → jeder eingeloggte User für eigene Mailbox; Sending-Domain nur `email.admin` oder `tenant.admin`
### Owner-Check bei `read_own`
- User mit `email.read_own` sieht nur Mails aus Mailboxen, deren `owner_user_id = self`
- Auto-Match-Logik bleibt aktiv über alle Mailboxen, aber Anzeige im Activity-Stream eines Kontakts wird permissioned: User mit nur `email.read_own` sieht nur Mails aus seinen Mailboxen am Kontakt
---
## Block J — Provider-Adapter (LP-11)
### EmailProviderInterface
Gemeinsames Interface für Gmail- und Microsoft-Adapter:
- `connect(authCode) → MailboxConnection`
- `disconnect(mailboxId) → void`
- `fetchMessages(cursor, limit) → MessageBatch`
- `getMessage(providerMessageId) → MessageDetail`
- `sendMessage(MessageDraft) → ProviderMessageId`
- `subscribeToWebhook(mailboxId) → SubscriptionInfo`
- `renewWebhook(subscriptionId) → SubscriptionInfo`
- `revokeWebhook(subscriptionId) → void`
- `markRead(providerMessageId, isRead) → void`
- `downloadAttachment(providerMessageId, attachmentId) → Stream`
### Implementierungen
- **GmailAdapter:** spricht Gmail-API + Pub/Sub
- **MicrosoftAdapter:** spricht Microsoft-Graph + Subscription-API
### Klartext-Diagnose pro Adapter (LP-10)
Adapter liefern Provider-Fehler übersetzt:
- Gmail `403 quota exceeded` → *„Du hast das tägliche Sende-Limit erreicht. Es wird in [X Stunden] zurückgesetzt."*
- Microsoft `401 token expired` → *„Outlook-Verbindung abgelaufen — bitte erneut verbinden."*
- Generisch unbekannter Fehler → *„Es gab ein Problem mit deiner Mailbox-Verbindung. Wir versuchen es automatisch in 5 Min erneut. [Logs anzeigen]"* (Logs-Anzeige Permission-gegated über `email.admin`)
---
## Block K — Phase 2 / spätere Features
- Erweiterte Filter (gespeicherte Filter, Smart-Folders)
- Bulk-Operations: Multi-Reply, Multi-Forward
- Email-Templates für Outbound (Quick-Reply-Snippets)
- Mail-Merge in Compose (Personalisierung pro Empfänger)
- Schedule-Send (Mail um Datum X versenden)
- Tracking-Pixel für Outbound (Open-Tracking — Phase 2 für transaktionale Mails, in M10 schon Phase 1)
- Snooze-Funktion (Mail kommt in 3 Tagen wieder in Inbox)
- Auto-Forwarding-Regeln (alle Mails von `@geerkens.de` an Sales-Team weiterleiten)
- Custom-Subject-Patterns für Auto-Match (Tenant-konfigurierbar)
- Shared-Inbox (mehrere User auf 1 Mailbox, mit Assignment)
---
## Architektur-Vorschriften (Querschnitt)
- **LP-9:** Requirements-pur, kein Layout
- **LP-10, AV #1:** Klartext-Diagnose bei jedem Sync-Fehler, jeder OAuth-Disconnect, jedem Send-Fehler
- **LP-11:** Provider-Adapter-Pattern, Gmail + Microsoft als erste Implementierungen
- **LP-13:** Mail-Bodies werden in Scaleway-DB gehalten, Attachments in Scaleway-Storage (EU)
- **AV #5 Permissions-aware-Default:** Inbox-Liste filtert automatisch nach `email.read_own` vs. `read_all`
- **AV #6 Audit-Trail:** Manueller Match-Override loggt `audit_event`
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 9. **Vor Bau:** Validierung der Provider-Webhook-Lifecycle (insbes. Microsoft-3-Tage-Renewal), DKIM-DNS-Check-Implementierung mit echter Domain testen.
**Offene Detail-Punkte (nicht-blockierend):**
- Konkretes Encryption-KMS-Setup für OAuth-Tokens (Implementierungs-Detail)
- Konkrete Quotas pro Provider (Gmail: 1 Mrd Quota-Units/Tag — reicht weit; Microsoft: 10.000 Mails/Tag pro Mailbox)
- Initial-Sync-Default-Tiefe (90 Tage vorgeschlagen, ggf. Tenant-konfigurierbar)
- Subframe-UI-Designs (separat)
- Verknüpfung mit Modul 24 Globale Suche (Mail-Volltext indexieren)