chore: sync staging workspace

docs/Makefile.md

@@ -0,0 +1,66 @@
+# Makefile Quick Reference
+
+Dieses Dokument fasst die wichtigsten Ziele aus dem Projekt-Makefile zusammen und erklärt, wie du sie anpasst.
+
+## Grundlagen
+
+- `make help` listet alle verfügbaren Targets mit Kurzbeschreibung.
+- Alle Docker-Befehle nutzen standardmäßig `docker compose`; überschreibe das Kommando bei Bedarf mit `DOCKER=...`.
+- Variablen wie `PHP_SERVICE`, `COMPOSER_BIN`, `NODE_BIN` oder `ARGS` lassen sich beim Aufruf anpassen, z. B. `make phpstan PHP_SERVICE=php-alt`.
+
+## Container-Steuerung
+
+| Befehl | Beschreibung |
+| ------ | ------------ |
+| `make up` | startet die lokale Docker-Umgebung im Hintergrund |
+| `make down` | stoppt und entfernt Container, Netzwerke und Volumes |
+| `make build` | baut die Images neu |
+| `make restart` | startet den PHP-Container neu (`PHP_SERVICE`) |
+| `make logs SERVICE=name` | streamt Logs (Standard: alle Container) |
+| `make ps` | zeigt laufende Container |
+
+## Composer & Anwendung
+
+| Befehl | Beschreibung |
+| ------ | ------------ |
+| `make composer-install` | führt `composer install` im PHP-Container aus |
+| `make composer-update` | führt `composer update` aus |
+| `make autoload` | aktualisiert den Autoloader (`composer dump-autoload -o`) |
+| `make console CMD="cache:clear"` | ruft `php console.php` mit übergebenem Befehl auf |
+| `make cache-clear` | ruft intern `console` mit `cache:clear` auf |
+
+## Tests & Qualitätssicherung
+
+| Befehl | Beschreibung |
+| ------ | ------------ |
+| `make test` | führt alle Pest-Tests im Profil `test` aus; weitere Parameter via `ARGS` |
+| `make test-unit` / `test-domain` / `test-framework` | scoped Pest-Läufe für einzelne Ordner |
+| `make test-watch` | Pest im Watch-Modus |
+| `make test-coverage` / `test-coverage-html` | Coverage-Reports (Text bzw. HTML) |
+| `make test-filter FILTER=Klasse` | filtert Tests nach Name |
+| `make phpstan` | PHPStan-Analyse im Container |
+| `make phpstan-baseline` | erzeugt eine neue Baseline |
+| `make cs` | php-cs-fixer Dry-Run |
+| `make cs-fix` | php-cs-fixer mit automatischer Korrektur |
+| `make security-check` | führt `composer audit` aus |
+
+## Frontend-Helper
+
+| Befehl | Beschreibung |
+| ------ | ------------ |
+| `make npm-install` | installiert Node-Abhängigkeiten |
+| `make npm-build` | baut Produktions-Assets via Vite |
+| `make npm-dev` | startet den Vite-Dev-Server |
+| `make npm-test` | führt JavaScript-Tests aus |
+
+## Git & Deployment
+
+| Befehl | Beschreibung |
+| ------ | ------------ |
+| `make push-staging` | pusht den aktuellen HEAD nach `origin/staging` |
+
+## Tipps
+
+- `console` und andere Container-Kommandos verwenden `docker exec -it`; wenn die Umgebung keine TTY mag (z. B. CI), `TTY=0 make console CMD="list"` ausführen und das Makefile bei Bedarf erweitern.
+- Tests laufen im Container `php-test` mit dem Compose-Profil `test`. Vor der Nutzung sicherstellen, dass das Profil gebaut wurde (`make build`).
+- Zusätzliche Shortcuts lassen sich leicht durch neue Targets ergänzen – einfach mit Beschreibung versehen und in `.PHONY` aufnehmen, damit GNU Make nicht versucht, gleichnamige Dateien zu bauen.