georg/mailadler
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Name shortcut zu mailadler

Browse Source
This commit is contained in:
georg0480
2026-02-04 02:47:35 +01:00
parent f0af0d641f
commit f836c5cf34
27 changed files with 10494 additions and 908 deletions
Download Patch File Download Diff File Expand all files Collapse all files

579
TELEMETRIE_FEHLERBERICHTERSTATTUNG.md Normal file
View File

@@ -0,0 +1,579 @@
# Telemetrie & Fehlerberichterstattung System
## Übersicht
Mail-Adler wird ein optionales Fehlerberichterstattungs- und Telemetrie-System mit vollständiger Benutzerkontrolle implementieren.
## 1. Datenschutz & Benutzer-Einwilligung
### Installation & Onboarding
Bei der **ersten Anwendung** wird der Benutzer gefragt:
```
┌─────────────────────────────────────────────────┐
│ Mail-Adler Willkommen │
├─────────────────────────────────────────────────┤
│ │
│ Fehlerberichterstattung helfen, Mail-Adler │
│ zu verbessern. Ihre Privatsphäre ist │
│ wichtig: Keine persönlichen Daten werden │
│ ohne Ihre Zustimmung übertragen. │
│ │
│ ☐ Automatische Fehlerberichterstattung │
│ (Betriebssystem, Fehlertyp, Stack-Trace) │
│ │
│ ☐ Anonyme Nutzungsstatistiken │
│ (Feature-Nutzung, Sync-Erfolgsrate) │
│ │
│ [Ja, Standard aktiviert] [Nein, später] │
└─────────────────────────────────────────────────┘
```
**Standardverhalten:** Aktiviert (Benutzer wird informiert)
**Speicherort:** `~/.config/mail-adler/telemetry_consent.json`
```json
{
"version": 1,
"timestamp": "2025-02-03T12:00:00Z",
"error_reporting": true,
"usage_statistics": false,
"last_asked": "2025-02-03T12:00:00Z"
}
```
### Wiederholung
Alle 90 Tage wird der Benutzer erneut gefragt, ob die Einwilligung noch aktuell ist.
---
## 2. Fehlerberichterstattungs-Architektur
### 2.1 Fehlererfassung
#### Automatische Erfassung
```cpp
// src/telemetry/ErrorReporter.h/cpp
class ErrorReporter {
public:
static void reportError(
const QString &errorType, // z.B. "ImapConnectionFailed"
const QString &message, // Fehlermeldung
const QString &stackTrace, // Stack-Trace
const QMap<QString, QString> &context // Zusätzlicher Kontext
);
static void reportException(const std::exception &e);
static void reportWarning(const QString &warning);
};
```
#### Fehlertypen
| Fehler-ID | Beschreibung | Beispiel |
|-----------|-------------|---------|
| `IMAP_CONNECTION_FAILED` | IMAP-Verbindungsfehler | Timeout, SSL-Fehler |
| `SMTP_SEND_FAILED` | SMTP-Versandfehler | Auth-Fehler, Relay-Fehler |
| `DATABASE_ERROR` | SQLite-Fehler | Schema-Migration, Locking |
| `SYNC_FAILED` | Sync-Fehler | Netzwerkfehler, Konflikt |
| `CRASH` | Anwendungs-Crash | Segfault, Assertion |
| `UI_ERROR` | UI-Rendering-Fehler | Widget-Initialisierung |
### 2.2 Fehler-Kontext
Jeder Fehler enthält:
```json
{
"error_id": "unique-uuid-v4",
"error_type": "IMAP_CONNECTION_FAILED",
"message": "Connection timeout after 30s",
"timestamp": "2025-02-03T12:34:56.789Z",
"severity": "ERROR",
"system": {
"os": "Windows 11 (Build 22621)",
"os_version": "11.0.22621",
"architecture": "x86_64",
"cpu_cores": 8,
"memory_mb": 16384,
"qt_version": "6.4.2"
},
"application": {
"version": "0.1.0-beta",
"build_hash": "abc1234567",
"uptime_seconds": 3600,
"session_duration_seconds": 1800
},
"account_info": {
"account_id": "hash(account-uuid)", // Anonymisiert
"provider": "gmail", // "gmail", "gmx", "web.de", "telekom", etc.
"last_sync_minutes_ago": 15
},
"stack_trace": "...",
"additional_context": {
"operation": "ImapSync.incrementalFetch",
"retry_count": 2,
"network_available": true
},
"hash": "sha256(message+stacktrace)" // Zur Deduplizierung
}
```
### 2.3 Fehler-Deduplizierung
Wenn derselbe Fehler erneut auftritt:
```cpp
// Fehler wird NICHT erneut gesendet, sondern lokal gezählt
// Nach dem 1. Bericht: Zähler++ (lokal gespeichert)
// Nach 10 Vorkommen: Bericht mit occurrence_count: 10
// Speicherung in: ~/.config/mail-adler/error_cache.json
{
"sha256_hash_of_error": {
"first_occurrence": "2025-02-03T12:00:00Z",
"occurrence_count": 5,
"last_reported": "2025-02-03T13:00:00Z"
}
}
```
### 2.4 Fehler-Upload
**Trigger-Punkte:**
1. Unmittelbar nach kritischem Fehler (mit User-Bestätigung)
2. Täglich um 8:00 Uhr (gesammelt)
3. Beim Beenden der Anwendung
4. Nach WiFi/Netzwerk-Wiederherstellung
**Upload-Ziel:**
```
POST https://mail-adler-telemetry.example.com/api/v1/errors
Authorization: Bearer <api-key>
Content-Type: application/json
[
{ error_json_1 },
{ error_json_2 },
...
]
```
**Fehlerbehandlung beim Upload:**
- Lokal gecacht, wenn Netzwerk nicht verfügbar
- Max. 1000 Fehler gecacht (älteste werden verworfen)
- Keine Blockierung der UI während Upload
---
## 3. Nutzungsstatistiken
### 3.1 Sammlung (nur wenn aktiviert)
```json
{
"session_id": "uuid-v4",
"timestamp": "2025-02-03T12:00:00Z",
"application": {
"version": "0.1.0-beta"
},
"usage": {
"feature_usage": {
"imap_sync_count": 5,
"smtp_send_count": 2,
"read_messages_count": 50,
"compose_messages_count": 3
},
"sync_statistics": {
"successful_syncs": 98,
"failed_syncs": 2,
"average_sync_duration_seconds": 12.5,
"total_messages_synced": 1250
},
"ui_interactions": {
"features_used": ["MailList", "MailView", "Compose"],
"session_duration_seconds": 3600
}
},
"system": {
"os": "Windows 11",
"architecture": "x86_64"
}
}
```
**Upload:** Täglich um 8:00 Uhr (zusammen mit Fehlern)
---
## 4. Expert-Modus
### 4.1 Aktivierung
**Menü:** `Einstellungen → Expertenoptionen → Expert-Modus aktivieren`
```cpp
// src/telemetry/ExpertMode.h/cpp
class ExpertMode {
public:
bool isEnabled() const;
void setEnabled(bool enabled);
// Zeige Telemetrie-Daten an
void showSentErrorReports(); // Fehler, die zu uns gesendet wurden
void showReceivedUpdates(); // Updates, die von uns kamen
void showTelemetryLog(); // Vollständiges Telemetrie-Log
};
```
### 4.2 Expert-Modus UI
#### Fenster: "Telemetrie-Inspektor"
```
┌──────────────────────────────────────────────────────┐
│ Telemetrie-Inspektor [X] │
├──────────────────────────────────────────────────────┤
│ │
│ 📤 Zu uns gesendete Fehler │
│ ├─ 2025-02-03 12:34 | IMAP_CONNECTION_FAILED │
│ ├─ 2025-02-03 11:20 | SYNC_FAILED (5x) │
│ └─ 2025-02-02 15:45 | SMTP_SEND_FAILED │
│ │
│ 📥 Von uns empfangene Meldungen │
│ ├─ 2025-02-03 08:00 | Spam-Liste aktualisiert │
│ ├─ 2025-02-02 08:00 | Feature-Ankündigung │
│ └─ 2025-02-01 10:30 | Sicherheitsupdate │
│ │
│ [Details ansehen] [Export als JSON] │
└──────────────────────────────────────────────────────┘
```
#### Details-Ansicht (Fehler)
```json
{
"error_id": "uuid-1234",
"type": "IMAP_CONNECTION_FAILED",
"timestamp": "2025-02-03T12:34:56Z",
"status": "SENT",
"sent_at": "2025-02-03T13:00:00Z",
"message": "Connection timeout after 30s",
"stack_trace": "..."
}
```
---
## 5. Fehlerbehandlung mit Benutzer-Dialog
### 5.1 Kritischer Fehler
Wenn ein kritischer Fehler auftritt:
```
┌─────────────────────────────────────────────────┐
│ Ein Fehler ist aufgetreten │
├─────────────────────────────────────────────────┤
│ │
│ Ein unerwarteter Fehler hat die Anwendung │
│ beeinträchtigt. Helfen Sie, Mail-Adler zu │
│ verbessern, indem Sie diesen Fehler │
│ berichten. │
│ │
│ Fehlernummer: ERR-20250203-001 │
│ │
│ Was haben Sie zuvor getan? │
│ [______________________________] │
│ │
│ ☑ Fehler automatisch berichten │
│ │
│ [Bericht senden] [Verwerfen] │
└─────────────────────────────────────────────────┘
```
### 5.2 Fehler-Tracking
Nach Fehler wird gespeichert:
```json
{
"error_number": "ERR-20250203-001",
"type": "IMAP_CONNECTION_FAILED",
"timestamp": "2025-02-03T12:34:56Z",
"user_description": "Ich habe auf 'Synchronisieren' geklickt",
"was_reported": true,
"reported_at": "2025-02-03T12:35:00Z"
}
```
Wenn **derselbe Fehler erneut auftritt**:
- Lokale Fehler-ID erhöhen (ERR-20250203-002)
- Benutzer wird erneut gefragt
- Bericht mit Details über vorherige Fehlerberichte senden
---
## 6. Spam-Liste Service
### 6.1 Zentrale Spam-Datenbank
Täglich um 9:00 Uhr:
- Alle Benutzer melden lokale Spam-Markierungen
- Zentrale Datenbank aggregiert und dedupliziert
- Um 10:00 Uhr: Clients fragen aktualisierte Spam-Liste ab
### 6.2 Spam-Liste Schema
```json
{
"timestamp": "2025-02-03T09:00:00Z",
"version": "20250203-0900",
"entries": [
{
"email_hash": "sha256(spam@example.com)",
"type": "PHISHING",
"severity": 1.0,
"reported_count": 157,
"last_seen": "2025-02-03T08:45:00Z"
},
{
"email_hash": "sha256(spam2@example.com)",
"type": "BULK",
"severity": 0.7,
"reported_count": 43,
"last_seen": "2025-02-03T07:30:00Z"
}
]
}
```
### 6.3 Spam-Klassifikation
| Typ | Beschreibung | Aktion |
|-----|-------------|--------|
| `PHISHING` | Phishing/Social Engineering | Block alle |
| `MALWARE` | Malware-Quellen | Block alle |
| `SPAM_BULK` | Massenmails | Block für alle |
| `BLOCKED_BY_USER` | Einzelne Personen blockiert | Nur eigene Blockierung |
---
## 7. Tägliche Fehler-Zusammenfassung
### 7.1 Fehler-Zusammenfassung Email
**Täglich um 9:00 Uhr** sendet zentraler Service eine Email an `georg.dahmen@proton.me`:
```
Betreff: Mail-Adler Fehler-Zusammenfassung - 2025-02-03
─────────────────────────────────────────────────────
Gestrige Fehler (2025-02-02):
Kritische Fehler (2):
• IMAP_CONNECTION_FAILED (5 Benutzer, 12 Vorkommen)
→ Mögliche Ursache: TLS-Upgrade auf Gmail-Konten
→ Link: https://mail-adler-telemetry.example.com/errors/IMAP_CONNECTION_FAILED
• DATABASE_ERROR (1 Benutzer, 3 Vorkommen)
→ Mögliche Ursache: Schema-Migration fehlgeschlagen
→ Link: https://mail-adler-telemetry.example.com/errors/DATABASE_ERROR
Warnungen (8):
• SYNC_FAILED (18 Benutzer)
• UI_ERROR (4 Benutzer)
...
Spam-Report:
• 242 neue Spam-Quellen gemeldet
• Top 5: phishing@attacker1.com, spam@bulkmail2.ru, ...
Nutzungsstatistiken:
• Aktive Benutzer: 1,250
• Durchschn. Sync-Erfolgsrate: 98.3%
• Durchschn. Session-Dauer: 35 Minuten
─────────────────────────────────────────────────────
Vollständiger Bericht: https://mail-adler-telemetry.example.com/reports/2025-02-02
```
---
## 8. Client-Update Mechanismus
### 8.1 Update-Check
**Täglich um 8:00 Uhr** fragt Client ab:
```
GET /api/v1/updates?version=0.1.0-beta&os=windows&arch=x86_64
```
**Antwort:**
```json
{
"current_version": "0.1.0-beta",
"latest_version": "0.2.0",
"update_available": true,
"critical": false,
"download_url": "https://...",
"release_notes": "...",
"checksum": "sha256=..."
}
```
### 8.2 Update-Dialog
Wenn Update verfügbar:
```
┌─────────────────────────────────────────────────┐
│ Update verfügbar: Mail-Adler 0.2.0 │
├─────────────────────────────────────────────────┤
│ │
│ Neue Features: │
│ • Multi-Account Unterstützung │
│ • Verbesserte Verschlüsselung │
│ • 5 Bugfixes │
│ │
│ Größe: 45 MB │
│ │
│ [Jetzt aktualisieren] [Später] │
└─────────────────────────────────────────────────┘
```
---
## 9. Datenspeicherung (Server-Seite)
### 9.1 Fehler-Datenbank
```sql
CREATE TABLE telemetry_errors (
id INTEGER PRIMARY KEY AUTOINCREMENT,
error_id TEXT UNIQUE NOT NULL,
error_type TEXT NOT NULL,
message TEXT,
severity TEXT,
system_os TEXT,
system_arch TEXT,
app_version TEXT,
account_provider TEXT, -- "gmail", "gmx", "web.de", etc.
stack_trace TEXT,
hash TEXT UNIQUE, -- Für Deduplizierung
timestamp DATETIME,
occurrence_count INTEGER DEFAULT 1,
INDEX idx_error_type (error_type),
INDEX idx_timestamp (timestamp),
INDEX idx_hash (hash)
);
```
### 9.2 Aufbewahrungsrichtlinie
- **Detaillierte Fehler:** 90 Tage
- **Aggregierte Statistiken:** 1 Jahr
- **Spam-Liste:** Permanent (mit Deduplizierung)
---
## 10. Sicherheit & Datenschutz
### 10.1 Verschlüsselung
- Alle Übertragungen: **HTTPS/TLS 1.3**
- Passwörter/Tokens: **Keine** im Telemetrie-Daten
- Stack-Traces: Redaktioniert, um Dateipfade zu verbergen
### 10.2 Anonymisierung
- Account-ID: **gehashed** (SHA256)
- Benutzernamen: **nicht erfasst**
- IP-Adressen: **nicht gespeichert**
- Email-Adressen: Nur gehashed (für Spam-Liste)
### 10.3 Benutzerkontrolle
```cpp
// src/telemetry/TelemetrySettings.h
class TelemetrySettings {
public:
bool errorReportingEnabled() const;
void setErrorReportingEnabled(bool enabled);
bool usageStatisticsEnabled() const;
void setUsageStatisticsEnabled(bool enabled);
// Daten exportieren
void exportAllTelemetryData(const QString &filePath);
// Daten löschen
void deleteAllLocalTelemetryData();
void deleteOldTelemetryData(int daysOld);
};
```
---
## 11. Implementierungs-Roadmap
### Phase 1: Fehlerberichterstattungs-Kern
- [ ] ErrorReporter Klasse
- [ ] Error-JSON Schema
- [ ] Fehler-Deduplication
- [ ] Lokale Caching-Logik
### Phase 2: Server-Infrastruktur
- [ ] Telemetry-API Server aufsetzen
- [ ] Fehler-Datenbank
- [ ] Spam-Liste Service
- [ ] Update-Check Endpoint
### Phase 3: Client-Integration
- [ ] Fehler-Dialog UI
- [ ] Expert-Modus
- [ ] Onboarding-Consent Dialog
- [ ] Tägliche Synchronisierung
### Phase 4: Monitoring & Analyse
- [ ] Dashboard für Entwickler
- [ ] Fehler-Trends Analyse
- [ ] Spam-Statistiken
- [ ] Tägliche Summary-Emails
---
## 12. Kontakt & Support
**Fehlerberichterstattung:** georg.dahmen@proton.me
**Sicherheitsbedenken:** security@mail-adler.dev
**Datenschutz:** privacy@mail-adler.dev
---
## 13. FAQ
**F: Werden meine Passwörter übertragen?**
A: Nein. Passwörter und API-Tokens werden niemals in Fehlerberichten erfasst.
**F: Kann ich Telemetrie deaktivieren?**
A: Ja. Einstellungen → Datenschutz → Telemetrie-Optionen.
**F: Wie lange werden Fehler gespeichert?**
A: 90 Tage detaillierte Fehler, dann aggregierte Statistiken für 1 Jahr.
**F: Sind meine Daten exportierbar?**
A: Ja. Einstellungen → Datenschutz → "Alle Telemetrie-Daten exportieren".
**F: Kann ich einen Fehler manuell löschen?**
A: Ja. Expert-Modus → Telemetrie-Inspektor → Fehler auswählen → Löschen.