docs: restructure docs to diataxis and finalize DOCS-RESTRUCTURE-001

2026-03-06 12:25:18 +01:00
parent 9caa0a4f75
commit 72886f4784
49 changed files with 564 additions and 180 deletions
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,104 +1,101 @@
 # Dokumentation

-Letzte Aktualisierung: 2026-03-04
+Letzte Aktualisierung: 2026-03-06

-Diese Dokumentation folgt einem klaren Lernpfad (einfach -> fortgeschritten) und trennt Lernen von Nachschlagen.
+Diese Dokumentation ist nach dem Diataxis-Modell in vier Quadranten gegliedert: Tutorials zum Lernen, How-to Guides zum Nachschlagen von Aufgaben, Explanation zum Verstehen und Reference zum Nachschlagen von Fakten.

-## Lernpfad (chronologisch)
+## Tutorials

-1. `/docs/00-systemueberblick.md`
+1. `/docs/tutorial-01-erste-schritte.md`
+   - Schnellstart: Repo klonen, Container starten, erster Login.
+2. `/docs/tutorial-02-systemueberblick.md`
   - Produktbild, Kernmodule und Lernziel in 10 Minuten.
-2. `/docs/01-setup-und-erster-login.md`
+3. `/docs/tutorial-03-setup-und-erster-login.md`
   - Lokales Setup, erster Login, erster Smoke-Test.
-3. `/docs/02-domain-glossar.md`
-   - Zentrale Begriffe (Tenant, Role, Permission, Scope, Policy).
-4. `/docs/03-architektur-request-flow.md`
+4. `/docs/tutorial-04-architektur-request-flow.md`
   - Request-Flow, Schichtmodell, Do/Don't.
-5. `/docs/04-erste-aenderung-ui.md`
-   - Erste sichere UI-Änderung im Admin-Bereich.
-6. `/docs/05-erste-aenderung-backend.md`
-   - Erste Backend-/Service-/Repository-Änderung.
-7. `/docs/06-security-tenant-scope.md`
+5. `/docs/tutorial-05-erste-aenderung-ui.md`
+   - Erste sichere UI-Aenderung im Admin-Bereich.
+6. `/docs/tutorial-06-erste-aenderung-backend.md`
+   - Erste Backend-/Service-/Repository-Aenderung.
+7. `/docs/tutorial-07-security-tenant-scope.md`
   - Sicherheitsgrundlagen, Tenant-Scope, Pflichtchecks.
-8. `/docs/07-api-erweitern.md`
-   - API-Änderung sauber mit OpenAPI und Tests umsetzen.
-9. `/docs/08-advanced-scheduler-sso.md`
+8. `/docs/tutorial-08-api-erweitern.md`
+   - API-Aenderung sauber mit OpenAPI und Tests umsetzen.
+9. `/docs/tutorial-09-advanced-scheduler-sso.md`
   - Fortgeschrittene Themen: Scheduler, Lifecycle, SSO.

-## Konzepte (Explanation)
+## How-to Guides

- `/docs/architektur.md`
-  - Architektur-Kompass mit verbindlichen Leitplanken.
- `/docs/di-container.md`
-  - Wie der AppContainer funktioniert und neue Services registriert werden.
- `/docs/sicherheitsmodell.md`
-  - Vollständiges Sicherheitsmodell (Auth, Permission, Scope).
- `/docs/einstellungen-speicherung.md`
-  - Warum Settings in DB + Datei-Cache koexistieren.
-
-## Aufgabenanleitungen (How-to)
-
- `/docs/globale-suche.md`
+- `/docs/howto-erste-aenderung.md`
+  - Schritt-fuer-Schritt durch die erste Codeaenderung.
+- `/docs/howto-globale-suche.md`
  - Neue Resource in der globalen Suche integrieren.
- `/docs/importe.md`
+- `/docs/howto-importe.md`
  - Importfluss, Regeln und Fehlercodes.
- `/docs/benutzerdefinierte-felder.md`
+- `/docs/howto-benutzerdefinierte-felder.md`
  - Tenant/User-Zusatzfelder korrekt erweitern.
- `/docs/geplante-aufgaben.md`
+- `/docs/howto-geplante-aufgaben.md`
  - Neue Scheduler-Jobs registrieren und betreiben.
- `/docs/auth-sso-smoke-test.md`
-  - SSO-Funktionalität manuell verifizieren.
- `/docs/anfragelimits.md`
+- `/docs/howto-auth-sso-smoke-test.md`
+  - SSO-Funktionalitaet manuell verifizieren.
+- `/docs/howto-anfragelimits.md`
  - Rate-Limits verstehen und testen.
