From dcb6eb67d63fdfaf9f8145e0f128c6be7c6ca5bb Mon Sep 17 00:00:00 2001 From: blaerf Date: Sat, 15 Nov 2025 13:08:19 +0100 Subject: [PATCH] =?UTF-8?q?Erkl=C3=A4rungen=20f=C3=BCr=20Ordner=20hinzugef?= =?UTF-8?q?=C3=BCgt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Projektstruktur-und-Best-Practices.-.md | 189 ++++++++++++++++++++---- 1 file changed, 157 insertions(+), 32 deletions(-) diff --git a/Projektstruktur-und-Best-Practices.-.md b/Projektstruktur-und-Best-Practices.-.md index b448242..342e461 100644 --- a/Projektstruktur-und-Best-Practices.-.md +++ b/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.