diff --git a/Projektstruktur-und-Best-Practices.-.md b/Projektstruktur-und-Best-Practices.-.md index db7b28f..de5fa44 100644 --- a/Projektstruktur-und-Best-Practices.-.md +++ b/Projektstruktur-und-Best-Practices.-.md @@ -1,234 +1,234 @@ -# Projektstruktur - -*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, sodass jedes Teammitglied genau versteht, was wohin gehört und warum. - ---- - -# 1. Ordnerstruktur im Gitea-Repository - -``` -ad-admin-panel\ -├── public\ -│ ├── index.php -│ ├── css\ -│ ├── js\ -│ ├── images\ -│ └── assets\ -├── app\ -│ ├── Controllers\ -│ ├── Services\ -│ │ ├── Ldap\ -│ │ ├── Powershell\ -│ │ └── Snmp\ -│ ├── Models\ -│ └── Helpers\ -├── config\ -│ ├── config.example.php -│ └── config.php -├── scripts\ -│ └── powershell\ -├── storage\ -│ ├── logs\ -│ └── uploads\ -├── docs\ -│ ├── Architektur.md -│ ├── Deployment.md -│ └── API-Endpunkte.md -├── .gitignore -└── README.md -``` - ---- - -## 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. - ---- - -### **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? - -### **.gitignore im Repository-Root** -Im Hauptverzeichnis des Repositories liegt eine `.gitignore`-Datei. Sie sorgt dafür, dass keine temporären oder sensiblen Daten versioniert werden: -``` -\vendor\ -\.idea\ -\.vscode\ -\storage\ -\config.php -``` - ---- - -# 2. Struktur auf dem IIS-Server - -``` -C:\Web\AdAdminPanel -├── public\ # Webroot im IIS -├── app\ -├── config\ -├── scripts\ -│ └── powershell\ -├── storage\ -│ ├── logs\ -│ └── uploads\ -└── vendor\ -``` - -### Wichtige Punkte: - -- 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 - ---- - -# 3. Warum diese Struktur gut für das Projekt ist - -- 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 - ---- - -# 4. Zusammenfassung - -Diese Ordnerstruktur ermöglicht: - -- Klarheit -- Sicherheit -- Wartbarkeit -- Teamfähigkeit -- saubere Trennung von Frontend, Logik und Server-Skripten - -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. - +# Projektstruktur + +*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, sodass jedes Teammitglied genau versteht, was wohin gehört und warum. + +--- + +# 1. Ordnerstruktur im Gitea-Repository + +``` +ad-admin-panel\ +├── public\ +│ ├── index.php +│ ├── css\ +│ ├── js\ +│ ├── images\ +│ └── assets\ +├── app\ +│ ├── Controllers\ +│ ├── Services\ +│ │ ├── Ldap\ +│ │ ├── Powershell\ +│ │ └── Snmp\ +│ ├── Models\ +│ └── Helpers\ +├── config\ +│ ├── config.example.php +│ └── config.php +├── scripts\ +│ └── powershell\ +├── storage\ +│ ├── logs\ +│ └── uploads\ +├── docs\ +│ ├── Architektur.md +│ ├── Deployment.md +│ └── API-Endpunkte.md +├── .gitignore +└── README.md +``` + +--- + +## 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. + +--- + +### **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? + +### **.gitignore im Repository-Root** +Im Hauptverzeichnis des Repositories liegt eine `.gitignore`-Datei. Sie sorgt dafür, dass keine temporären oder sensiblen Daten versioniert werden: +``` +\vendor\ +\.idea\ +\.vscode\ +\storage\ +\config.php +``` + +--- + +# 2. Struktur auf dem IIS-Server + +``` +C:\Web\AdAdminPanel +├── public\ # Webroot im IIS +├── app\ +├── config\ +├── scripts\ +│ └── powershell\ +├── storage\ +│ ├── logs\ +│ └── uploads\ +└── vendor\ +``` + +### Wichtige Punkte: + +- 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 + +--- + +# 3. Warum diese Struktur gut für das Projekt ist + +- 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 + +--- + +# 4. Zusammenfassung + +Diese Ordnerstruktur ermöglicht: + +- Klarheit +- Sicherheit +- Wartbarkeit +- Teamfähigkeit +- saubere Trennung von Frontend, Logik und Server-Skripten + +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. +