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. Ursache (nach genauerer Prüfung — korrigiert
gegenüber einer ersten Analyse):

- `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. **Das ist die alleinige Ursache.**

Korrektur: die im Repo-Root gelöschte `.env` (Commit `1d4546d "styling"`, korrekt aus dem
Git-Tracking entfernt und zu `.gitignore` hinzugefügt) ist eine andere, von der App nicht
genutzte Datei. Die tatsächlich verwendete `myteamwallet_backend/.env` (das Arbeitsverzeichnis
der NestJS-App) existiert bereits lokal, ist bereits in `myteamwallet_backend/.gitignore`
ausgeschlossen und enthält bereits gültige `MAIL_*`/`DATABASE_*` Werte (Strato-SMTP,
lokale MySQL-Instanz läuft). Es ist **keine Aktion an `.env` nötig.**

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**: bleiben unangetastet — `myteamwallet_backend/.env` existiert bereits
  lokal mit gültigen Strato-Werten (keine Rotation im Rahmen dieser Änderung).
- **Testing-Infrastruktur**: kein lokaler MailDev-Container/e2e-Aufbau in diesem Zug (siehe
  Testing-Abschnitt) — Unit-Test + einmalige manuelle Verifikation mit echtem Versand
  stattdessen.
- **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`

Keine Aktion nötig — `myteamwallet_backend/.env` existiert bereits lokal mit gültigen Werten
(siehe Kontext oben).

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

Korrektur gegenüber einer ersten Analyse: der bestehende e2e-Test
`test/user/auth.e2e-spec.ts` ("Confirm email") pollt eine MailDev-HTTP-Inbox-API
(`MAIL_HOST:MAIL_CLIENT_PORT`). Dafür existiert im Repo keine Infrastruktur (kein
`docker-compose.yml`, kein MailDev-Container), und die echte `.env` zeigt auf produktives
Strato-SMTP statt auf eine lokale Test-Mailbox — dieser Test kann unabhängig vom Bugfix nicht
grün werden, ohne separate Test-Infrastruktur aufzusetzen. Entscheidung: kein MailDev-Aufbau in
diesem Zug (zu viel Zusatzaufwand für den aktuellen Scope).

Stattdessen:

- Neuer Jest Unit-Test für `MailService` (gemockter `MailerService`/`ConfigService`), der
  verifiziert, dass `userSignUp()` und `forgotPassword()` `sendMail(...)` mit den erwarteten
  Parametern (`to`, `subject`, `template`, `context`) aufrufen. Dieser Test hätte den
  `return;`-Bug erkannt und ist die primäre automatisierte Regression-Absicherung.
- Manuelle Verifikation: Backend lokal starten (bestehende `.env`, laufende lokale MySQL-Instanz
  vorhanden), einmal Registrierung und einmal Passwort-vergessen über die echten Endpunkte
  auslösen und den tatsächlichen Mailversand über Strato-SMTP mit einer echten Test-Mailadresse
  prüfen.
- Der bestehende e2e-Test bleibt unverändert im Repo (nicht Teil dieses Scopes, weiterhin ohne
  lokale MailDev-Instanz nicht lauffähig — vorbestehende Einschränkung, nicht durch diese Änderung
  verursacht). Kein neuer e2e-Test für forgot-password (gleiche Infrastruktur-Einschränkung).

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