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

8.6 KiB

MAIL-03 · HiveGrid-Systemmails visuell und textlich vereinheitlichen

Typ Launch-Härtung · Mail-UX / Branding
Owner Raffael
Phase Pilot-Härtung · CR-022
Cycle/Fenster gestartet 2026-08-02
Status Done
Plane HIVEGRID-245 · Issue 03e41c05-6b82-4085-8a33-9ad8eead9613

Abhängigkeiten & Parallelität

  • Blocked by: MAIL-01, MAIL-02 und I18N-01 sind Done. Mailjet-Zustellung, HTML-/Plaintext-Transport und der Sechs-Sprachen-Vertrag sind damit vorhanden.
  • Blocks: konsistentes Systemmail-Erlebnis für Pilotkunden; keine bestehende Code-Implementierung wird durch dieses Ticket blockiert.
  • Abhängigkeitsschutz: Sender-Domain, Mailjet, Queue-Namen, Retry, Idempotenz, Tracking-, Billing- und Datenbankverträge bleiben unverändert. I18N_ENABLED_LOCALES bleibt standardmäßig de,en; pl, uk, ru und hu werden durch diese Arbeit nicht freigeschaltet.
  • Plane-Prüfung: Ticket nach bestätigter Plane-Identität raffael als HIVEGRID-245 angelegt. Es besitzt keine blocked-by-/blocks-Relationen.

Was wir bauen

Alle fest von HiveGrid formulierten Systemmails verwenden einen gemeinsamen, responsiven Markenrahmen. Dazu gehören insbesondere Signup/Auth, Einladungen, Billing/Rechnungen, Plattformbenachrichtigungen, Buchungen, Signatur/Abnahme, Formulare/Double-Opt-in, DSGVO-Export, Customer-Portal-Authentifizierung und Portal-Lifecycle. Der Rahmen enthält:

  • das horizontale HiveGrid-Logo als absolut erreichbares HTTPS-Bild mit Textfallback und Link zu https://hivegrid.de;
  • klare Typografie und Informationshierarchie aus Anlass, Headline, Einleitung, optionaler Detailkarte, eindeutiger Hauptaktion und Sicherheitshinweis;
  • lokalisierte Preheader, HTML- und vollständige Plaintext-Versionen;
  • einen persönlichen, professionellen Abschluss als HiveGrid-Team;
  • Supportkontakt und die unveränderlichen Plattformlinks https://hivegrid.de/agb, https://hivegrid.de/datenschutz und https://hivegrid.de/impressum.

Bestehende rohe HTML-/Textpfade werden auf den zentralen Renderer umgestellt. Tenant-, Projekt-, Termin- und Absenderkontext bleibt sichtbar, ersetzt aber nicht die HiveGrid-Plattformidentität. Nutzergenerierte Kampagnen-, Workflow- und Portal-Template-Inhalte werden nicht redaktionell verändert.

Benötigte Screens

Keine App-Oberfläche. Die E-Mail-Artefakte werden als Desktop- und Mobile-HTML visuell geprüft. Der abschließende UAT versendet jede feste Kundenvariante wie im echten Betrieb an das freigegebene Postfach, ohne Testpräfix oder Testhinweis im sichtbaren Inhalt.

Definition of Done

  • Ein zentraler Mail-Brand-Adapter bildet @hivegrid/brand vollständig und typsicher auf den Mail-Theme-Vertrag ab; Logo, Farben, Support und Links gehen nicht durch Strukturunterschiede verloren.
  • Das zentrale Layout nutzt ein öffentliches horizontales HiveGrid-Logo, responsive E-Mail-kompatible Styles, abgestufte Textgrößen/-gewichte, zugängliche Kontraste, aussagekräftige Alt-Texte und einen verlinkten Textfallback.
  • AGB, Datenschutz und Impressum zeigen in jeder Plattform-Systemmail exakt auf die drei freigegebenen hivegrid.de-Ziele; Tenant-Konfiguration kann diese Plattformlinks nicht überschreiben.
  • Signup/Auth, Einladung, Billing/Rechnung und generische Notification- Templates erhalten die freigegebene persönlich-professionelle Tonalität, eindeutige CTA-Texte, sinnvolle Preheader, Sicherheits-/Ablaufhinweise und den Abschluss Viele Grüße / Dein HiveGrid-Team sinngemäß je Sprache und Anredeform.
  • Alle festen Runtime-Systemmails aus Web und Worker verwenden den gemeinsamen Renderer statt rohem Ein-Zeilen-HTML/Text; dynamische Detailwerte sind strukturiert, escaped und in HTML wie Plaintext präsent.
  • Alle neuen oder geänderten Texte existieren für de, en, pl, ru, uk und hu; Formal-Bundles fallen korrekt auf ihre Basissprache zurück. Keine Zielsprache wird produktiv aktiviert.
  • Renderingtests prüfen Logo, Plattformlinks, Preheader, CTA, Textversion, sichere URLs und das Fehlen roher Keys beziehungsweise unerlaubter Sprachfallbacks; die festen Kundenvarianten besitzen einen vollständigen Inventar-/Coverage-Vertrag.
  • Desktop- und Mobile-Rendering sind visuell abgenommen; lange lateinische und kyrillische Texte, deaktivierte Bilder und Dark-Mode-Farbanpassung bleiben lesbar.
  • Fokussierte Tests, pnpm typecheck, pnpm lint, pnpm test, pnpm run verify:i18n, verify:ci-baseline, verify:source-health und verify:secrets sind grün.
  • Alle festen Kundenvarianten wurden ohne Testkennzeichnung an raffaelsheikh@protonmail.com gesendet; Providerannahme und Inbox- Rendering sind dokumentiert.

