Hetzner-Backup/refactoring.md

v2-Docker Admin Panel Refactoring

Übersicht

Dieses Dokument beschreibt den aktuellen Stand des Refactorings der v2-Docker Admin Panel Anwendung und die geplanten nächsten Schritte.

Ziele des Refactorings

• Bessere Code-Organisation: Aufteilung der monolithischen 5000+ Zeilen app.py
• Wartbarkeit: Modulare Struktur für einfachere Wartung und Erweiterungen
• Testbarkeit: Unabhängige Module können isoliert getestet werden
• Skalierbarkeit: Vorbereitung für zukünftige Features

Phase 1: Modularisierung (✅ Abgeschlossen)

Erreichte Verbesserungen

• Code-Reduktion: Von 5.021 auf 4.445 Zeilen (-576 Zeilen)
• Klare Trennung: Funktionalität in logische Module aufgeteilt
• Wiederverwendbarkeit: Zentrale Funktionen verfügbar

Neue Struktur

v2_adminpanel/
├── app.py (Hauptanwendung, reduziert)
├── config.py (Zentrale Konfiguration)
├── db.py (Datenbank-Management)
├── models.py (Datenmodelle)
├── auth/
│   ├── decorators.py (Login-Required, Session-Management)
│   ├── password.py (Passwort-Hashing mit bcrypt)
│   ├── rate_limiting.py (IP-Blocking, Login-Versuche)
│   └── two_factor.py (TOTP, QR-Codes, Backup-Codes)
├── utils/
│   ├── audit.py (Audit-Logging)
│   ├── backup.py (Verschlüsselte Backups)
│   ├── export.py (Excel-Export Funktionen)
│   ├── license.py (Lizenzschlüssel-Generierung)
│   ├── network.py (IP-Ermittlung)
│   └── recaptcha.py (reCAPTCHA-Verifikation)
└── routes/
    ├── auth_routes.py (Blueprint vorbereitet)
    └── admin_routes.py (Blueprint vorbereitet)

Implementierte Module

1. Konfiguration (config.py)

• Alle Flask-Einstellungen
• Datenbank-Konfiguration
• Rate-Limiting Parameter
• Backup-Einstellungen
• reCAPTCHA Keys

2. Datenbank (db.py)

• Connection Management mit Context Managers
• Helper-Funktionen für Queries
• Automatisches Commit/Rollback
• UTF-8 Encoding sichergestellt

3. Authentication (auth/)

• decorators.py: Login-Required mit 5-Minuten Session-Timeout
• password.py: Sichere Passwort-Hashes mit bcrypt
• two_factor.py: TOTP-basierte 2FA mit Backup-Codes
• rate_limiting.py: Schutz vor Brute-Force-Angriffen

4. Utilities (utils/)

• audit.py: Vollständiges Audit-Logging mit IP und User-Agent
• backup.py: Verschlüsselte PostgreSQL-Backups mit Fernet
• license.py: Lizenzschlüssel im Format AF-[F/T]-YYYYMM-XXXX-YYYY-ZZZZ
• export.py: Excel-Export für verschiedene Datentypen
• network.py: Client-IP Ermittlung hinter Nginx Proxy
• recaptcha.py: Google reCAPTCHA v2 Integration

Phase 2: Blueprint-Architektur (⚠️ Teilweise implementiert)

Erstellte Blueprints

1. Auth Blueprint (routes/auth_routes.py)

Enthält alle authentifizierungsbezogenen Routes:

• /login - Login-Seite mit Rate-Limiting und reCAPTCHA
• /logout - Session-Beendigung
• /verify-2fa - 2FA-Verifizierung
• /profile - Benutzerprofil
• /profile/change-password - Passwort ändern
• /profile/setup-2fa - 2FA einrichten
• /profile/enable-2fa - 2FA aktivieren
• /profile/disable-2fa - 2FA deaktivieren
• /heartbeat - Session Keep-Alive

2. Admin Blueprint (routes/admin_routes.py)

Enthält administrative Funktionen:

• / - Dashboard mit Statistiken
• /audit - Audit-Log Viewer
• /backups - Backup-Verwaltung
• /backup/create - Manuelles Backup
• /backup/restore/<id> - Backup wiederherstellen
• /backup/download/<id> - Backup herunterladen
• /backup/delete/<id> - Backup löschen
• /security/blocked-ips - Gesperrte IPs verwalten
• /security/unblock-ip - IP entsperren
• /security/clear-attempts - Login-Versuche zurücksetzen

