From e76bec80ef232d7f141f0b487f441562798b91ca Mon Sep 17 00:00:00 2001 From: blaerf Date: Sat, 29 Nov 2025 13:59:46 +0100 Subject: [PATCH] aktualisiert --- Anforderungen.md => Anforderungen.-.md | 258 ++++++++++++------------- Architektur-und-Design.-.md | 99 ++++++++++ Coding-Guidelines.-.md | 17 +- Fehlerbehandlung-und-Logging.-.md | 97 ++++++++++ Gitea-Workflow.-.md | 8 + Home.md | 6 +- 6 files changed, 348 insertions(+), 137 deletions(-) rename Anforderungen.md => Anforderungen.-.md (97%) create mode 100644 Architektur-und-Design.-.md create mode 100644 Fehlerbehandlung-und-Logging.-.md diff --git a/Anforderungen.md b/Anforderungen.-.md similarity index 97% rename from Anforderungen.md rename to Anforderungen.-.md index d636e5c..6bd51fb 100644 --- a/Anforderungen.md +++ b/Anforderungen.-.md @@ -1,129 +1,129 @@ -# Administrations-Tool für Active Directory und Serververwaltung - -Die IT-Abteilung legt neue Benutzerkonten derzeit manuell im Active Directory an. Dieser Vorgang ist zeitintensiv, fehleranfällig und erschwert eine effiziente Massenverarbeitung. Auch die Serveradministration erfolgt überwiegend reaktiv. Um diese Abläufe zu verbessern, entsteht ein webbasiertes Verwaltungstool, das die Benutzeranlage automatisiert und zentrale Wartungsfunktionen bereitstellt. - -## Projektziel (Muss-Anforderungen) -Ziel ist die Entwicklung eines Administrationstools zur: -- automatisierten Anlage und Bearbeitung von Active-Directory-Benutzern, -- zentralen Ausführung von Serverwartungen. - -Die Umsetzung erfolgt in HTML, CSS und PHP. Die Kommunikation mit dem Active Directory erfolgt über LDAP, während Powershell-Befehle für administrative Operationen genutzt werden. - -## Funktionsumfang - -### Aktueller Implementierungsstand - -| Feature | Status | Kommentar | -|----------------------------------|-------------------|---------------------------------------------| -| LDAP-Login (Administrator) | implementiert | Login gegen AD-Domäne über LDAP/LDAPS | -| Server-Monitoring (SNMP) | in Arbeit / geplant | Basis laut Implementierungshandbuch definiert | -| Einzelne Benutzererstellung | geplant | Schnittstelle über PowerShell vorgesehen | -| CSV-Massenimport | geplant | Anforderungen beschrieben, noch keine UI | -| Logging (Aktionen/Fehler) | geplant | Konzept definiert, technische Umsetzung offen | - - -### Benutzerverwaltung -- Anlage neuer Benutzer über Eingabefelder -- CSV-Import für Massenverarbeitungen -- automatische Übernahme der CSV-Daten in die Eingabefelder -- Validierung der Eingabedaten -- Übertragung der Benutzerinformationen an das AD -- Zuordnung zu Gruppen -- optionale Einstellung von Anmeldezeiten - -### Datenfelder -- Login-Name -- Passwort -- Vorname -- Nachname -- Gruppe -- (optional) Anmeldezeiten - -### Serververwaltung -- Ausführen vordefinierter Powershell-Routinen -- Abrufen von Systemmetriken (CPU, RAM, Dienste, Speicher) -- Dokumentation der Testergebnisse -- Unterstützung präventiver Wartungsprozesse - -## Projektphasen - -### Testumgebung erstellen -- Virtuelle Maschine einrichten -- Windows Server installieren -- Active Directory konfigurieren -- LDAP-Anbindung testen - -### Tests -- Powershell-Befehle prüfen -- CSV-Importvalidierung testen -- AD-Anbindungen dokumentiert verifizieren - -### Entwicklung -- Entwurf der Weboberfläche -- Implementierung der CSV-Importlogik -- Anbindung an LDAP und Powershell -- Integration aller Funktionen - -### Übergabe -- Funktionstests -- Dokumentation -- Präsentation - ---- - -# Erweiterungsmöglichkeiten (Kann-Anforderungen) - -## Ausführliches Logging -Ein integriertes Logging ermöglicht die Nachvollziehbarkeit aller Aktionen: -- angelegte Benutzer -- ausgeführte Powershell-Befehle -- Fehlermeldungen und LDAP-Issues - -## Erweiterte AD-Benutzerdaten -Optional können zusätzliche Attribute gesetzt werden: -- Abteilung -- Telefonnummer -- E-Mail -- Standort - -## Dynamisches Einlesen aus dem AD -Das Tool kann OUs und Gruppen automatisch anzeigen und zur Auswahl bereitstellen. - -## CSV-Validierungscheck -Vor der Verarbeitung sollten geprüft werden: -- Pflichtfelder vorhanden? -- ungültige Zeichen? -- doppelte Einträge? -- existieren Logins bereits im AD? - -## Benutzerübersicht (Read-Only) -Eine AD-Liste mit Such- und Filterfunktion: -- Benutzername -- Name -- Gruppen -- Status - -## Server-Health-Dashboard -Ein Dashboard mit: -- CPU-Last -- RAM-Auslastung -- Dienste-Status -- Festplattenbelegung -- Server-Ping -- kritische Eventlogs - -## Powershell-Wartungsroutinen -- Dienste neustarten -- Eventlogs prüfen -- AD-Replikation testen -- Berechtigungen analysieren -- Netzwerkstatus abfragen - -## Rollen-Vorlagen (für AD-Gruppen) -Automatische Gruppenzuweisung durch auswählbare Rollen, z.B.: -- Azubi -- IT -- Vertrieb - -Diese Funktion erleichtert standardisierte Benutzeranlagen, ohne Rollen im Tool selbst zu verwalten. - +# Administrations-Tool für Active Directory und Serververwaltung + +Die IT-Abteilung legt neue Benutzerkonten derzeit manuell im Active Directory an. Dieser Vorgang ist zeitintensiv, fehleranfällig und erschwert eine effiziente Massenverarbeitung. Auch die Serveradministration erfolgt überwiegend reaktiv. Um diese Abläufe zu verbessern, entsteht ein webbasiertes Verwaltungstool, das die Benutzeranlage automatisiert und zentrale Wartungsfunktionen bereitstellt. + +## Projektziel (Muss-Anforderungen) +Ziel ist die Entwicklung eines Administrationstools zur: +- automatisierten Anlage und Bearbeitung von Active-Directory-Benutzern, +- zentralen Ausführung von Serverwartungen. + +Die Umsetzung erfolgt in HTML, CSS und PHP. Die Kommunikation mit dem Active Directory erfolgt über LDAP, während Powershell-Befehle für administrative Operationen genutzt werden. + +## Funktionsumfang + +### Aktueller Implementierungsstand + +| Feature | Status | Kommentar | +|----------------------------------|-------------------|---------------------------------------------| +| LDAP-Login (Administrator) | implementiert | Login gegen AD-Domäne über LDAP/LDAPS | +| Server-Monitoring (SNMP) | in Arbeit / geplant | Basis laut Implementierungshandbuch definiert | +| Einzelne Benutzererstellung | geplant | Schnittstelle über PowerShell vorgesehen | +| CSV-Massenimport | geplant | Anforderungen beschrieben, noch keine UI | +| Logging (Aktionen/Fehler) | geplant | Konzept definiert, technische Umsetzung offen | + + +### Benutzerverwaltung +- Anlage neuer Benutzer über Eingabefelder +- CSV-Import für Massenverarbeitungen +- automatische Übernahme der CSV-Daten in die Eingabefelder +- Validierung der Eingabedaten +- Übertragung der Benutzerinformationen an das AD +- Zuordnung zu Gruppen +- optionale Einstellung von Anmeldezeiten + +### Datenfelder +- Login-Name +- Passwort +- Vorname +- Nachname +- Gruppe +- (optional) Anmeldezeiten + +### Serververwaltung +- Ausführen vordefinierter Powershell-Routinen +- Abrufen von Systemmetriken (CPU, RAM, Dienste, Speicher) +- Dokumentation der Testergebnisse +- Unterstützung präventiver Wartungsprozesse + +## Projektphasen + +### Testumgebung erstellen +- Virtuelle Maschine einrichten +- Windows Server installieren +- Active Directory konfigurieren +- LDAP-Anbindung testen + +### Tests +- Powershell-Befehle prüfen +- CSV-Importvalidierung testen +- AD-Anbindungen dokumentiert verifizieren + +### Entwicklung +- Entwurf der Weboberfläche +- Implementierung der CSV-Importlogik +- Anbindung an LDAP und Powershell +- Integration aller Funktionen + +### Übergabe +- Funktionstests +- Dokumentation +- Präsentation + +--- + +# Erweiterungsmöglichkeiten (Kann-Anforderungen) + +## Ausführliches Logging +Ein integriertes Logging ermöglicht die Nachvollziehbarkeit aller Aktionen: +- angelegte Benutzer +- ausgeführte Powershell-Befehle +- Fehlermeldungen und LDAP-Issues + +## Erweiterte AD-Benutzerdaten +Optional können zusätzliche Attribute gesetzt werden: +- Abteilung +- Telefonnummer +- E-Mail +- Standort + +## Dynamisches Einlesen aus dem AD +Das Tool kann OUs und Gruppen automatisch anzeigen und zur Auswahl bereitstellen. + +## CSV-Validierungscheck +Vor der Verarbeitung sollten geprüft werden: +- Pflichtfelder vorhanden? +- ungültige Zeichen? +- doppelte Einträge? +- existieren Logins bereits im AD? + +## Benutzerübersicht (Read-Only) +Eine AD-Liste mit Such- und Filterfunktion: +- Benutzername +- Name +- Gruppen +- Status + +## Server-Health-Dashboard +Ein Dashboard mit: +- CPU-Last +- RAM-Auslastung +- Dienste-Status +- Festplattenbelegung +- Server-Ping +- kritische Eventlogs + +## Powershell-Wartungsroutinen +- Dienste neustarten +- Eventlogs prüfen +- AD-Replikation testen +- Berechtigungen analysieren +- Netzwerkstatus abfragen + +## Rollen-Vorlagen (für AD-Gruppen) +Automatische Gruppenzuweisung durch auswählbare Rollen, z.B.: +- Azubi +- IT +- Vertrieb + +Diese Funktion erleichtert standardisierte Benutzeranlagen, ohne Rollen im Tool selbst zu verwalten. + diff --git a/Architektur-und-Design.-.md b/Architektur-und-Design.-.md new file mode 100644 index 0000000..1309867 --- /dev/null +++ b/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. diff --git a/Coding-Guidelines.-.md b/Coding-Guidelines.-.md index 26b375e..522830d 100644 --- a/Coding-Guidelines.-.md +++ b/Coding-Guidelines.-.md @@ -44,13 +44,17 @@ Beispiel: ```php 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. \ No newline at end of file diff --git a/Gitea-Workflow.-.md b/Gitea-Workflow.-.md index 5a4b2ca..a9dad0a 100644 --- a/Gitea-Workflow.-.md +++ b/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. + --- diff --git a/Home.md b/Home.md index 7bfd950..f9abf58 100644 --- a/Home.md +++ b/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]]