feat(PROJ-17): Admin Dashboard Systemauslastung immer anzeigen

- Systemauslastungs-Sektion wird immer gerendert (nicht nur bei Erfolg) - Fehlermeldung wenn /api/admin/system/stats nicht erreichbar ist - Feature-Status auf In Review gesetzt Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-14 11:43:19 +01:00
parent a893084a88
commit d360c9a5ba
68 changed files with 11938 additions and 435 deletions
@@ -0,0 +1,147 @@
+# 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_