81 lines
3.0 KiB
Markdown
81 lines
3.0 KiB
Markdown
# 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.
|