- `/docs/rbac-permissions-playbook.md`
-  - RBAC-Rechte sauber erweitern (neue Permission, neue Ability, UI/API-Fälle).
- `/docs/request-input-validation.md`
-  - Einheitliches Request/Input- und Validation-Muster für Web + API.
-
-## Referenz (Reference)
-
- `/docs/api.md`
-  - API-Referenz-Einstieg.
- `/docs/konfiguration.md`
-  - ENV-Variablen und Produktions-Defaults.
- `/docs/konventionen.md`
-  - Projektweite Konventionen (kurz und verbindlich).
- `/docs/lib-standards.md`
-  - Regeln speziell für `lib/**`.
- `/docs/benutzer-lifecycle-policy.md`
-  - Policy- und Laufzeitreferenz für User Lifecycle.
-
-## Betrieb (Operations)
-
- `/docs/docker-lokal.md`
+- `/docs/howto-rbac-permissions-playbook.md`
+  - RBAC-Rechte sauber erweitern (neue Permission, neue Ability, UI/API-Faelle).
+- `/docs/howto-request-input-validation.md`
+  - Einheitliches Request/Input- und Validation-Muster fuer Web + API.
+- `/docs/howto-docker-lokal.md`
  - Lokaler Docker-Betrieb.
- `/docs/docker-produktiv.md`
+- `/docs/howto-docker-produktiv.md`
  - Produktivbetrieb mit Docker.
- `/docs/docker-betrieb.md`
-  - Übersicht und Entscheidungshilfe für Dev/Prod.
- `/docs/betriebscheck-doctor.md`
+- `/docs/howto-betriebscheck-doctor.md`
  - Schneller Systemcheck mit `bin/doctor.php`.
- `/docs/fehlerbehebung.md`
-  - Häufige Fehler und schnelle Lösungen.
+- `/docs/howto-fehlerbehebung.md`
+  - Haeufige Fehler und schnelle Loesungen.
+- `/docs/howto-lokale-entwicklung.md`
+  - Tages-Workflow fuer Entwicklung und Checks.
+- `/docs/howto-dokumentation-erweitern.md`
+  - Regeln fuer konsistente, wachsende Doku.

-## Mitwirken (Contributor Guide)
+## Explanation

- `/docs/lokale-entwicklung.md`
-  - Tages-Workflow für Entwicklung und Checks.
- `/docs/entwickler-checkliste.md`
+- `/docs/explanation-architektur.md`
+  - Architektur-Kompass mit verbindlichen Leitplanken.
+- `/docs/explanation-di-container.md`
+  - Wie der AppContainer funktioniert und neue Services registriert werden.
+- `/docs/explanation-sicherheitsmodell.md`
+  - Vollstaendiges Sicherheitsmodell (Auth, Permission, Scope).
+- `/docs/explanation-einstellungen-speicherung.md`
+  - Warum Settings in DB + Datei-Cache koexistieren.
+- `/docs/explanation-docker-betrieb.md`
+  - Uebersicht und Entscheidungshilfe fuer Dev/Prod.
+
+## Reference
+
+- `/docs/reference-domain-glossar.md`
+  - Zentrale Begriffe (Tenant, Role, Permission, Scope, Policy).
+- `/docs/reference-api.md`
+  - API-Referenz-Einstieg.
+- `/docs/reference-konfiguration.md`
+  - ENV-Variablen und Produktions-Defaults.
+- `/docs/reference-konventionen.md`
+  - Projektweite Konventionen (kurz und verbindlich).
+- `/docs/reference-lib-standards.md`
+  - Regeln speziell fuer `lib/**`.
+- `/docs/reference-benutzer-lifecycle-policy.md`
+  - Policy- und Laufzeitreferenz fuer User Lifecycle.
+- `/docs/reference-frontend-css.md`
+  - CSS-Schichtsystem und Namenskonventionen.
+- `/docs/reference-frontend-javascript.md`
+  - JS-Module, DOM-Utilities und Patterns.
+- `/docs/reference-entwickler-checkliste.md`
  - Definition of Done vor Merge.
- `/docs/codex-prompts.md`
-  - Standard-Prompts für Skill-basierte Planung und Implementierung.
- `/docs/dokumentation-erweitern.md`
-  - Regeln für konsistente, wachsende Doku.
-
-## Agent Workflow
-
- `/docs/agents/overview.md`
+- `/docs/reference-codex-prompts.md`
+  - Standard-Prompts fuer Skill-basierte Planung und Implementierung.
+- `/docs/reference-agents-overview.md`
  - Einstieg in das Rollenmodell und die Artefakte.
- `/docs/agents/roles.md`
+- `/docs/reference-agents-roles.md`
  - Klare Verantwortung je Rolle (Planner, Executor, Reviewer, Finalizer).
- `/docs/agents/flow.md`
+- `/docs/reference-agents-flow.md`
  - State-Flow mit Fail-Loop zur Executor-Iteration.
- `/agent-system/README.md`
-  - Technische Basis mit Contracts, Templates, Prompts und Checks.