mail und logging

docs/mail-templates.md

@@ -0,0 +1,80 @@
+# Mail Templates
+
+Das Backend nutzt `@nestjs-modules/mailer` mit dem vorhandenen `HandlebarsAdapter`. Templates liegen unter `apps/api/src/mail/templates` und werden beim API-Build nach `dist/mail/templates` kopiert.
+
+## Aufbau
+
+- `layouts/base.hbs`: gemeinsames HTML-Grundlayout mit Preheader, Header, Inhaltsbereich und Footer.
+- `partials/`: wiederverwendbare Bausteine fuer Header, Footer, Button, sekundaren Link, Info-Box, Warn-Box, Key-Value-Tabelle und Trennlinie.
+- `*.hbs`: HTML-Inhalt je Mailtyp.
+- `*.text.hbs`: bewusst gepflegte Plain-Text-Version je Mailtyp.
+
+Aktuelle Templates:
+
+- `password-reset`
+- `verification`
+- `email-change`
+- `registration-pending-approval`
+- `account-created`
+- `invitation`
+- `generic-notification`
+- `warning-notification`
+
+## Mail-Service
+
+Neue Mailtypen sollen ueber `PortalMailService` angebunden werden. Der Service setzt Betreff, Template-Namen, Branding-Daten, HTML-Kontext und Plain-Text-Version zentral. Direkte `mailer.sendMail(...)`-Aufrufe ausserhalb dieses Service sollen vermieden werden.
+
+Beispiel:
+
+```typescript
+await this.mail.sendPasswordResetMail({
+  recipient: user.email,
+  token,
+  expiresAt: resetToken.expiresAt,
+});
+```
+
+## Branding
+
+Branding wird zentral aus Environment-Variablen gelesen:
+
+- `MAIL_PRODUCT_NAME`
+- `MAIL_COMPANY_NAME`
+- `MAIL_PRIMARY_COLOR`
+- `MAIL_SUPPORT_EMAIL`
+- `MAIL_LOGO_URL`
+- `MAIL_IMPRINT_URL`
+- `MAIL_PRIVACY_URL`
+
+Falls diese Werte fehlen, verwendet das Backend kompatible Defaults aus der bestehenden Konfiguration, insbesondere `PUBLIC_WEB_URL` und `SMTP_FROM`.
+
+## Sicherheit
+
+Handlebars-Escaping bleibt aktiv. Benutzereingaben wie Anzeigenamen, E-Mail-Adressen und Nachrichtentexte werden mit normalem `{{value}}` gerendert. Unescaped Ausgabe wird nur in Plain-Text-Templates fuer serverseitig erzeugte Aktions-URLs verwendet, damit diese kopierbar bleiben.
+
+Nicht in Templates oder Logs aufnehmen:
+
+- Tokens als sichtbarer Text ausserhalb serverseitig erzeugter URLs
+- SMTP-Passwoerter oder Authorization-Daten
+- technische Stacktraces
+- ungeprueftes HTML aus Benutzereingaben
+
+## Lokale Vorschau
+
+Preview-Dateien koennen ohne Mailversand erzeugt werden:
+
+```bash
+npm run preview:mails -w @ldap-portal/api
+```
+
+Standardausgabe ist das Betriebssystem-Temp-Verzeichnis unter `ldap-portal-mail-previews`. Alternativ kann `MAIL_PREVIEW_DIR` gesetzt werden.
+
+## Build und Docker
+
+Das Projekt baut die API per `tsc`, nicht per `nest build`. Deshalb kopiert `scripts/copy-mail-assets.js` die Templates nach dem Compile nach `dist/mail/templates`. Die `nest-cli.json` enthaelt zusaetzlich eine Asset-Konfiguration fuer Umgebungen, die spaeter `nest build` nutzen.
+
+Die Dockerfiles kopieren das komplette API-`dist`; dadurch sind die Templates im Runtime-Container verfuegbar.
+
+## Internationalisierung
+
+Es gibt aktuell keine zentrale i18n-Loesung im Projekt. Die Templates verwenden daher die bestehende Standardsprache der Anwendung. Die Service-Inputs akzeptieren optional `locale`, damit spaetere Lokalisierung ohne neue Mail-Ausloeser moeglich bleibt.