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

170 lines
9.5 KiB
Markdown

# 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.