98 lines
4.9 KiB
Markdown
98 lines
4.9 KiB
Markdown
# Entwicklung und Tests – lokal
|
||
|
||
**Stand:** 18.10.2026. Erstellt im Code-Review aus Code und Workflows. Deployment auf dem Raspberry Pi: [DEPLOYMENT.md](DEPLOYMENT.md).
|
||
|
||
## Voraussetzungen
|
||
|
||
- Python 3.12, Node.js (das Build-Image nutzt Node 22; lokal funktioniert auch Node 24)
|
||
- PostgreSQL 16. Der Benutzer aus `DB_USER` muss Tabellen anlegen und die Rolle `tsumugu_runtime` erstellen dürfen (`CREATEROLE`). Im Compose-Stack ist das der Superuser des Postgres-Containers.
|
||
|
||
## Konfiguration
|
||
|
||
Das Backend liest ausschließlich die Prozessumgebung. Eine `.env`-Datei wird nicht automatisch geladen.
|
||
|
||
| Variable | Pflicht | Default | Bedeutung |
|
||
|---|---|---|---|
|
||
| `TSUMUGU_ENV` | ja | – | `development` oder `production`; ein anderer Wert verhindert den Start |
|
||
| `DB_NAME`, `DB_USER`, `DB_PASSWORD` | ja | – | Owner-Zugang; Migration und Runtime-Rolle |
|
||
| `DB_HOST`, `DB_PORT` | nein | `localhost`, `5432` | – |
|
||
| `DB_RUNTIME_USER` | nein | `tsumugu_runtime` | Rolle des laufenden Pools; erhält dasselbe Passwort wie `DB_USER` |
|
||
| `ALLOWED_ORIGINS` | nein | `http://localhost:5173,http://localhost:3094` | erlaubte `Origin`-Werte für schreibende Aufrufe |
|
||
| `APP_URL` | nein | `http://localhost:5173` | öffentliche Adresse |
|
||
| `MEDIA_ROOT` | nein | `data/media` | Ablage eigener Dateien |
|
||
| `PAPERLESS_MEDIA_ROOT` | nein | leer | lesender Paperless-Ablageordner als Rückfallweg |
|
||
| `SEED_DEMO` | nein | `false` | wirkt nur in Development mit Datenbank `*_test`; in Production verhindert `true` den Start |
|
||
| `SESSION_TTL_HOURS` | nein | `336` | Laufzeit einer Session |
|
||
| `UPLOAD_MAX_BYTES` | nein | `20971520` | Upload-Grenze (Nginx erlaubt 21 MiB) |
|
||
|
||
## Backend starten
|
||
|
||
```bash
|
||
cd backend
|
||
python -m venv .venv && . .venv/bin/activate # Windows: .venv\Scripts\activate
|
||
pip install -r requirements-dev.txt
|
||
export TSUMUGU_ENV=development DB_NAME=tsumugu_local DB_USER=postgres DB_PASSWORD=…
|
||
python -m app.cli migrate
|
||
python -m app.cli create-account --email ich@example.test --name "Ich" --password "mindestens-zehn"
|
||
uvicorn main:app --reload --port 8000
|
||
```
|
||
|
||
Das erste per CLI angelegte Konto wird Betreiber. Alternativ zeigt die Anmeldeseite auf einer leeren Datenbank das Formular „Betreiberkonto“ (siehe Review R-04). `python -m app.entrypoint` entspricht dem Containerstart: Migration, Entfernen von Fixture-Konten, danach Uvicorn auf Port 8000.
|
||
|
||
## Frontend starten
|
||
|
||
```bash
|
||
cd frontend
|
||
npm ci
|
||
npm run dev # http://localhost:5173, Proxy für /api und /health auf 127.0.0.1:8000
|
||
```
|
||
|
||
Ein anderes Backend erreicht der Proxy über `VITE_API_PROXY`. Über HTTP heißt das Session-Cookie `jinkendo-session`. Die Kennzeichnung „Entwicklungsumgebung“ erscheint im Vite-Server automatisch, im Image über `VITE_TSUMUGU_ENV=development`.
|
||
|
||
Produktionsbuild: `npm run build`. Für Development-Images ergänzt `mark-environment.mjs` danach Titel, Manifest und Farbe.
|
||
|
||
## Tests
|
||
|
||
### Backend
|
||
|
||
Die Suite läuft gegen echtes PostgreSQL. Sie verweigert jede Datenbank, deren Name nicht auf `_test` endet, sowie `tsumugu`, `tsumugu_dev`, `postgres` und die Templates. Vor und nach jedem Test werden alle Tabellen geleert.
|
||
|
||
```bash
|
||
cd backend
|
||
createdb tsumugu_local_test
|
||
export DB_NAME=tsumugu_local_test DB_USER=… DB_PASSWORD=… DB_HOST=localhost
|
||
python -m pytest tests -ra --basetemp=.pytest-tmp
|
||
```
|
||
|
||
- `conftest.py` setzt `TSUMUGU_ENV=development`, `ALLOWED_ORIGINS=http://testserver`, `SEED_DEMO=false` und ein temporäres `MEDIA_ROOT`.
|
||
- Unter Windows kann das Standard-Temp-Verzeichnis von pytest gesperrt sein. `--basetemp=.pytest-tmp` umgeht das; der Ordner gehört nicht ins Repository.
|
||
- Zwei Läufe dürfen nicht gleichzeitig dieselbe Testdatenbank verwenden.
|
||
- Paperless und IMAP werden in den Tests durch lokale Attrappen ersetzt. Es entsteht kein Netzzugriff.
|
||
|
||
### Frontend
|
||
|
||
```bash
|
||
cd frontend
|
||
node --test src/list-meta.test.mjs
|
||
```
|
||
|
||
Weitere Frontend-Tests gibt es nicht. Ein `npm test`-Skript ist nicht registriert.
|
||
|
||
### In CI
|
||
|
||
`.gitea/workflows/test.yml` erzeugt auf der Dev-Postgres die Datenbank `tsumugu_test` neu und führt die Suite im Backend-Image aus. Danach folgen ein lesender Health-Smoke der laufenden Dev-App und ein Frontend-Build. Bekannte Schwächen: [Review 07](review/07_TESTS_UND_CI.md).
|
||
|
||
## Neue Migration
|
||
|
||
1. Datei `backend/migrations/YYYYMMDDTHHMMSSZ_kurzname.sql` anlegen, Zeitstempel in UTC, lexikalisch nach der letzten.
|
||
2. Keine eigene Transaktionssteuerung in der Datei; der Runner kapselt jede Datei.
|
||
3. Angewandte Dateien nie ändern: Die Prüfsumme im Ledger verhindert danach den Start.
|
||
4. [DATENMODELL_IST.md](architecture/DATENMODELL_IST.md) nachziehen.
|
||
|
||
## Neue Route
|
||
|
||
1. Route in `api/routes.py`, `api/sources.py` oder `api/export.py` mit `Depends(get_principal)` und `Depends(get_conn)` anlegen.
|
||
2. Rechte über die Funktionen in `access/policy.py` prüfen, nie nur im Frontend.
|
||
3. Änderung samt `audit(...)` in derselben Verbindung.
|
||
4. [API_REFERENZ.md](architecture/API_REFERENZ.md) nachziehen.
|