# VA-P28c · Admin Connections & E-Mail | | | |---|---| | **Plane** | `HIVEGRID-191` · Parent `HIVEGRID-190` | | **Typ** | Dev (Code) | | **Owner** | Raffael | | **Phase** | P28 — Admin Sales Workspace | | **Cycle/Fenster** | Backlog · nach `VR-P28a` und CRM-Core-Vertrag | | **Status** | Ready for Review | 🎨 **design-nachzug: offen** > **Owner-Änderung 2026-07-24:** Raffael übernimmt die Delivery. Working-ID, Scope, Status, > Termine, DoD und Abhängigkeiten bleiben unverändert. > > **Dependency-Nachzug 2026-07-24:** Auch `VA-P28b` liegt jetzt bei Raffael. Der > AdminContact-/AdminCompany-/AdminDeal-Vertrag und die `blocked-by`-Kante bleiben unverändert. > > **Feste Datenschutz-/Outbound-Entscheidung 2026-07-24:** Open-/Click-Tracking und > Live-Open-Benachrichtigungen sind standardmäßig deaktiviert. Aktivierte Tracking-Rohdaten > verfallen nach 180 Tagen. Produktiver Versand bleibt gesperrt, bis Limits, Arbeitszeiten > und Consent-Regeln administriert wurden. Lokale Fixtures lösen niemals Provideraktionen aus. ## Abhängigkeiten & Parallelität - **Blocked by:** `VR-P28a` (AdminUser/RBAC) und `VA-P28b` (AdminContact/AdminCompany/AdminDeal). - **Blocks:** `VA-P28d` (Connection-Fundament), `VA-P28e`, `VA-P28f`, `VA-P28g`, `VA-P28i` und `VR-P28a-RBAC` für Own-/Team-Kommunikationssicht und auditierte Fremdzugriffe. - **Design:** `VD-P28` ist Design-Dach; nach AD-28 kein Dev-Blocker. - **Extern:** Google-/Microsoft-Mail-OAuth, Redirect-URIs und Domain-DNS müssen für `admin.hivegrid.de` verfügbar sein. Providerfreigaben blockieren nur die jeweiligen Live-Proofs. - **Hardgrenze:** persönliche Admin-Mailboxen; keine Tenant-Mailbox, kein Tenant-DEK, kein Tenant-Mailverlauf. > **Implementierungsstart 2026-07-24:** `blocked-by` und `blocks` wurden in Plane und in > den Ticket-Docs beider Richtungen geprüft. `VR-P28a` steht mit 6/6 DoD und `VA-P28b` > mit 10/10 DoD auf Ready for Review. `VA-P28d/e/f/g/i` konsumieren weiterhin ausschließlich > den gemeinsamen providerneutralen `AdminDataConnection`-Vertrag. Google-/Microsoft-Live-Proofs > bleiben getrennte externe Gates und blockieren weder Fixture-first-Code noch den lokalen Golden Path. ## Was wir bauen Ein einmaliges plattformweites `AdminDataConnection`-Fundament und darauf den vollständigen persönlichen E-Mail-Arbeitsplatz für HiveGrids Vertrieb. Eingehende und ausgehende Nachrichten werden sicher synchronisiert, zu AdminContact/AdminLead/AdminDeal gematcht und als Thread in der gemeinsamen AdminActivity-Timeline angezeigt. ## Story-Ownership — 18/117 - `MAIL-01` Persönliches E-Mail-Konto verbinden. - `MAIL-02` Eingehende Mails Kontakt, Lead oder Deal automatisch zuordnen. - `MAIL-03` Gesendete Mails automatisch im Vorgang ablegen. - `MAIL-04` Mail direkt aus dem Kontakt senden. - `MAIL-05` Ganze Mail-Verläufe als Thread sehen. - `MAIL-06` Anhänge automatisch am Deal ablegen. - `MAIL-07` Öffnungen sehen. - `MAIL-08` Link-Klicks sehen. - `MAIL-09` Zustell- und Bounce-Status sehen. - `MAIL-10` Benachrichtigung bei einer aktuellen Öffnung erhalten. - `MAIL-11` Sende-Domain mit SPF/DKIM sauber einrichten. - `MAIL-12` Extern gesendete Mails per BCC-Adresse loggen. - `MAIL-13` E-Mail-Vorlagen mit Platzhaltern anlegen. - `MAIL-14` Textbausteine einfügen. - `MAIL-15` Persönliche Signatur hinterlegen. - `MAIL-16` Mails für später planen. - `MAIL-17` Bei ausbleibender Antwort nach X Tagen erinnern. - `MAIL-18` Personalisierte Serienmail an eine ausgewählte Liste senden. ## Benötigte Screens | Screen [Admin-Host-Route] | Kern-Inhalt | |---|---| | E-Mail im Kontakt/Lead/Deal | Thread, Anhänge, Events, Composer und Aufgabe | | Inbox [`/sales/email/inbox`] | Threads, Matchingstatus und Zuordnungsqueue | | Templates [`/sales/email/templates`] | Vorlagen, Platzhalter, Snippets, Vorschau | | Geplant [`/sales/email/scheduled`] | geplante Sends, Reminder und Bulk-Runs | | Konten [`/sales/settings/email-accounts`] | Connect, Syncstatus, Reconnect, Disconnect | | Domains [`/sales/settings/sending-domains`] | SPF/DKIM, BCC-Adresse, Tracking-/Datenschutzstatus | ## Definition of Done - [x] `AdminDataConnection` und verschlüsselter Admin-Credential-Store stehen providerneutral; Google Workspace und Microsoft 365 können pro AdminUser verbunden, erneuert und getrennt werden. - [x] Inbound-/Sent-Sync ist inkrementell und idempotent; Recovery-Polling, Webhooks, Cursor, Message-IDs und Provider-Dubletten sind getestet. - [x] Matching zu Kontakt, Lead und Deal ist deterministisch; unsichere Treffer landen in einer sichtbaren Zuordnungsqueue und werden nie still falsch verknüpft. - [x] Composer, Threading, persönliche Signatur, Vorlagen, Platzhalter und Snippets erfüllen `MAIL-04`, `MAIL-05`, `MAIL-13..15`. - [x] Anhänge erfüllen `MAIL-06`, laufen fail-closed durch Größenlimit/ClamAV und liegen im EU-Storage mit auditierter Deal-Verknüpfung. - [x] Zustellung, Bounce, Öffnung und Klick sind pro Empfänger als Events sichtbar; Tracking und Live-Open-Benachrichtigung sind standardmäßig aus, dedupliziert und unterliegen 180 Tagen Rohdaten-Retention. - [x] SPF/DKIM-Domainstatus und eindeutige, spoofing-geschützte BCC-Ingestion erfüllen `MAIL-11`/`MAIL-12`. - [x] Scheduling, No-Reply-Reminder und personalisierte Listenmail erfüllen `MAIL-16..18`, verwenden Queue, Idempotenz, Zeitzone und Sendebudgets; Multi-Step-Outbound bleibt in `VA-P28e`. - [x] Admin-Permissions, Audit/Activity, i18n, Klartextzustände sowie VM-/Action-Layer sind vollständig. - [ ] Unit-, Provider-Fixture-, DB-/RLS-, Worker-, Smoke-, Hot-Swap- und Visual-Tests sowie je Provider ein kontrollierter Staging-Live-Proof sind grün. **Fortschritt:** **9/10 DoD = 90 % done** · offen: 1 externer Provider-Live-Proof, davon 1 extern blockiert → **0 im Code selbst machbar**. ## Umsetzungs-Notiz 2026-07-24 - Providerneutrale Connections, verschlüsselte Credentials, OAuth-State, Google-/Microsoft-Adapter, cursorbasierter Sync, Replay-Schutz und Recovery-Polling wurden über `6bf8a9b36`, `33c062aeb` und die zugehörigen Fixture-/DB-/RLS-Tests umgesetzt. - Threading, deterministisches Kontakt-/Lead-/Deal-Matching, sichtbare Zuordnungsqueue, Composer, Vorlagen, Snippets und Signaturen wurden über `e0f8475f2` und `12ea12675` vollständig durch Route, View-Model und Actions verdrahtet. - Fail-closed Attachment-Ingestion, Tracking-/Retention-Vertrag, Domainprüfung, spoofing-geschützte BCC-Ingestion sowie Scheduling, No-Reply und Bulk wurden über `3da4fae4f`, `5bb52f12d`, `9504955e4`, `a7b4273f2` und `07918bc4b` geliefert. - Die Interim-UI ist über Admin-Sidebar und Breadcrumbs erreichbar. Visual-/A11y-Baselines decken Konten, Inbox, Templates, geplante Sends und Domains ab. Der Produktionsbuild-Fix `3a62825d8` hält alle Workspace-Services server-only. - Lokaler Proof: `pnpm typecheck`, `pnpm lint`, `pnpm test` (**1056 Dateien / 7457 Tests grün**), `pnpm build`, `pnpm run test:a11y` (**14 Dateien / 44 Tests grün**), `verify:i18n`, `verify:sidebar-routes`, `verify:phase-c-boundaries`, `verify:tenant-policy-contract` (**353/353**), `verify:cross-cutting-models` (**351/351**), `verify:ui-visual`, `test:hot-swap`, `verify:a11y-coverage`, `verify:source-health` und `verify:ci-baseline`. - Extern offen: kontrollierte Google-Workspace- und Microsoft-365-Live-Proofs mit freigegebenen Redirect-URIs/Testkonten. Fixture-Tests werden nicht als Live-Proof gewertet. ## Technische Bausteine - **Schema:** `prisma/schema/adminConnections.prisma` und `prisma/schema/adminEmail.prisma`. - **Modelle:** `AdminDataConnection`, `AdminConnectionCredential`, `AdminMailbox`, `AdminMailboxSyncCursor`, `AdminEmailThread`, `AdminEmailMessage`, `AdminEmailParticipant`, `AdminEmailAttachment`, `AdminEmailEvent`, `AdminEmailLink`, `AdminEmailTemplate`, `AdminEmailSnippet`, `AdminEmailSignature`, `AdminScheduledEmail`, `AdminNoReplyReminder`, `AdminBulkEmailRun`, `AdminSendingDomain`, `AdminBccAddress`. - **Secrets:** Plattform-Envelope-Key/Key-Wrapper, getrennte Staging-/Prod-Keys, niemals Tenant-DEK oder `CRYPTO_SECRET`-Legacyvertrag. - **Wiederverwendung:** providerneutrale Clients, MIME-/Threading- und Tracking-Helfer aus bestehenden Mail-Modulen dürfen extrahiert werden; keine Tenant-Queries oder Tenant-Routen. - **Legacy:** globale EmailSequence/Sender/MarketingIntegration-Daten nur migrieren, nicht als zweite Versand- oder Secret-Welt fortführen. ## Slices und Rollback 1. AdminDataConnection/Credential-Fundament. 2. Provider-Connect und Sync. 3. Threading/Matching/Timeline. 4. Composer/Versand/Templates. 5. Tracking/Domain/BCC/Anhänge. 6. Scheduling/Reminder/Bulk. Provider können einzeln per Feature-Flag deaktiviert werden. Disconnect widerruft Tokens und stoppt neue Jobs, löscht aber keine bereits auditierte Kommunikation. Forward-only-Migrationen enthalten Inverse-SQL. ## Quellen - `.planning/ticket-docs/VR-P28a.md`, `VA-P28b.md`, `VD-P28.md` - `docs/ARCHITECTURE-DECISIONS.md` — AD-21, AD-28, AD-31 - AGENTS.md — Admin-Hardgrenze, Estate-Mail/ClamAV, Layer-/Test-DoD ## Dev-Nachzug - [x] Tracking-/Datenschutzentscheidung aus gemeinsamer Block-Review festschreiben: standardmäßig aus, Tracking-Rohdaten 180 Tage. - [ ] Google-/Microsoft-Mail-Scopes, Redirects und Live-Testkonten als externe Proofs dokumentieren. - [ ] Legacy-Sequenz-/Sender-/Integration-Migration mit `AK-UI-19`/`AK-UI-20` nachziehen. - [ ] Davids `VD-P28`-Delta integrieren und Visual-Baselines erneuern. - [x] Interim-Screens aus bestehenden `~/ui`-Komponenten mit reinen View-Models, Action-Callbacks, Visual- und A11y-Baselines ausliefern.