aktualisiert
parent
d7a5f9dc41
commit
e76bec80ef
99
Architektur-und-Design.-.md
Normal file
99
Architektur-und-Design.-.md
Normal file
@ -0,0 +1,99 @@
|
||||
# Architektur und Design
|
||||
|
||||
## Ziel dieses Dokuments
|
||||
|
||||
Dieses Dokument beschreibt die interne Architektur der Webanwendung *PHP Admin Tool*.
|
||||
Es soll Entwickler einen schnellen Überblick geben, wie die einzelnen Komponenten zusammenspielen und wo neue Funktionalität ergänzt werden kann.
|
||||
|
||||
---
|
||||
|
||||
## Übersicht
|
||||
|
||||
Die Anwendung folgt einem mehrschichtigen Aufbau:
|
||||
|
||||
- **Front-Controller** (`public/index.php`)
|
||||
- **Controller-Schicht** (`app/Controllers`)
|
||||
- **Service-Schicht** (`app/Services/...`)
|
||||
- **View-Schicht** (`public/views/...`)
|
||||
- **Infrastruktur** (IIS, PHP, PowerShell, AD, SNMP) – ausführlich im Implementierungshandbuch beschrieben
|
||||
|
||||
---
|
||||
|
||||
## Request-Flow
|
||||
|
||||
1. Eine HTTP-Anfrage trifft auf `public/index.php`.
|
||||
2. Der Front-Controller:
|
||||
- initialisiert den Autoloader,
|
||||
- lädt die Konfiguration aus `config/config.php`,
|
||||
- startet die Session (für Login-Zustand),
|
||||
- instanziiert die Controller.
|
||||
3. Über den GET-Parameter `route` wird entschieden, welcher Controller und welche Methode ausgeführt wird (z. B. `login`, `dashboard`, `users`).
|
||||
4. Der Controller ruft bei Bedarf Services auf (z. B. LDAP-Service, SNMP-Service) und erstellt ein View-Result-Array.
|
||||
5. Das View-Result-Array wird an das zentrale Layout (`public/views/layout.php`) übergeben.
|
||||
6. Das Layout bindet die entsprechenden View-Templates ein (z. B. `login.php`, `dashboard.php`, `users.php`) und rendert HTML.
|
||||
|
||||
---
|
||||
|
||||
## Controller-Schicht
|
||||
|
||||
- Liegt im Namespace `App\Controllers`.
|
||||
- Jeder Controller ist für einen logisch abgegrenzten Bereich zuständig:
|
||||
|
||||
- `AuthController`: Login, Logout, Session-Verwaltung
|
||||
- `DashboardController`: Anzeige von Serverstatus und Monitoring-Daten
|
||||
- `UserManagementController`: Anzeige von Benutzern und Gruppen (LDAP-Abfragen)
|
||||
|
||||
- Controller geben kein HTML aus, sondern liefern strukturierte Arrays an die View-Schicht.
|
||||
|
||||
---
|
||||
|
||||
## Service-Schicht
|
||||
|
||||
- Liegt im Namespace `App\Services\...`.
|
||||
- Kapselt technische Details und externe Systeme:
|
||||
|
||||
- `App\Services\Ldap\LdapConnectionHelper`: Aufbau der LDAP-Verbindung (ohne Bind).
|
||||
- `App\Services\Ldap\LdapDirectoryService`: Suchen von Benutzern und Gruppen im AD.
|
||||
- `App\Services\Snmp\SnmpServerStatusService`: Auslesen von Serverkennzahlen per SNMP.
|
||||
- `App\Services\Powershell\...` (geplant): Ausführung von PowerShell-Skripten.
|
||||
|
||||
- Controller sprechen nur über diese Services mit LDAP, SNMP und PowerShell – direkte Zugriffe aus Views sind nicht erlaubt.
|
||||
|
||||
---
|
||||
|
||||
## View-Schicht
|
||||
|
||||
- Liegt unter `public/views/`:
|
||||
- `layout.php` enthält die zentrale Funktion `renderLayout()`.
|
||||
- Unter `public/views/partials/` liegen `head.php`, `sidebar.php`, `topbar.php`, `footer.php`, `scripts.php`.
|
||||
- Inhaltliche Seiten wie `login.php`, `dashboard.php`, `users.php` stellen nur den jeweiligen Content innerhalb des Layouts dar.
|
||||
|
||||
- Die Views bekommen vom Controller vordefinierte Variablen (z. B. `$serverStatus`, `$users`, `$groups`) und sind für:
|
||||
|
||||
- Ausgabeformatierung
|
||||
- Tabellen, Formulare, UI-Elemente (auf Basis SB Admin 2)
|
||||
|
||||
zuständig.
|
||||
|
||||
---
|
||||
|
||||
## Sicherheitsaspekte (kurz)
|
||||
|
||||
- Zugang zur Anwendung nur für AD-Administrator (Login über LDAP/LDAPS).
|
||||
- Nach erfolgreichem Login wird der Benutzerstatus in der Session gespeichert.
|
||||
- Geschützte Routen prüfen den Login-Zustand, bevor Inhalte geladen werden.
|
||||
- Technische Fehlerdetails (z. B. LDAP-Fehler, SNMP-Fehler) werden nicht direkt im Browser angezeigt, sondern sollen über das Logging (siehe Seite „Fehlerbehandlung und Logging“) behandelt werden.
|
||||
|
||||
---
|
||||
|
||||
## Erweiterbarkeit
|
||||
|
||||
Neue Funktionen werden nach folgendem Muster ergänzt:
|
||||
|
||||
1. Neue Route im Front-Controller definieren.
|
||||
2. Neue Methode im zuständigen Controller anlegen.
|
||||
3. Gegebenenfalls neue Service-Klasse anlegen oder bestehende erweitern.
|
||||
4. Neues View-Template unter `public/views/` anlegen.
|
||||
5. Falls nötig, Menüeintrag in der Sidebar hinzufügen.
|
||||
|
||||
Dieses Muster stellt sicher, dass die Architektur konsistent bleibt und Verantwortlichkeiten klar getrennt sind.
|
||||
@ -44,13 +44,17 @@ Beispiel:
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace App\Services\Ldap;
|
||||
|
||||
class LdapDirectoryService
|
||||
{
|
||||
// ...
|
||||
// LDAP-Operationen (Benutzersuche, Gruppensuche, etc.)
|
||||
}
|
||||
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
@ -195,10 +199,6 @@ throw new UserNotFoundException("User not found");
|
||||
## 11. Kommentare & PHPDoc
|
||||
|
||||
- Kommentare erklären *warum*, nicht *was*.
|
||||
- Jeder `public` Service und jeder `public` Controller-Endpunkt bekommt einen PHPDoc-Block.
|
||||
- `@param` und `@return` werden konsequent gesetzt, auch bei skalarer Typisierung (für phpDocumentor).
|
||||
- Bei Methoden, die AD ändern (Benutzer anlegen, Gruppen zuweisen, Skripte triggern): kurzer Hinweis auf Seiteneffekte.
|
||||
|
||||
|
||||
Schlecht:
|
||||
|
||||
@ -208,6 +208,13 @@ $i = $i + 1;
|
||||
```
|
||||
|
||||
### PHPDoc
|
||||
- Jeder `public` Controller und jeder `public` Service bekommt einen PHPDoc-Klassenkommentar.
|
||||
- Öffentliche Methoden erhalten immer einen PHPDoc-Block mit:
|
||||
- kurzer Beschreibung (1–3 Sätze),
|
||||
- `@param` für alle Parameter,
|
||||
- `@return` für den Rückgabewert.
|
||||
- Methoden, die AD-Objekte verändern oder Skripte anstoßen, müssen einen Hinweis auf Seiteneffekte enthalten (z. B. „legt AD-Benutzer an“, „führt PowerShell-Skript aus“).
|
||||
|
||||
|
||||
```php
|
||||
/**
|
||||
|
||||
97
Fehlerbehandlung-und-Logging.-.md
Normal file
97
Fehlerbehandlung-und-Logging.-.md
Normal file
@ -0,0 +1,97 @@
|
||||
# Fehlerbehandlung und Logging
|
||||
|
||||
## Ziel dieses Dokuments
|
||||
|
||||
Dieses Dokument beschreibt, wie Fehler in der Anwendung erkannt, behandelt und protokolliert werden sollen.
|
||||
Es dient als Richtlinie für alle Entwickler, damit Fehlersituationen einheitlich behandelt werden.
|
||||
|
||||
---
|
||||
|
||||
## Grundprinzipien
|
||||
|
||||
- **Benutzerfreundlich im Frontend**
|
||||
- Benutzer sehen nur verständliche, neutrale Fehlermeldungen.
|
||||
- Interne Details (z. B. LDAP-Verbindungsstring, SNMP-Community-Strings, PowerShell-Pfade) werden **niemals** im Browser angezeigt.
|
||||
|
||||
- **Detailreich im Log**
|
||||
- Technische Details werden in Logdateien geschrieben (z. B. Exception-Message, Stacktrace, Kontextinformationen).
|
||||
- Logs dienen zur Analyse von Problemen in Entwicklung, Test und Produktion.
|
||||
|
||||
- **Sicherheit geht vor**
|
||||
- Keine Passwörter oder Zugangsdaten im Klartext im Log.
|
||||
- Sensible Felder (z. B. Benutzerpasswörter) werden maskiert oder gar nicht geloggt.
|
||||
|
||||
---
|
||||
|
||||
## Fehlerarten
|
||||
|
||||
- **Technische Fehler**
|
||||
- LDAP-Verbindungsfehler
|
||||
- SNMP-Timeouts oder ungültige OIDs
|
||||
- Fehler bei der Ausführung von PowerShell-Skripten
|
||||
- interne PHP-Exceptions (z. B. ungültige Konfiguration)
|
||||
|
||||
- **Anwendungsfehler**
|
||||
- Ungültige Eingaben im Formular (Login, CSV-Daten, etc.)
|
||||
- fehlende Pflichtfelder
|
||||
- ungültige Dateiformate
|
||||
|
||||
- **Authentifizierungs-/Autorisierungsfehler**
|
||||
- falsche Anmeldedaten
|
||||
- Benutzer nicht berechtigt, bestimmte Funktion auszuführen
|
||||
|
||||
---
|
||||
|
||||
## Behandlungsstrategie
|
||||
|
||||
### 1. Fehler im Controller
|
||||
|
||||
- Controller fangen Exceptions aus Services ab.
|
||||
- Für den Benutzer wird eine passende, generische Meldung vorbereitet (z. B. „Die Anmeldung ist fehlgeschlagen.“).
|
||||
- Technische Details werden an die Logging-Schicht übergeben.
|
||||
|
||||
### 2. Fehler in Services
|
||||
|
||||
- Services dürfen Exceptions werfen, wenn:
|
||||
- ein nicht behebbarer Fehler auftritt (z. B. Konfiguration fehlt),
|
||||
- externe Systeme nicht erreichbar sind.
|
||||
- Services loggen keine direkten Benutzerinformationen, sondern nur Kontextdaten (z. B. `username` ohne Passwort).
|
||||
|
||||
---
|
||||
|
||||
## Logging-Konzept (Basis)
|
||||
|
||||
> Hinweis: Die konkrete technische Umsetzung (Pfad, Log-Rotation, Logging-Library) kann projektspezifisch angepasst werden.
|
||||
|
||||
- **Logziel**
|
||||
- Logdateien im Server-Dateisystem (z. B. `C:\inetpub\logs\php_admin_tool\app.log`).
|
||||
- Zugriff nur für Administrator.
|
||||
|
||||
- **Mindestinformationen pro Logeintrag**
|
||||
- Zeitstempel
|
||||
- Log-Level (INFO, WARNING, ERROR)
|
||||
- Komponente (z. B. `LdapDirectoryService`, `SnmpServerStatusService`)
|
||||
- Nachricht
|
||||
- Kontextdaten (sofern verfügbar, z. B. `route`, `username`, `server`)
|
||||
|
||||
- **Beispiel für Log-Eintrag (Semantik)**
|
||||
|
||||
```text
|
||||
[2025-11-29 10:15:23] ERROR LdapDirectoryService: Bind to LDAP server failed (server=ad.example.local, port=636, error=Invalid credentials)
|
||||
|
||||
---
|
||||
|
||||
## Umgang mit kritischen Fehlern
|
||||
|
||||
- Bei kritischen Fehlern (z. B. keine Verbindung zum AD, SNMP nicht erreichbar):
|
||||
- Benutzer sehen eine neutrale Fehlermeldung.
|
||||
- Es wird ein Eintrag mit Level ERROR oder CRITICAL geschrieben.
|
||||
- Falls sinnvoll, wird eine Fallback-Seite (z. B. „Wartungsmodus“) angezeigt.
|
||||
|
||||
---
|
||||
|
||||
## ToDos
|
||||
|
||||
- Auswahl und Integration einer Logging-Lösung (z. B. eigene Klasse oder Monolog).
|
||||
- Festlegen des Logverzeichnisses und der Berechtigungen.
|
||||
- Definition von einheitlichen Log-Formaten für LDAP, SNMP und PowerShell.
|
||||
@ -13,10 +13,18 @@ Der `develop`-Branch stellt den aktuellen Teststand bereit und ist erreichbar un
|
||||
- Test (`develop`): https://test.itfa.schraubenfuzzi.de
|
||||
|
||||
**Kurzüberblick:**
|
||||
## Kurzüberblick
|
||||
|
||||
- Entwicklung erfolgt in Feature-Branches (`feature/...`) auf Basis von `develop`.
|
||||
- Feature-Branches werden per Pull Request nach `develop` gemergt und auf dem Testsystem bereitgestellt.
|
||||
- Nach erfolgreichem Test wird ein Pull Request von `develop` nach `main` erstellt.
|
||||
- Änderungen in `main` werden auf das Produktivsystem ausgerollt.
|
||||
|
||||
feature/* → Pull Request nach `develop` → Testsystem
|
||||
erfolgreich getestet → Pull Request nach `main` → Review → Produktion
|
||||
|
||||
Die genauen Schritte und Konventionen (Branch-Namen, Reviews, Umgang mit Fehlern) sind im weiteren Verlauf dieser Seite beschrieben.
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
6
Home.md
6
Home.md
@ -30,7 +30,7 @@ Dieses Wiki ist die zentrale Arbeitsgrundlage für das gesamte Team:
|
||||
Wenn du neu im Projekt bist, lies die Seiten am besten in dieser Reihenfolge:
|
||||
|
||||
1. [[Projektübersicht]]
|
||||
2. [Anforderungen-und-Ziele](Anforderungen)
|
||||
2. [Anforderungen-und-Ziele](Anforderungen.-)
|
||||
3. [[Entwicklungsumgebung-einrichten]]
|
||||
4. [Windows Server Setup](Implementierungshandbuch-IIS-PHP-AD.-)
|
||||
5. [Projektstruktur und Best Practices](Projektstruktur-und-Best-Practices.-)
|
||||
@ -48,10 +48,10 @@ Wenn du neu im Projekt bist, lies die Seiten am besten in dieser Reihenfolge:
|
||||
- [[Meilensteine-und-Zeitplan]]
|
||||
|
||||
- **Entwicklung**
|
||||
- [[Architektur-und-Design]]
|
||||
- [Architektur-und-Design](Architektur-und-Design.-)
|
||||
- [[Datenbankmodell]]
|
||||
- [[API-Spezifikation]]
|
||||
- [[Fehlerbehandlung-und-Logging]]
|
||||
- [Fehlerbehandlung-und-Logging](Fehlerbehandlung-und-Logging.-)
|
||||
|
||||
- **Qualität & Prozesse**
|
||||
- [[Coding-Guidelines-PHP]]
|
||||
|
||||
Loading…
Reference in New Issue
Block a user