feat: Initial commit of KeyHelp Manager module

2025-10-15 22:29:11 +02:00
parent 4df2eddc6a
commit 351da5fe19
8 changed files with 2584 additions and 0 deletions
--- a/PROJECT_STRUCTURE.md
+++ b/PROJECT_STRUCTURE.md
@@ -0,0 +1,373 @@
+# KeyHelp Manager - Projektstruktur
+
+**Entwickelt von:** Kevin Feiler / AVVGO  
+**Version:** 1.0.0
+
+## 📁 Verzeichnisstruktur
+
+```
+keyweb-module/
+├── modules/
+│   └── servers/
+│       └── keyhelpmanager/
+│           ├── keyhelpmanager.php          # Haupt-Modul-Datei (846 Zeilen)
+│           └── templates/
+│               └── clientarea.tpl          # Client Area Smarty-Template
+│
+├── .gitignore                              # Git Ignore-Datei
+├── CHANGELOG.md                            # Versions-Historie
+├── composer.json                           # Composer Dependencies
+├── INSTALLATION.md                         # Detaillierte Installationsanleitung
+├── LICENSE                                 # MIT Lizenz
+├── PROJECT_STRUCTURE.md                    # Diese Datei
+└── README.md                               # Haupt-Dokumentation
+```
+
+## 📄 Datei-Übersicht
+
+### Hauptmodul: `keyhelpmanager.php`
+
+**Größe:** ~846 Zeilen  
+**Zweck:** Kernfunktionalität des WHMCS Provisioning Moduls
+
+#### Öffentliche WHMCS-Funktionen:
+
+1. **`keyhelpmanager_MetaData()`**
+   - Gibt Modul-Metadaten zurück
+   - DisplayName, API-Version, Port-Definitionen
+
+2. **`keyhelpmanager_ConfigOptions()`**
+   - Definiert Server-Konfigurationsoptionen
+   - Hostname, API-Key, SSL-Einstellungen
+
+3. **`keyhelpmanager_CreateAccount(array $params)`**
+   - Erstellt neuen KeyHelp-Account
+   - Generiert Username/Passwort falls nötig
+   - Fügt Domain hinzu
+   - Speichert Details in WHMCS
+
+4. **`keyhelpmanager_SuspendAccount(array $params)`**
+   - Sperrt KeyHelp-Account
+   - Setzt `is_locked` Flag
+
+5. **`keyhelpmanager_UnsuspendAccount(array $params)`**
+   - Entsperrt KeyHelp-Account
+   - Entfernt `is_locked` Flag
+
+6. **`keyhelpmanager_TerminateAccount(array $params)`**
+   - Löscht KeyHelp-Account permanent
+   - Entfernt alle zugehörigen Daten
+   - Cleanup in WHMCS-Datenbank
+
+7. **`keyhelpmanager_ChangePassword(array $params)`**
+   - Ändert Account-Passwort
+   - Synchronisiert mit WHMCS
+
+8. **`keyhelpmanager_ClientArea(array $params)`**
+   - Generiert Client Area Inhalt
+   - Lädt Live-Statistiken von KeyHelp
+   - Rendert Smarty-Template
+
+9. **`keyhelpmanager_LoginLink(array $params)`**
+   - Single Sign-On für Admins
+   - Erstellt Session-Token
+   - Generiert direkten Login-Link
+
+10. **`keyhelpmanager_TestConnection(array $params)`**
+    - Testet API-Verbindung
+    - Gibt KeyHelp-Version zurück
+
+#### Private Hilfsfunktionen:
+
+**API-Kommunikation:**
+- `_keyhelpmanager_APIRequest()` - Zentrale API-Request-Funktion mit Guzzle
+
+**Account-Management:**
+- `_keyhelpmanager_GenerateUsername()` - Generiert Username aus Domain
+- `_keyhelpmanager_GeneratePassword()` - Generiert sicheres Passwort (16 Zeichen)
+- `_keyhelpmanager_SaveAccountDetails()` - Speichert in WHMCS-DB
+- `_keyhelpmanager_GetAccountDetails()` - Lädt aus WHMCS-DB
+- `_keyhelpmanager_GetUserId()` - Holt KeyHelp User-ID
+- `_keyhelpmanager_UpdateAccountDetail()` - Aktualisiert einzelnes Detail
+- `_keyhelpmanager_DeleteAccountDetails()` - Löscht gespeicherte Details
+
+**Custom Fields:**
+- `_keyhelpmanager_GetCustomFieldId()` - Holt/erstellt Custom Field ID
+
+**Formatierung:**
+- `_keyhelpmanager_FormatBytes()` - Formatiert Bytes → KB/MB/GB/TB
+- `_keyhelpmanager_CalculatePercent()` - Berechnet Prozentsatz
+
+### Template: `clientarea.tpl`
+
+**Größe:** ~258 Zeilen  
+**Typ:** Smarty Template  
+**Zweck:** Client Area Darstellung
+
+#### Features:
+- Bootstrap 3/4 kompatibles Layout
+- FontAwesome Icons
+- Responsive Design
+- JavaScript-Funktionen:
+  - `togglePassword()` - Passwort anzeigen/verbergen
+  - `copyToClipboard()` - Text in Zwischenablage kopieren
+
+#### Angezeigte Informationen:
+1. **Login-Informationen:**
+   - KeyHelp Login-URL (klickbar)
+   - Benutzername (mit Copy-Button)
+   - Passwort (mit Show/Hide und Copy-Button)
+   - Domain-Name
+
+2. **Account-Statistiken:**
+   - Speicherplatz (Fortschrittsbalken)
+   - Traffic/Bandbreite (Fortschrittsbalken)
+   - Anzahl Domains
+   - Anzahl Datenbanken
+   - Anzahl E-Mail-Konten
+
+3. **Call-to-Action:**
+   - "Jetzt zu KeyHelp einloggen" Button
+
+## 🔌 KeyHelp API-Endpunkte
+
+Das Modul nutzt folgende KeyHelp API v2 Endpunkte:
+
+| Endpunkt | Methode | Zweck | Verwendet in |
+|----------|---------|-------|--------------|
+| `/api/v2/users` | POST | Benutzer erstellen | CreateAccount |
+| `/api/v2/users/{id}` | GET | Benutzer-Details | GetAccountDetails |
+| `/api/v2/users/{id}` | PUT | Benutzer aktualisieren | SuspendAccount, UnsuspendAccount, ChangePassword |
+| `/api/v2/users/{id}` | DELETE | Benutzer löschen | TerminateAccount |
+| `/api/v2/domains` | POST | Domain hinzufügen | CreateAccount |
+| `/api/v2/users/{id}/statistics` | GET | Statistiken abrufen | ClientArea |
+| `/api/v2/sessions` | POST | SSO-Session erstellen | LoginLink |
+| `/api/v2/server/version` | GET | Server-Version | TestConnection |
+
+## 💾 WHMCS-Datenbank-Interaktionen
+
+### Verwendete Tabellen:
+
+1. **`tblhosting`**
+   - Felder: `username`, `password`
+   - Zweck: Speichert Account-Credentials
+
+2. **`tblcustomfields`**
+   - Erstellt Custom Field: "KeyHelp User ID"
+   - Typ: Text (Admin Only)
+
+3. **`tblcustomfieldsvalues`**
+   - Speichert KeyHelp User-ID pro Service
+   - Verknüpfung über `relid` (Service-ID)
+
+### Verwendetes ORM:
+- **Laravel Eloquent Capsule** (von WHMCS bereitgestellt)
+- Sichere Queries ohne SQL-Injection-Risiko
+
+## 🔒 Sicherheitsfeatures
+
+1. **API-Key-Schutz:**
+   - Verschlüsselte Speicherung in WHMCS
+   - Maskierung in Module-Logs
+   - Niemals im Frontend sichtbar
+
+2. **Passwort-Sicherheit:**
+   - Kryptografisch sichere Generierung (`random_int()`)
+   - 16 Zeichen Länge
+   - Gemischte Zeichensätze (a-z, A-Z, 0-9, Sonderzeichen)
+   - Verschlüsselte Speicherung in WHMCS
+
+3. **SSL/TLS:**
+   - Konfigurierbare SSL-Verbindungen
+   - Optionale Zertifikat-Verifizierung
+   - Standard: SSL aktiviert
+
+4. **Input-Validierung:**
+   - Alle Benutzereingaben werden validiert
+   - Sanitization durch Capsule ORM
+   - Exception-Handling für alle API-Calls
+
+5. **Session-Token:**
+   - Temporäre SSO-Tokens (5 Minuten Gültigkeit)
+   - Automatischer Ablauf
+
+## 📝 Logging
+
+### WHMCS Module Log:
+- Alle API-Requests werden protokolliert
+- Automatische Maskierung sensibler Daten
+- Abrufbar unter: `Utilities → Logs → Module Log`
+
+### Logged werden:
+- API-Endpunkt und Methode
+- Request-Body (API-Key maskiert)
+- Response-Status und Body
+- Fehler und Exceptions
+
+## 🎨 Design-Patterns
+
+1. **Prefix-Convention:**
+   - Öffentliche Funktionen: `keyhelpmanager_FunctionName()`
+   - Private Funktionen: `_keyhelpmanager_FunctionName()`
+
+2. **Error-Handling:**
+   - Try-Catch-Blöcke um alle kritischen Operationen
+   - Verständliche Fehlermeldungen für Endbenutzer
+   - Detailliertes Logging für Admins
+
+3. **Rollback-Mechanismus:**
+   - Bei fehlgeschlagener Domain-Erstellung: Benutzer wird gelöscht
+   - Verhindert inkonsistente Zustände
+
+4. **Separation of Concerns:**
+   - API-Logik in `_keyhelpmanager_APIRequest()`
+   - Datenbank-Logik in separaten Funktionen
+   - Template-Logik in `.tpl`-Datei
+
+## 🔄 Workflow-Diagramme
+
+### Account-Erstellung:
+
+```
+WHMCS Payment Cleared
+        ↓
+keyhelpmanager_CreateAccount()
+        ↓
+Validiere Parameter
+        ↓
+Generiere Username/Passwort (falls nötig)
+        ↓
+API: POST /users (Benutzer erstellen)
+        ↓
+    Erfolg?
+    ↙     ↘
+  Ja       Nein → Return Error
+    ↓
+API: POST /domains (Domain hinzufügen)
+        ↓
+    Erfolg?
+    ↙     ↘
+  Ja       Nein → Rollback: DELETE User → Return Error
+    ↓
+Speichere Details in WHMCS
+        ↓
+Return "success"
+        ↓
+Account ist aktiv
+```
+
+### Single Sign-On:
+
+```
+Admin klickt "Login to KeyHelp"
+        ↓
+keyhelpmanager_LoginLink()
+        ↓
+Lade User-ID aus WHMCS
+        ↓
+API: POST /sessions (mit User-ID)
+        ↓
+Erhalte Session-Token
+        ↓
+Generiere Login-URL mit Token
+        ↓
+Redirect zu KeyHelp
+        ↓
+Auto-Login ohne Passwort
+```
+
+## 📦 Abhängigkeiten
+
+### PHP-Extensions:
+- `ext-json` - JSON-Verarbeitung
+- `ext-curl` - HTTP-Requests
+
+### Composer-Pakete:
+- `guzzlehttp/guzzle` ^7.0 - HTTP-Client (von WHMCS bereitgestellt)
+
+### WHMCS-Komponenten:
+- Laravel Eloquent Capsule (ORM)
+- Smarty Template Engine
+- Module Log System
+- Custom Fields System
+- Encryption Functions
+
+## 🧪 Testing-Empfehlungen
+
+### Manuelle Tests:
+
+1. **Connection-Test:**
+   - Server-Konfiguration → Test Connection
+
+2. **Account-Lifecycle:**
+   - Create → Verify in KeyHelp
+   - Suspend → Verify locked
+   - Unsuspend → Verify unlocked
+   - Terminate → Verify deleted
+
+3. **Client Area:**
+   - Login-Credentials sichtbar?
+   - Statistiken werden geladen?
+   - Copy-to-Clipboard funktioniert?
+   - Responsive Design auf Mobile?
+
+4. **Admin SSO:**
+   - Login-Link funktioniert?
+   - Automatischer Login ohne Passwort?
+   - Token läuft nach 5 Min. ab?
+
+### Automatisierte Tests (Geplant):
+
+- PHPUnit-Tests für alle Funktionen
+- Mock-API-Responses
+- Database-Transaktionen für Tests
+
+## 📊 Code-Statistiken
+
+- **Gesamt-Zeilen:** ~1.400+
+- **PHP-Code:** ~846 Zeilen
+- **Smarty-Template:** ~258 Zeilen
+- **Dokumentation:** ~1.200+ Zeilen (README, INSTALLATION, etc.)
+- **Funktionen:** 21 (10 öffentlich, 11 privat)
+- **API-Endpunkte:** 8
+
+## 🚀 Performance-Optimierungen
+
+1. **Caching:**
+   - Custom Field IDs werden bei erster Abfrage ermittelt
+   - Wiederverwendung innerhalb einer Request
+
+2. **Lazy-Loading:**
+   - Statistiken nur bei Bedarf (Client Area)
+   - Session-Tokens nur bei SSO
+
+3. **Effiziente DB-Queries:**
+   - Verwendung von Eloquent ORM
+   - Keine N+1 Query-Probleme
+
+4. **API-Timeouts:**
+   - 30 Sekunden Timeout für API-Requests
+   - Verhindert hängende Requests
+
+## 🔮 Geplante Erweiterungen (Roadmap)
+
+Siehe CHANGELOG.md → [Unreleased]
+
+- Multi-Language Support
+- E-Mail-Account-Verwaltung
+- Datenbank-Management
+- SSL-Zertifikat-Management
+- Ressourcen-Upgrade/Downgrade
+- Webhook-Support
+
+## 📞 Support
+
+**Entwickler:** Kevin Feiler  
+**Firma:** AVVGO  
+**Website:** https://avvgo.de  
+**E-Mail:** info@avvgo.de
+
+---
+
+**Copyright (c) 2024 Kevin Feiler / AVVGO**  
+**Lizenz:** MIT License