# 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