PHP_AdminTool_Projekt/README.md

# PHP_AdminTool_Projekt

Dieses Repository enthält das gemeinsame PHP AdminTool, das auf IIS unter Windows betrieben wird und über LDAP/AD, SNMP und PowerShell administrative Aufgaben ermöglicht. Das Projekt wird von mehreren Entwicklern gepflegt und folgt einem klar definierten Workflow, um Qualität, Stabilität und Nachvollziehbarkeit sicherzustellen.

Ein zentraler Bestandteil der Arbeit mit diesem Repository ist der verbindliche Gitea-Workflow im Wiki.


**Hinweis:** Der [Gitea-Workflow](https://git.eckertplayground.de/taarly/PHP_AdminTool_Projekt/wiki) ist zwingend zu lesen und einzuhalten. Er legt fest, wie Branches erstellt, gemerged und getestet werden.

---

## Überblick

Das Projekt dient als webbasiertes Administrationswerkzeug und umfasst unter anderem:

- LDAP/AD‑Anbindung (LDAPS)
- Benutzer- und Gruppenverwaltung
- SNMP‑Auswertungen
- PowerShell‑Integration
- Weboberfläche zur zentralen Administration

Die Anwendung läuft in zwei Umgebungen:

- Produktion (`main`): https://itfa.schraubenfuzzi.de
- Test (`develop`): https://test.itfa.schraubenfuzzi.de  

---

## Ordnerstruktur (Auszug)

- `app/` – Anwendungscode
- `public/` – Webroot
- `config/` – Konfigurationen für LDAP, Systemvariablen usw.
- `scripts/` – Hilfs- und Bereitstellungsskripte
- `docs/` – interne Dokumente
- `.gitignore` – ausgeschlossene Dateien

---

## Workflow

Die Entwicklung folgt einem strengen, verbindlichen Ablauf:

1. **Feature‑Branch erstellen** (`feature/name`)
2. Feature entwickeln, committen, pushen
3. **PR nach `develop`** für Tests auf der Testinstanz
    - wird vom Autor selbst gemerged
    - Branch bleibt bestehen
4. Nach bestandenem Test: **PR nach `main`**
    - mit Review
    - Merge per Squash
    - danach wird der Feature‑Branch gelöscht

Details stehen im Wiki.

**Wichtiger Hinweis:**  
Der komplette Ablauf ist im [Gitea-Workflow](https://git.eckertplayground.de/taarly/PHP_AdminTool_Projekt/wiki) beschrieben und muss befolgt werden.

---

## Aufgaben

| Aufgabe | Benutzer |
| :---- | :---- |
| Benutzer und Gruppen über LDAP anzeigen | Jens E (@blaerf), Stefan W (@viperion) |
| SNMP Serverstatus abfragen / anzeigen |Thomas G (@tg95) |
| PHP-Powershell Anbindung | Marco Z (@Taarly) |
| Powershell Script für einzelne Benutzer und CSV Import | Matthias K |
| UI/UX anpassen | Yasin B (@Muchentuchen), Alexander M (@Alexander) |
| Blackbox Testing | Torsten J (@tojacobs) |

**Hinweis:** Die Passwortanforderungen (Mindestlänge, Kategorien, keine Teile des Benutzernamens) werden beim Erstellen validiert. Die Validierung ist in `scripts/powershell/create_users_csv.ps1` implementiert und die Mockup-UI (`docs/Mockup/index.html`) zeigt die Anforderungen und prüft sie clientseitig.

---

## Dokumentation

Alle weiteren Informationen wie Regeln, technische Details, Konzepte und Anleitungen befinden sich im Wiki:

`Wiki → Gitea‑Workflow`  
`Wiki → Implementierung / LDAP / IIS / Setup`

Dieser Bereich muss von allen Entwicklern gelesen werden, bevor am Projekt gearbeitet wird.

---

## PowerShell Integration (Benutzererstellung)

Die Weboberfläche nutzt PowerShell-Skripte, um Active Directory Benutzer anzulegen. Damit dies funktioniert, sind folgende Voraussetzungen erforderlich:

- Der Webserver läuft auf Windows und PHP kann PowerShell ausführen (`powershell` oder `pwsh`).
- Die PowerShell-Module `ActiveDirectory` müssen installiert (RSAT) und verfügbar sein.
- Der Benutzer, unter dem der Webserver läuft, muss ausreichende Rechte besitzen, um `New-ADUser` und `Add-ADGroupMember` auszuführen.
- Im `config/config.php` kann `powershell.dry_run` auf `true` gesetzt werden, um Tests ohne Änderungen durchzuführen.

Konfigurationsoptionen (in `config/config.php`):
- `powershell.exe`: Name oder Pfad zur PowerShell-Executable (standard `powershell`).
- `powershell.script_dir`: Pfad zu den PowerShell-Skripten (standard `scripts/powershell`).
- `powershell.execution_policy`: Auszuführende ExecutionPolicy (z. B. `Bypass`).
- `powershell.dry_run`: Wenn `true`, werden keine echten AD-Änderungen durchgeführt; das Skript meldet nur, was es tun würde.

Die grundlegende Funktionalität wurde mit folgenden Komponenten implementiert:
- `public/api/create_user.php`: API-Endpoint zur Erstellung eines einzelnen Benutzers.
- `public/api/create_users_csv.php`: API-Endpoint zur Erstellung mehrerer Benutzer aus CSV.
- `scripts/powershell/create_user.ps1`: PowerShell-Skript zum Erstellen eines einzelnen Benutzers.
- `scripts/powershell/create_users_csv.ps1`: PowerShell-Skript zum Erstellen mehrerer Benutzer aus CSV.

- `scripts/powershell/check_environment.ps1`: Prüft, ob `ActiveDirectory`-Modul vorhanden ist und zeigt die ausführende Identität an.

API endpoints:
- `public/api/powershell_check.php`: Ruft `check_environment.ps1` auf und gibt ein JSON-Objekt mit `actor`, `module_installed`, `can_new_aduser` zurück.

Bitte testen zuerst mit `powershell.dry_run = true` und prüfen sie die resultierenden Meldungen in UI.


## Mitwirken

Wer etwas ändern oder erweitern möchte:

- Branch vom aktuellen Stand erstellen
- Entwickeln, Committen, Pushen
- PR zuerst nach `develop`, später nach bestandenen Tests nach `main`
- Reviewer zuweisen (für `main`)

Nur tested und reviewed Code gelangt in die Produktion.

---

## Ziel

Das AdminTool soll eine wartbare, erweiterbare und zuverlässige Verwaltungsoberfläche bieten, die zentrale Aufgaben des AD‑Umfelds über eine moderne Weboberfläche ermöglicht.