373 lines
10 KiB
Markdown
373 lines
10 KiB
Markdown
# 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 |