From ed5a00a57725f83edad6741687fce01a108be84f Mon Sep 17 00:00:00 2001 From: Bastian Wagner Date: Fri, 31 Jul 2026 22:09:59 +0200 Subject: [PATCH] docs: correct mail design spec after deeper env/infra investigation .env already exists locally with valid creds (the deleted repo-root .env was an unused duplicate), and no MailDev infra exists for the e2e mail tests, so the plan shifts to a MailService unit test plus one manual send instead of touching .env or standing up e2e infra. --- .../specs/2026-07-31-mail-versand-design.md | 64 ++++++++++++------- 1 file changed, 41 insertions(+), 23 deletions(-) diff --git a/docs/superpowers/specs/2026-07-31-mail-versand-design.md b/docs/superpowers/specs/2026-07-31-mail-versand-design.md index f9e5524..51dee01 100644 --- a/docs/superpowers/specs/2026-07-31-mail-versand-design.md +++ b/docs/superpowers/specs/2026-07-31-mail-versand-design.md @@ -9,15 +9,19 @@ Backend: NestJS (`myteamwallet_backend`), basierend auf `nestjs-boilerplate`. Ma `@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: +Der Mailversand funktioniert aktuell nicht. Ursache (nach genauerer Prüfung — korrigiert +gegenüber einer ersten Analyse): -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. +- `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: @@ -36,8 +40,11 @@ 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). +- **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, @@ -102,12 +109,10 @@ Wordmark-Schreibweise „TeamWallet". `firstName`, `url`, ggf. `year` fürs Footer-Copyright — Rest (Texte, Button-Label, Titel) fest im Template. -### 5. `.env` wiederherstellen +### 5. `.env` -- 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. +Keine Aktion nötig — `myteamwallet_backend/.env` existiert bereits lokal mit gültigen Werten +(siehe Kontext oben). ## Fehlerbehandlung @@ -119,14 +124,27 @@ Wordmark-Schreibweise „TeamWallet". ## 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. +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