Erklärungen für Ordner hinzugefügt

Projektstruktur-und-Best-Practices.-.md

@@ -2,21 +2,21 @@
 
 *Hinweis: Dies ist lediglich ein Vorschlag meinerseits, um eine klare, sichere und nachvollziehbare Struktur für unser PHP-/AD-Projekt zu gewährleisten.*
 
-Dieses Dokument beschreibt die empfohlene Ordnerstruktur für das Gitea-Repository und für den späteren IIS-Server. Ziel ist es, dass alle Teammitglieder dieselbe Struktur nutzen und dadurch ein einheitliches, stabiles Projekt entsteht.
+Dieses Dokument beschreibt die empfohlene Ordnerstruktur für das Gitea-Repository und für den späteren IIS-Server, sodass jedes Teammitglied genau versteht, was wohin gehört und warum.
 
 ---
 
-## Empfohlene Ordnerstruktur im Gitea-Repository
+# 1. Ordnerstruktur im Gitea-Repository
 
 ```
 ad-admin-panel/
-├── public/                 
-│   ├── index.php           
+├── public/
+│   ├── index.php
 │   ├── css/
 │   ├── js/
 │   ├── images/
 │   └── assets/
-├── app/                    
+├── app/
 │   ├── Controllers/
 │   ├── Services/
 │   │   ├── Ldap/
@@ -36,22 +36,144 @@ ad-admin-panel/
 │   ├── Architektur.md
 │   ├── Deployment.md
 │   └── API-Endpunkte.md
-├── tests/
 ├── .gitignore
-├── composer.json
 └── README.md
 ```
 
-### Hinweise
+---
 
-- `public/` ist das **einzige** Verzeichnis, das öffentlich erreichbar sein soll.
-- `config.php`, `scripts/`, `storage/` gehören **nicht** ins Webroot.
-- Die App wird strukturiert in Controller, Services, Models, Helpers.
-- PowerShell-Skripte bleiben im Repo, liegen aber später auf dem Server außerhalb des Webroots.
+## 1.1 Erklärung aller Ordner
+
+### **public/**
+Dies ist das *Webroot* – der einzige Ordner, der direkt über den Browser erreichbar ist.
+
+Hier gehört hinein:
+- `index.php` als Einstiegspunkt
+- CSS-Dateien
+- JavaScript-Dateien
+- Bilder
+- Frontend-Assets
+
+**Warum:**  
+Sicherheit. Alles, was sensibel ist (Config, PowerShell, Logs), liegt *außerhalb* des Webroots.
 
 ---
 
