teamwallet/docs/superpowers/specs/2026-07-31-mail-versand-design.md

Mailversand reparieren + Templates neu gestalten

Status: approved Datum: 2026-07-31

Kontext

Backend: NestJS (myteamwallet_backend), basierend auf nestjs-boilerplate. Mailversand über @nestjs-modules/mailer (Nodemailer) mit Handlebars-Templates. E-Mails werden für zwei Flows verschickt: Registrierung (Bestätigungsmail) und Passwort vergessen.

Der Mailversand funktioniert aktuell nicht, aus zwei unabhängigen Gründen:

1. src/mail/mail.service.ts — sowohl userSignUp() als auch forgotPassword() haben ein totes return; als erste Anweisung, noch vor dem eigentlichen mailerService.sendMail(...) Aufruf. Der Versand-Code wird nie erreicht.
2. .env existiert lokal nicht mehr im Arbeitsverzeichnis (im Commit 1d4546d "styling" wurde die Datei korrekt aus dem Git-Tracking entfernt und zu .gitignore hinzugefügt — das war bereits vor diesem Spec erledigt). Ohne .env sind alle MAIL_*/DATABASE_*/etc. Umgebungsvariablen undefined, die App kann so nicht sinnvoll laufen.

Zusätzlich bestehende Baustellen, die in diesem Zug mit erledigt werden:

• E-Mail-Templates (activation.hbs, reset-password.hbs) sind unverändertes, unstyled Boilerplate aus dem nestjs-boilerplate Scaffold (graue Kopfzeile, generischer Button, kein Branding).
• Die E-Mail-Texte laufen aktuell über nestjs-i18n, das ausschließlich für diese zwei Mails genutzt wird und nur eine en-Locale hat, obwohl das Produkt (myteamwallet.de) deutschsprachig ist. Entscheidung (siehe unten): nestjs-i18n komplett entfernen, Texte direkt auf Deutsch im Code/Template.

Das Frontend (myteamwallet_frontend_modern, das aktuell aktiv gebaute/deployte Frontend laut Dockerfile) hat kein fertiges Bild-Logo — nur generische Angular-Default-Icons. Als Markenfarbe dient das dort verwendete Grün #2e7d32 (Material theme-color), Schriftart Roboto, Wordmark-Schreibweise „TeamWallet".

Entscheidungen aus dem Brainstorming

