Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -0,0 +1,163 @@
<!-- markdownlint-disable MD013 MD060 -->
# 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
- [x] 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.
- [x] 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.
- [x] AGB, Datenschutz und Impressum zeigen in jeder Plattform-Systemmail
exakt auf die drei freigegebenen `hivegrid.de`-Ziele; Tenant-Konfiguration
kann diese Plattformlinks nicht überschreiben.
- [x] 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.
- [x] 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.
- [x] 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.
- [x] 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.
- [x] Desktop- und Mobile-Rendering sind visuell abgenommen; lange lateinische
und kyrillische Texte, deaktivierte Bilder und Dark-Mode-Farbanpassung
bleiben lesbar.
- [x] Fokussierte Tests, `pnpm typecheck`, `pnpm lint`, `pnpm test`,
`pnpm run verify:i18n`, `verify:ci-baseline`, `verify:source-health` und
`verify:secrets` sind grün.
- [x] 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.**