170 lines
9.5 KiB
Markdown
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.
|