Fortschritt: 10/10 DoD = 100 % done · 0 Punkte offen.

Technische Bausteine

  • packages/brand: kanonische öffentliche Logo- und Plattformlink-Tokens.
  • packages/mail/src/templates-react: Mail-Theme-Adapter, zentraler Rahmen, strukturierte Detail-/Hinweis-Komponenten und Renderer.
  • apps/web/app/modules/emails, Auth-, Booking-, Signatur-, Abnahme-, Formular- und Portal-Services: bestehende Versender auf den Renderer verdrahten.
  • apps/worker/src/jobs: Plattformnotification, Portal-Lifecycle, GDPR, Form-/Transactional-Outbox und Reminder auf denselben Vertrag umstellen.
  • apps/web/public/locales/*/mail.json: fachliche Mailtexte aller sechs Basissprachen; Formal-Overrides ausschließlich bei tatsächlicher Abweichung.

Nicht im Scope

  • Keine neue Mailkategorie und keine Änderung nutzergenerierter Kampagnen-, Workflow-, Sales- oder Portal-Template-Inhalte.
  • Kein Provider-, Sender-Domain-, Secret-, Queue-, Retry-, Idempotenz-, Tracking-, Billing-, Entitlement-, Schema- oder Migrationswechsel.
  • Keine Aktivierung von pl, uk, ru oder hu in Produktion.

Rollback

Reiner Code- und Katalog-Rollback auf den vorherigen Renderer und die bisherigen Versand-Call-Sites. Queue-Payloads bleiben rückwärtskompatibel; es gibt keine Datenmigration. Bereits zugestellte E-Mails sind externe Artefakte und können nicht zurückgerufen werden.

Quellen

  • docs/CHANGE-REQUESTS.md → CR-022.
  • MAIL-01, MAIL-02, I18N-01 und REQ-i18n-six-locale-outbound.
  • User-Freigabe im Chat vom 2026-08-02 für vollständiges Marken-/Text-Polish und realen Kundenmail-UAT.

Umsetzungs-Notiz

2026-08-02 · Ticket nach bestätigter Plane-Identität raffael als HIVEGRID-245 angelegt. Isolierte Session feat/mail-system-polish-20260802 basiert exakt auf origin/main fda162ea2; die bestehenden schmutzigen Worktrees bleiben unangetastet.

MAIL-03: 0/10 DoD = 0 % done. Offen: 10 Punkte, davon 0 blockiert.

2026-08-02 · Umsetzung atomar in 32f04667e (Mail-Foundation), 88b17bd27 (Kataloge), 1be0c8623 (Web-Wiring), cbcc813ba (Worker-Wiring) und 51f675b24 (Buchungserinnerungen): zentraler HiveGrid-Mailrahmen mit öffentlichem Logo, responsiver Typografie, WCAG-AA-Farbkontrasten, unveränderlichen Plattformlinks, lokalisierten HTML-/Plaintext-Texten und persönlicher Tonalität. Alle festen Web-/Worker-Systempfade wurden auf den gemeinsamen Renderer umgestellt. Das ausführbare Inventar umfasst 30 feste Kundenvarianten; Kampagnen, Workflows und kundeneigene Portal-Templates blieben unverändert.

Prüfnachweis: pnpm typecheck, pnpm lint, pnpm test (1.194 Testdateien, 8.317 Tests grün), pnpm run verify:i18n (6 Basis-Locales, 16.542 Keys in 9 Namespaces), pnpm run verify:i18n-performance (Delta 45,01 ms / 13,20 MB), verify:ci-baseline (35/35), verify:source-health (24/24), verify:secrets und verify:test-coverage grün. Die vier Review-Manifeste bleiben auf release.status: disabled; standardmäßig sind weiterhin ausschließlich de,en aktiviert.

Realer Versandnachweis: Mailjet hat am 2026-08-02 alle 30/30 Nachrichten an raffaelsheikh@protonmail.com angenommen. Erste Provider-ID 98192a83-b346-4dc4-9fce-a70a34c56312, letzte Provider-ID f3909bc0-cd90-4aff-9a98-8e6eb92e44d1. Sichtbarer Absendername: HiveGrid; Betreff und Inhalt enthalten keine Test-/UAT-Kennzeichnung. Der Empfänger hat die Inbox-/Sichtprüfung am 2026-08-02 mit „ok passt erstmal“ bestätigt.

MAIL-03: 10/10 DoD = 100 % done. Offen: 0 Punkte.