archivmail/features/PROJ-12-export.md

# PROJ-12: E-Mail-Export (EML / PDF)

## Status: In Review
**Created:** 2026-03-12
**Last Updated:** 2026-03-14

## Dependencies
- Requires: PROJ-1 (Authentifizierung)
- Requires: PROJ-6 (Volltext-Suche) – Export aus Suchergebnissen
- Requires: PROJ-7 (E-Mail-Ansicht)
- Requires: PROJ-11 (Audit-Log) – Export-Aktionen werden geloggt

## User Stories
- Als Nutzer möchte ich eine einzelne E-Mail als EML-Datei exportieren, damit ich sie in einem E-Mail-Client öffnen kann.
- Als Nutzer möchte ich eine E-Mail als PDF drucken/exportieren, damit ich sie für Behörden oder Verträge verwenden kann.
- Als Admin möchte ich mehrere E-Mails als ZIP-Archiv exportieren, damit ich bei einer Anfrage mehrere Mails auf einmal liefern kann.
- Als System möchte ich jeden Export im Audit-Log erfassen.

## Acceptance Criteria
- [ ] Einzelexport EML: Original-MIME-Inhalt wird unverändert heruntergeladen
- [ ] Einzelexport PDF: E-Mail-Header + Body als gut lesbares PDF gerendert, Anhänge als separate Dateien erwähnt
- [ ] Massenexport: Auswahl mehrerer E-Mails (Checkbox in Suchergebnissen), ZIP-Download
- [ ] ZIP enthält: EML-Dateien + optionale Anhänge + Manifest (CSV mit Metadaten)
- [ ] Massenexport-Limit konfigurierbar (Standard: max. 500 E-Mails pro Export)
- [ ] Jeder Export wird im Audit-Log erfasst (Nutzer, Anzahl E-Mails, Format)
- [ ] Zugriffsschutz: Nutzer kann nur eigene E-Mails exportieren

## Edge Cases
- Export von 500 E-Mails mit großen Anhängen → Streaming-ZIP, kein Speicher-Overflow
- PDF-Rendering von komplexem HTML → graceful Fallback auf Plain-Text-PDF
- Nutzer wählt E-Mails aus, auf die er keinen Zugriff hat → diese werden aus Export-Liste entfernt

## Technical Requirements
- ZIP-Erstellung als Stream (nicht komplett in Memory)
- PDF-Generierung serverseitig (z.B. wkhtmltopdf oder Go-PDF-Bibliothek)

---
## Tech Design (Solution Architect)

### Komponentenstruktur

**Next.js Frontend:**
```
Suchergebnisse (PROJ-6, Erweiterung)
├── Checkbox pro Treffer (Multi-Select)
├── [Exportieren] Button (aktiv wenn ≥1 ausgewählt)
└── Export-Dialog
    ├── Format: EML | PDF
    ├── Anhänge einschließen: ja / nein
    └── [Download starten] → POST /api/export/zip (Streaming)

E-Mail-Ansicht (PROJ-7, Erweiterung)
├── [Als EML herunterladen] Button  → GET /api/export/eml/{id}
└── [Als PDF exportieren] Button    → GET /api/export/pdf/{id}
```

**Go Backend:**
```
Export-Handler
├── GET /api/export/eml/{id}        ← Einzelexport EML
│   └── Original-.m-Datei lesen, AES-256-GCM entschlüsseln, direkt streamen
│
├── GET /api/export/pdf/{id}        ← Einzelexport PDF
│   ├── .m-Datei lesen + entschlüsseln
│   ├── Header + Body extrahieren
│   └── → PDF-Bibliothek → PDF streamen
│       Fallback: Plain-Text-PDF wenn HTML zu komplex
│
└── POST /api/export/zip            ← Massenexport
    ├── Body: { ids: [...], format: "eml"|"pdf", attachments: bool }
    ├── Zugriffscheck: Nutzer darf nur eigene Mails exportieren
    ├── Max-Limit prüfen (konfigurierbar, Standard: 500)
    ├── Streaming-ZIP (archive/zip Writer → ResponseWriter direkt)
    │   ├── Pro Mail: <message_id>.eml oder <message_id>.pdf
    │   ├── Anhänge: attachments/<hash>/<filename> (wenn aktiviert)
    │   └── manifest.csv (Message-ID, From, To, Subject, Date, Dateiname)
    └── → Audit-Log: export_start + export_done (Anzahl, Format)
```