Aufgetretene Herausforderungen

1. Route-Konflikte: Doppelte Definitionen zwischen app.py und Blueprints
2. Zirkuläre Imports: Gegenseitige Abhängigkeiten zwischen Modulen
3. URL-Referenzen: url_for() muss Blueprint-Namen verwenden

Nächste Schritte

Option 1: Schrittweise Migration (⭐ Empfohlen)

# Blueprints mit Präfixen registrieren
app.register_blueprint(auth_bp, url_prefix='/auth')
app.register_blueprint(admin_bp, url_prefix='/admin')

# Redirects von alten URLs
@app.route('/login')
def legacy_login():
    return redirect(url_for('auth.login'))

Vorteile:

• Keine Breaking Changes
• Schrittweise Migration möglich
• Einfaches Rollback

Option 2: Feature-Flag Ansatz

if os.getenv('USE_BLUEPRINTS', 'false').lower() == 'true':
    app.register_blueprint(auth_bp)
    app.register_blueprint(admin_bp)
else:
    # Alte Routes verwenden
    from legacy_routes import *

Option 3: Parallelbetrieb

• Separate Docker-Container für Test
• A/B Testing möglich
• Höherer Ressourcenverbrauch

Verbleibende Aufgaben

Phase 2 Fertigstellung

• License Blueprint (routes/license_routes.py)
• Customer Blueprint (routes/customer_routes.py)
• Resource Blueprint (routes/resource_routes.py)
• API Blueprint (routes/api_routes.py)
• Export Blueprint (routes/export_routes.py)

Phase 3: Model Layer

• User Model mit ORM-ähnlicher Struktur
• License Model mit Validierung
• Customer Model mit Beziehungen
• Resource Model mit Status-Management

Phase 4: Service Layer

• Business Logic von Routes trennen
• Transaktions-Management
• Caching-Layer

Phase 5: Testing

• Unit Tests für alle Module
• Integration Tests für Blueprints
• End-to-End Tests für kritische Workflows
• Performance Tests

Migrations-Strategie

1. Vorbereitung

# Backup erstellen
docker-compose exec admin-panel python -c "from utils.backup import create_backup; create_backup()"

# Test-Umgebung aufsetzen
docker-compose -f docker-compose.test.yml up -d

2. Schrittweise Aktivierung

1. Auth-Routes migrieren (Login kritisch)
2. Admin-Routes migrieren (Dashboard)
3. API-Routes (externe Abhängigkeiten)
4. Restliche Routes

3. Monitoring

• Fehler-Logs überwachen
• Performance-Metriken vergleichen
• User-Feedback sammeln

Performance-Überlegungen

Aktuelle Messwerte

• App-Start: ~2-3 Sekunden
• Route-Response: <100ms
• Datenbankqueries: Optimiert mit Indizes

Nach Refactoring erwartet

• Schnellerer App-Start durch lazy loading
• Bessere Parallelisierung möglich
• Einfacheres Caching pro Modul

Sicherheits-Verbesserungen

1. Rate-Limiting: Zentral in eigenem Modul
2. Session-Management: Strikte 5-Minuten Timeouts
3. 2FA: Vollständig implementiert mit Backup-Codes
4. Audit-Trail: Lückenlose Protokollierung

Entwickler-Hinweise

Neue Features hinzufügen

1. Modul in entsprechendem Verzeichnis erstellen
2. In passenden Blueprint integrieren
3. Tests schreiben
4. Dokumentation aktualisieren

Debugging

# Logging ist überall verfügbar
import logging
logger = logging.getLogger(__name__)
logger.info("Debug information")

# Audit-Log für wichtige Aktionen
from utils.audit import log_audit
log_audit('ACTION', 'entity_type', entity_id, old_values, new_values)

Datenbank-Zugriff

# Immer Context Manager verwenden
from db import get_db_connection, get_db_cursor

with get_db_connection() as conn:
    with get_db_cursor(conn) as cur:
        cur.execute("SELECT * FROM users WHERE id = %s", (user_id,))
        user = cur.fetchone()

Zeitplan

Q1 2024

• Phase 1: Modularisierung
• Phase 2: Blueprints vollständig
• Phase 3: Model Layer

Q2 2024

• Phase 4: Service Layer
• Phase 5: Testing
• Production Release

Kontakt

Bei Fragen zum Refactoring:

• GitHub Issues: https://github.com/anthropics/claude-code/issues
• Dokumentation: Dieses Dokument

---

Letzte Aktualisierung: 2024-06-16