• SMTP-Zugangsdaten: das alte, aus der Git-Historie wiederhergestellte Strato-Passwort wird vorerst weiterverwendet (keine sofortige Rotation im Rahmen dieser Änderung).
• Sprachen: nur Deutsch. Keine mehrsprachige i18n-Infrastruktur für Mails.
• i18n-Mechanismus: kein Sprachdatei-System — deutsche Texte direkt im Code/Template. nestjs-i18n wird komplett entfernt (Modul-Registrierung, src/i18n/, Dependency, I18n-Nutzung in mail.service.ts), da es im Backend ausschließlich für die zwei Mails verwendet wurde.
• Branding: Grün #2e7d32 (aus myteamwallet_frontend_modern), Textwordmark „TeamWallet" (kein Bild-Logo), Roboto mit System-Font-Fallback, abgerundete Card-Optik passend zum „fintech-lite" Look der App.
• Personalisierung: Anrede mit Vornamen („Hallo Max,"), da firstName an beiden Aufrufstellen im AuthService bereits verfügbar ist.

Architektur / Komponenten

1. Bugfix mail.service.ts

• Die zwei toten return; Statements entfernen (vor sendMail in userSignUp() und forgotPassword()).
• I18n/I18nRequestScopeService Constructor-Injection entfernen.
• Betreffzeilen als deutsche String-Literale direkt im Service ('E-Mail bestätigen', 'Passwort zurücksetzen').
• MailData<T> Interface (src/mail/interfaces/mail-data.interface.ts) bleibt strukturell gleich ({ to: string; data: T }), T wird pro Aufruf um firstName?: string erweitert: MailData<{ hash: string; firstName?: string }>.

2. Aufrufstellen auth.service.ts

• register(): dto.firstName zusätzlich in mailData.data durchreichen.
• forgotPassword(): user.firstName zusätzlich in mailData.data durchreichen.
• Keine Änderung an Kontrollfluss, Fehlerbehandlung oder DB-Zugriffen — nur die zusätzliche Datenübergabe.

3. i18n-Entfernung

• app.module.ts: I18nModule.forRootAsync(...) Import und Registrierung entfernen (HeaderResolver-Import ebenfalls, falls sonst ungenutzt).
• src/i18n/ Ordner komplett löschen (nur von Mails genutzt, siehe Analyse).
• nestjs-i18n Dependency aus package.json entfernen (npm uninstall, damit Lockfile konsistent bleibt).
• app.config.ts Felder fallbackLanguage/headerLanguage (APP_FALLBACK_LANGUAGE, APP_HEADER_LANGUAGE) werden mit entfernt: geprüft, sie werden ausschließlich in app.module.ts für I18nModule gelesen (kein anderer Konsument im Code) — würden sonst toten Config-Code hinterlassen.

4. Templates

• Neues Handlebars-Partial src/mail/mail-templates/partials/layout-header.hbs und layout-footer.hbs (oder ein kombiniertes layout.hbs, falls das mit dem HandlebarsAdapter sauberer registrierbar ist) — gemeinsamer Rahmen: Header mit „TeamWallet"-Wordmark auf grünem/hellem Grund, Footer mit Kontakt-/Legal-Hinweis (z. B. „Diese E-Mail wurde automatisch von TeamWallet verschickt.").
• activation.hbs: nutzt das Layout, Inhalt: Begrüßung mit {{firstName}} (Fallback ohne Namen falls nicht vorhanden), kurzer Erklärtext, grüner CTA-Button „E-Mail bestätigen" → {{url}}.
• reset-password.hbs: nutzt das Layout, Inhalt: Begrüßung, Erklärtext, grüner CTA-Button „Passwort zurücksetzen" → {{url}}, Hinweis auf zeitliche Begrenzung des Links und dass die Mail ignoriert werden kann, falls nicht selbst angefragt.
• Styling-Konstanten: Akzent #2e7d32, Radius ~12px auf Card-Container, max-width: 600px, Inline-CSS (kein externes Stylesheet — E-Mail-Client-Kompatibilität), tabellenbasiertes Layout wie bisher (kein MJML — unnötige Build-Komplexität für zwei Templates), Roboto mit Fallback-Stack (Roboto, Helvetica, Arial, sans-serif, da Web-Fonts in vielen Mail-Clients nicht geladen werden).
• Kontext-Variablen, die mail.service.ts an Handlebars übergibt: app_name ("TeamWallet"), firstName, url, ggf. year fürs Footer-Copyright — Rest (Texte, Button-Label, Titel) fest im Template.

5. .env wiederherstellen

• Lokale, nicht getrackte .env Datei neu anlegen (Datei existiert nicht mehr im Working Tree, ist aber in .gitignore) mit den aus git show 7df5611:.env wiederhergestellten Werten (DB-, Mail-, JWT- und App-Konfiguration wie zuvor).
• Kein Commit dieser Datei — bleibt lokal/untracked, wie vom User entschieden.

Fehlerbehandlung

• Kein Verhaltensunterschied zu heute beabsichtigt: mailerService.sendMail(...) wirft bei SMTP-Fehlern eine Exception, die aktuell nicht speziell abgefangen wird (weder vorher noch nachher) — das bleibt so, ist außerhalb des Scopes dieser Änderung. Falls beim Testen ein SMTP- Fehler auftritt (z. B. Strato blockiert alte/rotierte Zugangsdaten), wird das separat besprochen statt stillschweigend Fehlerbehandlung hinzuzufügen.

Testing

• Bestehenden e2e-Test test/user/auth.e2e-spec.ts (Confirm-Email-Flow über MailDev-artige HTTP-Inbox-API) laufen lassen und verifizieren, dass er jetzt grün ist (war zuvor durch den Bug automatisch rot).
• Neuer e2e-Test für den Forgot-Password-Mail-Flow, analog zum bestehenden Confirm-Email-Test: Passwort-vergessen anfragen, Mail über MailDev-Inbox abrufen, Hash extrahieren, gegen /api/v1/auth/reset/password verifizieren.
• Kein Unit-Test-Aufbau für MailService vorgesehen (kein bestehendes Muster im Repo für Mail-Unit-Tests, e2e deckt das Verhalten ausreichend ab) — YAGNI.

Out of Scope

• Rotation der SMTP-Zugangsdaten (User macht das ggf. später selbst).
• Mehrsprachigkeit / weitere Locales.
• Redesign der Frontend-Flows, die auf /confirm-email/:hash bzw. /password-change/:hash linken.
• MJML- oder Build-Pipeline-Einführung für Templates.