KeyHelp-Manager-for-WHMCS/PROJECT_STRUCTURE.md

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