Rollback
Dieser Commit ist enthalten in:
261
refactoring.md
Normale Datei
261
refactoring.md
Normale Datei
@@ -0,0 +1,261 @@
|
||||
# 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)
|
||||
```python
|
||||
# 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
|
||||
```python
|
||||
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
|
||||
```bash
|
||||
# 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
|
||||
```python
|
||||
# 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
|
||||
```python
|
||||
# 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
|
||||
- [x] 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
|
||||
In neuem Issue referenzieren
Einen Benutzer sperren