Files
tsumugu/docs/ENTWICKLUNG_UND_TESTS.md
LarsandCursor d6b70d8f92
Deploy Development / deploy (push) Successful in 28s
Test Suite / pytest-backend (push) Failing after 2m18s
Test Suite / smoke-dev (push) Successful in 0s
Test Suite / frontend-build (push) Successful in 10s
Schließe die Connector-Kapselung ab, damit Paperless, IMAP und weitere Quellen über dieselbe Anbindung laufen.
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-19 15:00:50 +02:00

98 lines
4.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.