-## Empfohlene Struktur auf dem IIS-Server
+### **app/**
+Hier liegt die komplette PHP-Anwendungslogik.
+
+#### **app/Controllers/**
+- Verarbeiten Requests aus dem Frontend
+- Rufen passende Services auf
+- Geben Views oder JSON zurück
+
+Beispiel: `UserController.php` zeigt Benutzerliste an oder verarbeitet Formulare.
+
+#### **app/Services/**
+Hier steckt die "Fachlogik" des Projekts.
+
+- keine HTML-Ausgabe
+- alles, was LDAP, SNMP, PowerShell oder CSV betrifft
+
+Unterordner:
+
+**Ldap/**
+- LDAP-Verbindungen
+- User anlegen/ändern/löschen
+- Passwörter setzen
+- Gruppen verwalten
+
+**Powershell/**
+- PHP-Wrapper für `.ps1`-Skripte
+- Benutzerverwaltung per AD-Cmdlets
+
+**Snmp/**
+- SNMP-Status auslesen
+- CPU/RAM/Platten/etc. abrufen
+
+#### **app/Models/**
+Reine Datenobjekte, z.B.:
+- `User.php`
+- `ServerStatus.php`
+
+Hier werden keine Aktionen ausgeführt – nur Struktur & Daten.
+
+#### **app/Helpers/**
+Werkzeuge für:
+- Validation
+- kleine Utility-Funktionen
+- Logging-Helfer
+
+---
+
+### **config/**
+Globale Einstellungen.
+
+**config.example.php**  
+– liegt im Repo  
+– enthält die Struktur, aber keine Passwörter
+
+**config.php**  
+– echte Config  
+– kommt in `.gitignore`  
+– enthält LDAP-Credentials, SNMP-Settings, Pfade usw.
+
+---
+
+### **scripts/**
+Nicht-öffentliche Skripte, die vom PHP-Code aufgerufen werden.
+
+#### **scripts/powershell/**
+Hier liegen alle `.ps1` Dateien:
+
+- `New-AdUser.ps1`
+- `Set-AdUser.ps1`
+- `Disable-AdUser.ps1`
+- `Import-UsersFromCsv.ps1`
+
+Diese Skripte laufen auf dem Server – **niemals im Webroot**.
+
+---
+
+### **storage/**
+Dynamische Dateien, die während der Laufzeit entstehen.
+
+#### **storage/logs/**
+- PHP-Logs
+- Fehlerprotokolle
+- Aktionen (z.B. wer welchen User angelegt hat)
+
+#### **storage/uploads/**
+- hochgeladene CSV-Dateien für Massenimporte
+- ggf. später Export-Dateien
+
+**Wichtig:**  
+Dieser Ordner wird **nie** versioniert und kommt in `.gitignore`.
+
+---
+
+### **docs/**
+Projektdokumentation.
+
+Hier können alle Markdown-Dokumente rein:
+- `Architektur.md`
+- `Deployment.md`
+- `API-Endpunkte.md`
+- Diagramme, Erklärungen, Beispiele
+
+Diese Unterlagen landen später im Wiki.
+
+---
+
+### **README.md**
+Beschreibung des Projekts  
+– Was ist das?  
+– Wie installiert man es?  
+– Wie läuft es?
+
+---
+
+# 2. Struktur auf dem IIS-Server
 
 ```
 C:\Web\AdAdminPanel
@@ -66,34 +188,37 @@ C:\Web\AdAdminPanel
 └── vendor
 ```
 
-### Sicherheit
+### Wichtige Punkte:
 
-- IUSR/AppPool-Identität erhält nur die Rechte, die sie braucht.
-- PowerShell-Skripte sollten nur von einem speziellen Service-Account ausgeführt werden.
-- `storage/` wird für Logs und Uploads verwendet und nicht in Git versioniert.
+- IIS zeigt **nur auf `public/`**
+- `config/`, `scripts/`, `storage/` bleiben *unsichtbar* für den Browser
+- PowerShell läuft über einen eigenen Service-Account
+- AppPool-Identität erhält nur minimal benötigte Rechte
 
 ---
 
-## Bereiche, die von der Struktur profitieren
+# 3. Warum diese Struktur gut für das Projekt ist
 
-- AD-Benutzerverwaltung (LDAP/PowerShell)
-- CSV-Massenanlage
-- SNMP-Serverstatus
-- Logging
-- Wartbarkeit der PHP-Anwendung
-- Deployment über Gitea
+- sicher (Webroot klar getrennt)
+- einfach zu verstehen
+- klarer Ort für jede Art Datei
+- PowerShell sauber gekapselt
+- CSV-Verarbeitung logisch eingebettet
+- SNMP & LDAP sauber strukturiert
+- guter Team-Workflow
+- Deployment klar und eindeutig
 
 ---
 
-## Zusammenfassung
+# 4. Zusammenfassung
 
-Diese Struktur trennt sauber:
+Diese Ordnerstruktur ermöglicht:
 
-- Weboberfläche  
-- Anwendungslogik  
-- Konfiguration  
-- PowerShell-Integration  
-- Uploads & Logs  
+- Klarheit
+- Sicherheit
+- Wartbarkeit
+- Teamfähigkeit
+- saubere Trennung von Frontend, Logik und Server-Skripten
 
-Damit bekommt das Projekt eine stabile technische Basis und jeder aus dem Team kann konsistent daran arbeiten.
+Sie sorgt dafür, dass jeder sofort versteht, **wohin was gehört** – ohne Chaos und ohne Risiko, dass Passwörter oder Skripte versehentlich öffentlich sind.