Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/VA-P28c.md
T

9.5 KiB

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

  • AdminDataConnection und verschlüsselter Admin-Credential-Store stehen providerneutral; Google Workspace und Microsoft 365 können pro AdminUser verbunden, erneuert und getrennt werden.
  • Inbound-/Sent-Sync ist inkrementell und idempotent; Recovery-Polling, Webhooks, Cursor, Message-IDs und Provider-Dubletten sind getestet.
  • Matching zu Kontakt, Lead und Deal ist deterministisch; unsichere Treffer landen in einer sichtbaren Zuordnungsqueue und werden nie still falsch verknüpft.
  • Composer, Threading, persönliche Signatur, Vorlagen, Platzhalter und Snippets erfüllen MAIL-04, MAIL-05, MAIL-13..15.
  • Anhänge erfüllen MAIL-06, laufen fail-closed durch Größenlimit/ClamAV und liegen im EU-Storage mit auditierter Deal-Verknüpfung.
  • 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.
  • SPF/DKIM-Domainstatus und eindeutige, spoofing-geschützte BCC-Ingestion erfüllen MAIL-11/MAIL-12.
  • 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.
  • 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

  • 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.
  • Interim-Screens aus bestehenden ~/ui-Komponenten mit reinen View-Models, Action-Callbacks, Visual- und A11y-Baselines ausliefern.