From 3614421edad519ed012ad6cde6482afe9a361001 Mon Sep 17 00:00:00 2001 From: fs Date: Wed, 25 Mar 2026 19:15:53 +0100 Subject: [PATCH] fix(docs): resolve documentation drift and add missing content - Fix fictional SettingGateway/SettingService references with actual multi-gateway pattern (AdminSettingsService + domain-specific gateways) - Replace non-existent gridQueryLimitOffset()/gridQueryOrderDir() with actual gridParseFiltersFromSchemaFile() - Normalize bin/doctor.php references to canonical bin/console doctor - Add i18n_path contract to module manifest docs - Document module:validate and make:module CLI commands - Add APP_VENDOR_PHP_ISSUES_MODE env var to config reference - Remove invalid label field from notifications module permissions (violates manifest schema additionalProperties: false) Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/explanation-architektur.md | 5 ++-- docs/explanation-docker-betrieb.md | 2 +- docs/explanation-einstellungen-speicherung.md | 6 ++--- docs/explanation-sicherheitsmodell.md | 2 +- docs/howto-erste-aenderung.md | 4 ++-- docs/howto-fehlerbehebung.md | 2 +- docs/reference-cli-commands.md | 23 ++++++++++++++++++- docs/reference-konfiguration.md | 3 ++- docs/reference-module-manifest-contract.md | 12 +++++++++- modules/notifications/module.php | 1 - 10 files changed, 45 insertions(+), 15 deletions(-) diff --git a/docs/explanation-architektur.md b/docs/explanation-architektur.md index 9762ae8..bffb558 100644 --- a/docs/explanation-architektur.md +++ b/docs/explanation-architektur.md @@ -1,6 +1,6 @@ # Architektur-Kompass -Letzte Aktualisierung: 2026-03-06 +Letzte Aktualisierung: 2026-03-25 ## Ziel @@ -85,8 +85,7 @@ flowchart TD - In `pages/api/v1/**` kein direktes JSON-Body-Lesen über `ApiResponse::readJsonBody(...)`. - `Flash` nur für Redirect-/Outcome-Meldungen verwenden, nicht als primäre Validation-Struktur. - Listen-Endpoints in `pages/**/data().php` sind GET-only (`gridRequireGetRequest()`). -- Query-Filter in `data().php` über `gridParseFilters(...)` + `filter-schema.php` normalisieren. -- Grid-Query-Parameter (`limit`, `offset`, `order`, `dir`) in `data().php` über `gridQueryLimitOffset()` und `gridQueryOrderDir()` normalisieren. +- Query-Filter in `data().php` über `gridParseFiltersFromSchemaFile(...)` + `filter-schema.php` normalisieren (enthält `limit`, `offset`, `order`, `dir` im Ergebnis). ## Instanziierungsregeln (MUSS) diff --git a/docs/explanation-docker-betrieb.md b/docs/explanation-docker-betrieb.md index cf01b17..8264284 100644 --- a/docs/explanation-docker-betrieb.md +++ b/docs/explanation-docker-betrieb.md @@ -16,4 +16,4 @@ Die Docker-Dokumentation ist in zwei klare Pfade getrennt: - Für tägliche Entwicklung immer mit `docker-compose.yml` arbeiten. - Für Serverbetrieb ausschließlich `docker-compose.prod.yml` verwenden. - Änderungen an Domain/TLS nur in der Produktivdoku und den Produktivdateien pflegen. -- Nach Start oder Deployment einmal `docker compose exec php sh -lc "php bin/doctor.php"` ausführen. +- Nach Start oder Deployment einmal `docker compose exec php php bin/console doctor` ausführen. diff --git a/docs/explanation-einstellungen-speicherung.md b/docs/explanation-einstellungen-speicherung.md index 3534d10..73a5c30 100644 --- a/docs/explanation-einstellungen-speicherung.md +++ b/docs/explanation-einstellungen-speicherung.md @@ -1,6 +1,6 @@ # Einstellungen: Speicherung (DB + Cache) -Letzte Aktualisierung: 2026-03-06 +Letzte Aktualisierung: 2026-03-25 ## Kurzfassung @@ -14,7 +14,7 @@ Die Kombination ist bewusst so gebaut: 1. **DB als Wahrheit** - Alle Settings werden persistiert in `settings`. - - Validierung und Schreiblogik laufen über `SettingService`. + - Validierung und Schreiblogik laufen über domänenspezifische Gateways und `AdminSettingsService`. 2. **Datei-Cache für Hot-Path-Reads** - `config/settings.php` wird durch `SettingCacheService` geschrieben. @@ -41,7 +41,7 @@ Daher ist es korrekt, wenn diese Werte in `settings` (DB) vorhanden sind, aber n ## Laufzeitfluss 1. Admin speichert Settings in `admin/settings`. -2. `SettingGateway` (aus `SettingServicesFactory`) delegiert auf `SettingService`, der in DB schreibt. +2. `AdminSettingsService` koordiniert domänenspezifische Gateways (z. B. `SettingsAppGateway`, `SettingsSmtpGateway`, `SettingsMetadataGateway`), die auf `SettingRepository` delegieren und in die DB schreiben. 3. `SettingCacheService` aktualisiert den Datei-Cache nur für den definierten Teilbereich. 4. UI-Helfer `appSetting(...)` liest danach aus Datei-Cache. diff --git a/docs/explanation-sicherheitsmodell.md b/docs/explanation-sicherheitsmodell.md index 8882bea..3f64505 100644 --- a/docs/explanation-sicherheitsmodell.md +++ b/docs/explanation-sicherheitsmodell.md @@ -73,7 +73,7 @@ API-Sonderfall: - Web: Auth-Events + Admin-Write-Aktionen. - API: selektive `api.request`-Events (Write-Requests, `>=500`, Security-Endpunkte bei `>=400`). - Scheduler: `scheduler.run` (Runner-Zusammenfassung) und `scheduler.job.run` (pro Joblauf). - - CLI: `cli.command` für zentrale Betriebsbefehle (z. B. `bin/doctor.php`). + - CLI: `cli.command` für zentrale Betriebsbefehle (z. B. `php bin/console doctor`). - Privacy-Default: - keine Request-/Response-Bodies - keine Klartext-Secrets/Passwörter/Tokens/E-Mails diff --git a/docs/howto-erste-aenderung.md b/docs/howto-erste-aenderung.md index e2905ac..162a404 100644 --- a/docs/howto-erste-aenderung.md +++ b/docs/howto-erste-aenderung.md @@ -1,6 +1,6 @@ # Leitfaden für die erste Änderung -Letzte Aktualisierung: 2026-03-09 +Letzte Aktualisierung: 2026-03-25 ## Ziel @@ -18,7 +18,7 @@ Ein neuer Entwickler soll den ersten Change strukturiert und reproduzierbar umse 3. Grid-Spalte in `pages/admin//index(default).phtml` ergänzen (z. B. `pages/admin/users/index(default).phtml`) 4. i18n-Key für Spaltennamen setzen 5. Service-Auflösung in Action-Dateien nur über `app(Foo::class)` nutzen (kein `new ...Factory()` in `pages/**`) -6. In `data().php`: GET-only (`gridRequireGetRequest()`) und Grid-Querys über `gridQueryLimitOffset()`/`gridQueryOrderDir()` normalisieren +6. In `data().php`: GET-only (`gridRequireGetRequest()`) und Filter/Paging über `gridParseFiltersFromSchemaFile(...)` normalisieren 7. `php -l` + manueller UI-Test ### Done-Kriterien diff --git a/docs/howto-fehlerbehebung.md b/docs/howto-fehlerbehebung.md index 763dc8e..1ecc201 100644 --- a/docs/howto-fehlerbehebung.md +++ b/docs/howto-fehlerbehebung.md @@ -23,7 +23,7 @@ Unklar, ob das Problem aus ENV, DB, Storage, RBAC oder Scheduler kommt. ### Lösung ```bash -docker compose exec php sh -lc "php bin/doctor.php" +docker compose exec php php bin/console doctor ``` Bei `FAIL` zuerst diese Punkte beheben, danach erneut ausführen. diff --git a/docs/reference-cli-commands.md b/docs/reference-cli-commands.md index 8630f82..c01c910 100644 --- a/docs/reference-cli-commands.md +++ b/docs/reference-cli-commands.md @@ -1,6 +1,6 @@ # CLI-Kommandoreferenz -Letzte Aktualisierung: 2026-03-19 +Letzte Aktualisierung: 2026-03-25 ## Einstiegspunkt @@ -89,6 +89,27 @@ docker compose exec php php bin/console scheduler:run Der Docker-Scheduler-Service ruft dieses Kommando automatisch alle 60 Sekunden auf. +### module:validate + +Validiert Manifest, Klassen und Struktur eines Moduls. Prueft Namespace-Konventionen, Interface-Implementierungen, Permission-Key-Formate und Verzeichnisstruktur. + +```bash +docker compose exec php php bin/console module:validate +docker compose exec php php bin/console module:validate --all +``` + +`--all` validiert alle aktiven Module auf einmal. + +### make:module + +Erzeugt die vollstaendige Verzeichnisstruktur fuer ein neues Modul inkl. Manifest, ContainerRegistrar-Stub, AuthorizationPolicy-Stub und leeren Verzeichnissen. + +```bash +docker compose exec php php bin/console make:module +``` + +Argument `module-id` muss dem Pattern `[a-z][a-z0-9-]*` entsprechen. + ### doctor Fuehrt System-Gesundheitschecks aus (ENV, DB, RBAC, Scheduler-Heartbeat). diff --git a/docs/reference-konfiguration.md b/docs/reference-konfiguration.md index 4bf987b..5a46631 100644 --- a/docs/reference-konfiguration.md +++ b/docs/reference-konfiguration.md @@ -1,6 +1,6 @@ # Konfiguration (ENV-Variablen) -Letzte Aktualisierung: 2026-03-24 +Letzte Aktualisierung: 2026-03-25 Alle Konfiguration erfolgt über Umgebungsvariablen in der `.env`-Datei. Vorlage: `.env.example` — niemals echte Credentials committen. @@ -22,6 +22,7 @@ Vorlage: `.env.example` — niemals echte Credentials committen. | `APP_LOCALE` | `de` | Standard-Sprache der Anwendung | | `APP_LOCALES` | `de,en` | Komma-getrennte Liste aller unterstützten Sprachen | | `APP_I18N_DOMAIN` | `default` | Gettext-Domain — bestimmt welche `i18n/default_*.json` geladen wird, normalerweise nicht ändern | +| `APP_VENDOR_PHP_ISSUES_MODE` | `suppress_deprecations` | Umgang mit PHP-Deprecations/Warnings aus Vendor-Code. Werte: `strict` (alle Fehler), `suppress_deprecations` (Deprecations unterdrücken), `suppress_deprecations_warnings` (Deprecations + Warnings unterdrücken). In Produktion auf `strict` setzen | --- diff --git a/docs/reference-module-manifest-contract.md b/docs/reference-module-manifest-contract.md index 8548139..21b482c 100644 --- a/docs/reference-module-manifest-contract.md +++ b/docs/reference-module-manifest-contract.md @@ -1,6 +1,6 @@ # Module Manifest Contract (V1.2) -Letzte Aktualisierung: 2026-03-18 +Letzte Aktualisierung: 2026-03-25 ## Ziel @@ -37,6 +37,16 @@ Enforcement: `ModuleStructureContractTest::testModuleClassesUseModuleNamespace`. - gesetzt und leer (`APP_ENABLED_MODULES=''`): keine Module. - gesetzt mit Liste (`APP_ENABLED_MODULES='a,b'`): exakt diese Module. +## `i18n_path` Contract + +Module mit eigenen Übersetzungsdateien deklarieren den relativen Pfad zum i18n-Verzeichnis: + +```php +'i18n_path' => 'i18n', +``` + +Der `ModuleAutoloader` registriert daraus den absoluten Pfad `modules//i18n/` als zusätzliche Übersetzungsquelle. + ## `permissions` Contract `permissions` ist eine Objektliste: diff --git a/modules/notifications/module.php b/modules/notifications/module.php index 3f41ce0..5ec349c 100644 --- a/modules/notifications/module.php +++ b/modules/notifications/module.php @@ -70,7 +70,6 @@ return [ 'permissions' => [ [ 'key' => 'notifications.view', - 'label' => 'Notifications: View', 'description' => 'View and manage own notifications', ], ],