feat(storage): add local storage framework

CONTRIBUTING.md

@@ -73,7 +73,7 @@ Eine Aenderung gilt erst als fertig, wenn diese Punkte erfuellt sind:
 - keine `.venv` im Git
 - keine toten Imports
 - keine ungenutzten Dateien
-- keine Debug-Ausgaben wie `console.log`, `alert` oder `confirm`
+- keine Debug-Ausgaben oder Browser-Dialoge im Anwendungscode
 
 Standard-Checks:
 
@@ -103,7 +103,7 @@ uv run alembic upgrade head
 - Wiederverwendbare Komponenten bevorzugen.
 - UI-Zustaende immer abbilden: Loading, Error, Empty State.
 - Erfolg und Fehler in mutierenden CRUD-Flows ueber den Toast-Provider melden.
-- Keine Browser-Dialoge wie `alert()` oder `confirm()`.
+- Keine nativen Browser-Dialoge fuer produktive UI-Flows.
 - Keine Tokens in Browser-JavaScript speichern.
 - Datei-Uploads vom Browser laufen ueber Athena-BFF-Routen und werden serverseitig an Hermes weitergeleitet.
 
@@ -120,10 +120,12 @@ uv run alembic upgrade head
 - Mutierende Kernaktionen mit Audit Logs erfassen, sofern fachlich relevant.
 - Sensible Felder vor Persistenz in Logs oder Audit-Daten maskieren.
 - Import- und Bootstrap-Flows duerfen keine Passwoerter, Tokens, Secrets oder vollstaendige CSV-Inhalte loggen.
+- Dateiablagen laufen ueber `StorageService`; direkte Dateioperationen in Fachservices sind nur mit guter Begruendung zulaessig.
+- Uploads muessen Dateityp, MIME-Type, Groesse, Dateiname und Storage-Pfad validieren.
 
 ### Allgemein
 
-- Keine TODOs als Ersatz fuer fertige Implementierung.
+- Keine Platzhalter-Kommentare als Ersatz fuer fertige Implementierung.
 - Keine Quickfixes.
 - Keine Workarounds.
 - Keine ungeprueften Annahmen bei Auth, Datenbank oder Docker.
@@ -237,17 +239,35 @@ Upload-Regeln:
 - Browser sendet Dateien nur an Athena.
 - Athena leitet FormData serverseitig an Hermes weiter.
 - Hermes validiert Dateityp, MIME-Type, Dateigroesse und Speicherpfad.
-- Lokale Dateien liegen unter `KNOWLEDGE_STORAGE_PATH`.
+- Lokale Dateien liegen ueber Docker unter `STORAGE_BASE_PATH`; alte Knowledge-Pfade bleiben nur als Legacy-Fallback erhalten.
 - Audit Logs duerfen keine Datei-Inhalte enthalten.
 - Keine Pfade aus unvalidierten Benutzereingaben zusammensetzen.
 
 Paperless-ngx ist nur vorbereitet. `paperless_document_id` und `external_url` duerfen gepflegt werden, aber es werden keine Paperless-Secrets oder API-Keys eingefuehrt.
 
+### Storage
+
+Neue Dateiablagen muessen das zentrale Storage Framework verwenden.
+
+Regeln:
+
+- Keine unvalidierten Pfade aus Benutzereingaben zusammensetzen.
+- Keine absoluten User-Pfade akzeptieren.
+- Keine Path-Traversal-Moeglichkeiten zulassen.
+- Originaldateinamen und gespeicherte Dateinamen fachlich unterscheiden.
+- SHA256 fuer gespeicherte Dateien berechnen, sofern das Modul Datei-Metadaten persistiert.
+- Keine Datei-Inhalte loggen.
+- Bestehende Dateien nicht automatisch verschieben oder loeschen.
+
+Der lokale Provider nutzt `STORAGE_BASE_PATH`; Docker mountet den Host-Pfad aus `STORAGE_HOST_PATH` nach `/data/storage`.
+
 ### Deployment
 
 Neue Installationen koennen optional ueber `INITIAL_ADMIN_*` einen initialen Administrator anlegen. Diese Variablen werden nur von Hermes gelesen und duerfen nicht im Frontend oder in Logs erscheinen.
 
-Knowledge-Dateien benoetigen ein persistentes Docker-Volume. Vor produktiven Deployments muessen `KNOWLEDGE_STORAGE_PATH` und `KNOWLEDGE_MAX_UPLOAD_MB` bewusst gesetzt oder die Defaults akzeptiert werden.
+Dateien benoetigen einen persistenten Storage-Mount. Vor produktiven Deployments muessen `STORAGE_PROVIDER`, `STORAGE_BASE_PATH`, `STORAGE_MAX_UPLOAD_MB` und `STORAGE_HOST_PATH` bewusst gesetzt oder die Defaults akzeptiert werden.
+
+Die Skripte unter `scripts/` sind die bevorzugte Grundlage fuer Migration, Healthcheck, Deploy, Backup und Restore.
 
 ### Neue Permissions
 
@@ -299,6 +319,9 @@ Vor Merge pruefen:
 - Audit Logs fuer relevante Aenderungen vorhanden
 - API-Fehlerantworten konsistent
 - Toasts fuer mutierende UI-Aktionen vorhanden
+- Dateiablagen verwenden `StorageService`
+- Storage-Pfade sind gegen Path Traversal geschuetzt
+- Backup-/Restore-Auswirkungen fuer Dateiablagen dokumentiert
 
 ## Migrationsregeln