aktualisiert

Architektur-und-Design.-.md

@@ -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.

Coding-Guidelines.-.md

@@ -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
 /**

Fehlerbehandlung-und-Logging.-.md

@@ -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.

Gitea-Workflow.-.md

@@ -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.
+
 
 ---
 

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]]