### Export-Fluss (Massenexport)

```
POST /api/export/zip
        │
        ├── Zugriffsfilter: IDs auf user-eigene Mails beschränken
        │
        ├── Audit-Log: export_start
        │
        ├── ZIP-Stream öffnen (Content-Type: application/zip)
        │
        └── Für jede Mail:
              .m-Datei lesen → AES-256-GCM entschlüsseln
              → Zu ZIP hinzufügen (kein vollständiges RAM-Buffering)
              ↓
            manifest.csv Zeile anhängen
              ↓
            ZIP schließen → Audit-Log: export_done
```

### Technische Entscheidungen

| Entscheidung | Begründung |
|---|---|
| **Streaming-ZIP** | 500 Mails mit Anhängen können mehrere GB sein — kein RAM-Overhead |
| **Serverseitiges PDF** | Browser-Print ist nicht reproduzierbar; serverseitiges PDF ist auditierbar und einheitlich |
| **Plain-Text-Fallback für PDF** | Komplexes HTML kann PDF-Renderer zum Absturz bringen — graceful degradation |
| **Zugriffscheck im Export-Handler** | Serverseitige Filterung verhindert Datenlecks durch manipulierte IDs |
| **manifest.csv im ZIP** | Nachvollziehbarkeit bei Behördenanfragen ohne jede EML einzeln öffnen zu müssen |
| **Audit-Log für jeden Export** | Compliance-Anforderung — wer hat wann was exportiert |

### Abhängigkeiten

| Paket | Zweck |
|---|---|
| `archive/zip` (Stdlib) | Streaming-ZIP-Erstellung ohne externe Abhängigkeit |
| `github.com/SebastiaanKlippert/go-wkhtmltopdf` | PDF-Generierung aus HTML (serverseitig) |

## Implementation Notes (2026-03-14)

### What was built

**Go Backend — `internal/api/export.go` (new file):**
- `GET /api/export/pdf/{id}` — generates a stdlib-only PDF (no external deps) using raw PDF 1.4 syntax with Helvetica core font. Renders header fields, plain-text body (with HTML-strip fallback), and attachment list. `toLatinSafe()` converts umlauts for Latin-1 compatibility.
- `POST /api/export/zip` — streaming ZIP via `archive/zip` stdlib. Accepts `{"ids":[...], "attachments": true}`, max 500 IDs. Adds `{id[:16]}.eml`, optional `attachments/{id[:8]}/{filename}` entries, and `manifest.csv` (CSV with filename/message_id/from/to/subject/date). Audit-logged as `export: zip: N mails`.
- Both handlers use `requireMailAccess` middleware (blocks admin role). RoleUser is filtered to own mails via `mailBelongsToUser`; RoleAuditor can export all.

**Deviation from spec:** PDF generation uses a hand-rolled stdlib PDF writer instead of `go-wkhtmltopdf` or `go-pdf/fpdf` — avoids adding an external dependency that would require `go get` on the server.

**Routes added to `internal/api/server.go`:**
- `GET /api/export/pdf/{id}`
- `POST /api/export/zip`

**Frontend `src/lib/api.ts`:**
- Added `exportMailPDF(id)` and `exportMailsZIP(ids, attachments)` export functions.

**Frontend `src/app/mail/[id]/page.tsx`:**
- Added "Als PDF exportieren" button next to "Als .eml herunterladen".

**Frontend `src/app/search/page.tsx`:**
- Added per-row Checkbox column + select-all header checkbox.
- Export toolbar appears when ≥1 mail is selected.
- ZIP export dialog with attachments toggle (Switch component).
- Selection cleared when search results change.

## QA Test Results
_To be added by /qa_

## Deployment
_To be added by /deploy_