feat(storage): add local storage framework

README-DEV.md

@@ -0,0 +1,185 @@
+# Olympus CRM Entwicklungssetup
+
+Dieses Dokument beschreibt das lokale Setup fuer neue Rechner und parallele Entwicklung auf mehreren Macs.
+
+## Setup auf neuem Mac
+
+Voraussetzungen:
+
+- Git
+- Docker Desktop
+- Node.js passend zu Athena
+- Python/uv fuer lokale Hermes-Checks
+
+Repository klonen:
+
+```bash
+git clone <repository-url> Olympus
+cd Olympus
+```
+
+Umgebung anlegen:
+
+```bash
+cp .env.example .env
+```
+
+Wichtige lokale Werte:
+
+```env
+AUTH_COOKIE_SECURE=false
+ATHENA_PUBLIC_ORIGIN=http://localhost:3001
+STORAGE_PROVIDER=local
+STORAGE_BASE_PATH=/data/storage
+STORAGE_MAX_UPLOAD_MB=50
+STORAGE_HOST_PATH=./storage
+```
+
+Wenn `SECRET_KEY` Sonderzeichen wie `$` enthaelt, den Wert in der Shell oder Compose-Umgebung korrekt quoten. Secrets gehoeren nicht ins Git.
+
+## Docker Netzwerk
+
+Das gemeinsame Compose-File nutzt ein externes Docker-Netzwerk:
+
+```bash
+docker network create olympus-network
+```
+
+Wenn das Netzwerk bereits existiert, meldet Docker das nur als Hinweis.
+
+## Docker Compose Start
+
+```bash
+docker compose build
+docker compose up -d
+```
+
+Hermes ist im gemeinsamen Stack nur intern im Docker-Netzwerk erreichbar. Athena ist lokal ueber den Browser erreichbar:
+
+- Athena: `http://localhost:3001`
+- Hermes intern: `http://hermes:8000`
+
+Der Browser spricht nicht direkt mit Hermes.
+
+## Migrationen
+
+Migrationen ausfuehren:
+
+```bash
+scripts/migrate.sh
+```
+
+Alternativ lokal im Backend:
+
+```bash
+cd backend/hermes
+uv run alembic upgrade head
+```
+
+## Initial Admin
+
+Fuer neue Installationen ohne aktive Benutzer kann Hermes beim Startup einen initialen Admin anlegen.
+
+```env
+INITIAL_ADMIN_USERNAME=admin
+INITIAL_ADMIN_EMAIL=admin@example.local
+INITIAL_ADMIN_PASSWORD=<lokales-passwort>
+INITIAL_ADMIN_FIRST_NAME=
+INITIAL_ADMIN_LAST_NAME=
+```
+
+Diese Werte nur lokal oder sicher auf dem Zielsystem setzen. Nach dem ersten produktiven Login sollte das Passwort geaendert und die Bootstrap-Variablen wieder entfernt werden.
+
+## Login
+
+Nach Start und Migration:
+
+1. Browser auf `http://localhost:3001` oeffnen.
+2. Mit dem initialen Admin oder einem bestehenden Benutzer anmelden.
+3. Athena setzt das HttpOnly-Cookie. Hermes setzt keine Browser-Cookies.
+
+## Storage
+
+Neue Dateiablagen laufen ueber das Storage Framework.
+
+Lokaler Standard:
+
+```env
+STORAGE_HOST_PATH=./storage
+STORAGE_BASE_PATH=/data/storage
+```
+
+VPS-Empfehlung:
+
+```env
+STORAGE_HOST_PATH=/opt/olympus-storage
+STORAGE_BASE_PATH=/data/storage
+```
+
+Bestehende Knowledge-Dateien aus alten Setups unter `/data/knowledge` werden nicht automatisch verschoben. Vor einer manuellen Migration immer Backup erstellen.
+
+## Typische Fehler
+
+Hermes restartet wegen fehlender Migration:
+
+```bash
+scripts/migrate.sh
+docker compose restart hermes
+```
+
+`SECRET_KEY` mit `$` wird falsch interpretiert:
+
+- Wert in `.env` korrekt escapen oder quoten.
+- Keine Secrets in Commit oder Logs schreiben.
+
+Docker Container Name Conflict:
+
+```bash
+docker compose down
+docker ps -a
+```
+
+Danach blockierenden Altcontainer gezielt entfernen, wenn er wirklich nicht mehr gebraucht wird.
+
+External network fehlt:
+
+```bash
+docker network create olympus-network
+```
+
+DB leer oder Admin fehlt:
+
+- `INITIAL_ADMIN_*` Werte setzen.
+- `scripts/migrate.sh` ausfuehren.
+- `docker compose restart hermes`.
+
+Athena nicht erreichbar:
+
+- `docker compose ps` pruefen.
+- Port `3001` auf dem Rechner pruefen.
+- `scripts/healthcheck.sh` ausfuehren.
+
+## MacBook und Mac mini parallel
+
+Empfehlung:
+
+- `.env` pro Rechner lokal pflegen und nicht committen.
+- `STORAGE_HOST_PATH` pro Rechner bewusst setzen.
+- Datenbank- und Storage-Backups nicht ungeprueft zwischen Rechnern ueberschreiben.
+- Vor Branch-Wechseln Migrationen pruefen.
+- Bei paralleler Arbeit keine Docker-Volumes loeschen, solange ungesicherte Uploads existieren.
+
+## Qualitaetschecks
+
+```bash
+python3 -m compileall backend/hermes/app
+cd frontend/athena
+npm run lint
+npx next build --webpack
+```
+
+Skripte pruefen:
+
+```bash
+bash -n scripts/*.sh
+```