archivmail/features/PROJ-14-import-pop3.md

# PROJ-14: E-Mail-Import: POP3-Verbindung

## Status: In Progress
**Created:** 2026-03-13
**Last Updated:** 2026-03-13

## Dependencies
- Requires: PROJ-1 (Authentifizierung) – nur Admins verwalten POP3-Verbindungen
- Requires: PROJ-5 (Speicherung & Indexierung) – importierte E-Mails werden gespeichert

## Hinweis
POP3 kennt keine Ordnerstruktur – es gibt nur eine Inbox. Alle Mails werden importiert. Da POP3 keine UID-basierte Synchronisation unterstützt, ist nur ein einmaliger Initial-Import sinnvoll (kein regelmäßiger Sync wie bei IMAP).

## User Stories
- Als Admin möchte ich einen POP3-Server konfigurieren (Host, Port, Zugangsdaten), damit ich E-Mails von dort importieren kann.
- Als System möchte ich alle vorhandenen E-Mails vom POP3-Server herunterladen und archivieren.
- Als Admin möchte ich den Verbindungsstatus und Importfortschritt sehen.
- Als System möchte ich Duplikate (gleiche Message-ID) überspringen.

## Acceptance Criteria
- [ ] Konfigurationsformular: Host, Port, Verbindungsmodus (SSL/TLS, STARTTLS, None), Benutzername, Passwort
- [ ] **Verbindungsmodi:**
  - `SSL/TLS` – direkte TLS-Verbindung (Port 995)
  - `STARTTLS` – startet unverschlüsselt, wird auf TLS hochgestuft (Port 110)
  - `None` – unverschlüsselt, nur für lokale/Testumgebungen
- [ ] Verbindungstest vor dem Speichern (Timeout: 10 Sekunden)
- [ ] Passwörter AES-256-GCM verschlüsselt in der DB gespeichert
- [ ] Import: alle Mails vom Server herunterladen
- [ ] Duplikate (Message-ID) werden übersprungen
- [ ] Fortschrittsanzeige während Import (X von Y Mails)
- [ ] Abschlussbericht: importiert / übersprungen / Fehler
- [ ] Mails bleiben nach dem Import auf dem POP3-Server (kein DELE-Befehl)

## Edge Cases
- POP3-Server nicht erreichbar → Fehlermeldung mit Retry-Option
- Falsche Zugangsdaten → klare Fehlermeldung
- Mail ohne Message-ID → synthetische ID generieren (SHA-256 des Inhalts)
- Verbindungsabbruch während Import → bei Neustart von vorne (POP3 hat keine UIDs zum Weiterführen)
- Sehr großes Postfach (10.000+ Mails) → sequenzielles Herunterladen, kein Speicher-Overflow

## Technical Requirements
- **Verbindungsmodi:** SSL/TLS (Port 995), STARTTLS (Port 110), None
- POP3 unterstützt keine Ordner – es gibt nur die Inbox, keine Ordner-Erkennung nötig
- Kein regelmäßiger Sync – nur manueller Import (POP3 bietet keine zuverlässige Duplikatserkennung über Sessions hinaus)
- Zugangsdaten AES-256-GCM verschlüsselt in der DB

---
## Tech Design (Solution Architect)

### Komponentenstruktur

**Next.js Frontend (Admin-Bereich):**
```
/admin/pop3
├── POP3-Verbindungsliste
│   └── VerbindungsCard
│       ├── Name, Host, Status
│       ├── Letzter Import + Anzahl
│       └── Aktionen: Bearbeiten / Löschen / Import starten
├── Verbindung-Formular
│   ├── Host, Port, Verbindungsmodus (SSL/TLS | STARTTLS | None)
│   ├── Benutzername, Passwort
│   └── [Verbindung testen] Button
└── Import-Fortschrittsanzeige
    ├── Fortschrittsbalken
    └── Abschlussbericht
```

**Go Backend:**
```
POP3-Dienst
├── POST /api/admin/pop3           ← Verbindung anlegen
├── POST /api/admin/pop3/test      ← Verbindung testen
├── GET  /api/admin/pop3           ← auflisten
├── DELETE /api/admin/pop3/{id}    ← löschen
│
├── POP3-Client
│   ├── SSL/TLS + STARTTLS Handler
│   ├── USER/PASS Login
│   ├── STAT → Anzahl Mails + Gesamtgröße
│   ├── LIST → Message-Nummern
│   └── RETR → Mail herunterladen (kein DELE)
│
└── Import-Worker (Hintergrund-Goroutine)
    ├── Sequenziell: RETR 1, RETR 2, ...
    ├── Duplikat-Check (Message-ID)
    ├── → Storage Coordinator (PROJ-5)
    └── Fortschritt in DB
```

### Verbindungsmodus-Übersicht

| Modus | Port | Ablauf |
|-------|------|--------|
| `SSL/TLS` | 995 | TLS direkt beim Verbindungsaufbau |
| `STARTTLS` | 110 | Verbindung startet plain → STLS-Befehl → TLS |
| `None` | 110 | Unverschlüsselt (nur Testumgebung) |

### Importfluss

```
Admin klickt "Import starten"
        │
        ▼
POP3-Client verbindet (SSL/TLS oder STARTTLS)
        │
        ▼
STAT → Gesamtanzahl Mails (z.B. 3.842)
        │
        ▼
LIST → Message-Nummern [1, 2, 3, ..., 3842]
        │
        ▼
Für jede Message-Nummer:
  RETR <n> → rohe Mail (RFC 2822)
  Message-ID Duplikat? → überspringen
  → Storage Coordinator (PROJ-5)
  Fortschritt: n / 3842
        │
        ▼
Kein DELE → Mails bleiben auf dem Server
        │
        ▼
QUIT → Verbindung trennen
Abschlussbericht speichern
```

### Technische Entscheidungen

| Entscheidung | Begründung |
|---|---|
| **Kein DELE** | Archiv löscht nichts vom Quellserver – nur lesen und archivieren |
| **Kein regelmäßiger Sync** | POP3 hat keine UIDs – es gibt keine zuverlässige Möglichkeit festzustellen welche Mails bereits importiert wurden |
| **Synthetische Message-ID bei Fehlen** | POP3-Mails ohne Message-ID bekommen SHA-256(Inhalt) als ID – Duplikatserkennung bleibt konsistent |
| **Gleiche Codebasis wie IMAP-Worker** | Import-Worker-Struktur identisch – nur POP3-Client statt IMAP-Client |

### Abhängigkeiten

| Paket | Zweck |
|---|---|
| `github.com/emersion/go-message` | POP3-Client mit TLS/STARTTLS |

## QA Test Results
_To be added by /qa_

## Deployment
_To be added by /deploy_