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