Verleih Management System für das Analgenreferat der Stuve
Find a file
Niklas Remmers 8a17d88c4d Reiter per Wischen wechseln (Handy, Tablet)
komponenten.js erkennt eine waagerechte Wischgeste und wählt den nächsten bzw.
vorherigen Reiter – für jede Reiterleiste, Link-Reiter wie role="tablist".
Nicht in Feldern, auf der Unterschriftfläche, in waagerecht scrollenden
Bereichen oder in Dialogen ohne die Leiste. Der Komponenten-Test erlaubt
Touch-Handler nur dort.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 23:17:47 +01:00
assets initialize 2026-07-27 09:23:42 +02:00
migrations Material per ID: Bestand, Cases, Bundles und Leihpositionen 2026-11-04 21:29:34 +01:00
ops Datenbank-Migrationen mit Flyway versionieren 2026-11-04 21:29:34 +01:00
static Reiter per Wischen wechseln (Handy, Tablet) 2026-11-04 23:17:47 +01:00
templates Abhaken: ein Case nimmt seinen Inhalt mit 2026-11-04 22:41:27 +01:00
tests Reiter per Wischen wechseln (Handy, Tablet) 2026-11-04 23:17:47 +01:00
vms Leihanfragen: „Ausgabe abhaken“ bei allen angenommenen Vorgängen 2026-11-04 22:41:27 +01:00
.dockerignore initialize 2026-07-27 09:23:42 +02:00
.gitattributes initialize 2026-07-27 09:23:42 +02:00
.gitignore change to nginx template 2026-07-30 13:45:21 +02:00
pyproject.toml Datenbank-Migrationen mit Flyway versionieren 2026-11-04 21:29:34 +01:00
README.md Merge remote-tracking branch 'origin/main' into feat/anfrageseite 2026-11-04 21:34:26 +01:00
requirements-dev.txt Kanboard-Anbindung und Reconcile-Scheduler entfernen 2026-10-20 21:17:32 +02:00
requirements.txt Abhängigkeiten auf getestete Versionen festlegen 2026-11-04 22:12:37 +01:00

VMS — Verleih-Management-System

Flask-Anwendung zur Verwaltung von Materialverleih: erzeugt Leihverträge, Rechnungen und Umbuchungen aus versionierten ODT-Vorlagen (Export als PDF), verwaltet Inventar, importiert Leihanfragen per E-Mail und nimmt Anfragen über eine öffentliche Anfrageseite entgegen. Mit Nutzer-Authentifizierung, verschlüsselter Secret-Verwaltung (KMS) und PostgreSQL-Backend.


Inhalt


Funktionsumfang

Bereich Beschreibung
Dokumente Leihvertrag, Rechnung und Umbuchung aus ODT-Vorlagen füllen und als PDF exportieren (LibreOffice im Headless-Modus). Vorlagen werden versioniert im template_store gehalten.
Inventar CRUD für Artikel, Bundles und Lagerorte; Tags für die Materialauswahl.
Öffentliche Anfrageseite /request ohne Login: Gegenstände wählen, Verfügbarkeit im Monatskalender sehen (ohne Angaben zu fremden Veranstaltungen) und eine Leihanfrage stellen; sie landet unter „Offene Anfragen“. Inventar ist einmalig oder mehrfach vorhanden; einmalige Gegenstände können nicht doppelt verliehen werden (docs/specs/oeffentliche-anfrage.md).
Rechnungen Fortlaufende, eindeutige Rechnungs-/Umbuchungsnummern (DB-seitig über einen Unique-Index abgesichert).
Nutzerverwaltung Login (bcrypt-Hashes), Einladungs-Flow, Rate-Limiting, CSRF-Schutz.

Technologie-Stack

  • Backend: Python 3.12, Flask 3, SQLAlchemy 2, Flask-Login, Flask-WTF, Flask-Limiter
  • Datenbank: PostgreSQL (psycopg2)
  • Dokumente: ODT-Vorlagen + LibreOffice (libreoffice-writer) für die PDF-Konvertierung
  • Secrets: eigenes KMS-Modul (Fernet-verschlüsselte secrets.enc, Master-Key auf der Platte)
  • Server: Gunicorn hinter Nginx
  • Tests: pytest, pytest-cov, pytest-mock, Testcontainers (ephemeres PostgreSQL), freezegun

Projektstruktur

vms/                     Anwendungspaket (importierbar als vms.*)
  app.py                 Flask-Wiring, Blueprint-Registrierung, Top-Level-Routes
                         (/, /health, /api/generate, /api/calendar/events)
  auth.py                Nutzer, Login, Einladungen, Rate-Limiter (querschnittlich)
  routes/                je ein Flask-Blueprint pro Datei; URLs englisch (docs/specs/englische-urls.md)
    inventory.py           Inventar-, Bundle- und Lagerort-CRUD
    invoice.py             Rechnung / Umbuchung erzeugen & versenden
    verleih.py             Verleih: Lagerorte, Codes (/lending, /api/lending)
    email.py               Anfragen/Vorgänge intern (/requests): bearbeiten, annehmen, anlegen
    material.py            Material eines Vorgangs prüfen (/api/material/pruefen)
    anfrage.py             öffentliche Anfrageseite /request (ohne Login)
    umleitungen.py         alte deutsche Adressen → englische (301)
    settings.py            Nutzer- & Systemeinstellungen
    templates.py           Upload/Verwaltung der ODT-Dokumentvorlagen
  domain/                Kern-Domäne, ohne Web-Abhängigkeit
    models.py              SQLAlchemy-Modelle, Datums-Helfer, laufende Nummern
    database.py            Engine-/Session-Verwaltung (lazy, per Worker)
    material.py            Cases, Bestand, Bundles, Vertragstext (rein)
    materialverfuegbarkeit.py  Verfügbarkeit mit Mengen, Cases und Entnahmen (rein)
    materialdaten.py       lädt Lager und Positionen dafür, speichert Positionen
    positionen.py          Positionen aus dem Request prüfen (rein)
    vertragsdaten.py       Leihvertrag: Material prüfen, speichern, Vertragstext
    anfrage.py             Prüfung öffentlicher Anfragen (rein)
    vorgangsdaten.py       Datenzugriff auf Anfragen/Vorgänge (Tabelle email_candidates)
  infra/                 Infrastruktur / Querschnitt
    kms.py                 Laden/Entschlüsseln der Secrets (Fernet)
    kms_setup.py           CLI zum Provisionieren des Secret-Stores
    security.py            Fernet-Ver-/Entschlüsselung einzelner Werte
    odt_processor.py       Platzhalter-Ersetzung in ODT + ODT→PDF-Konvertierung
    template_store.py      versionierter Store der ODT-Vorlagen

migrations/              Flyway: SQL-Migrationen V<n>__*.sql + flyway.conf
assets/                  gebündelte ODT-Vorlagen (template*.odt) — Fallback/Seed für den Store
templates/               Jinja-HTML-Templates (Frontend)
static/                  JS/CSS/Assets fürs Frontend
tests/                   pytest-Suite + Fixtures (tests/conftest.py)
ops/                     Deployment
  Dockerfile               Multi-Stage-Image (Build-Kontext = Repo-Root)
  build-push.sh            Image bauen & in die Registry pushen (Tag = Git-SHA)
  docker-compose.yml       db + app + nginx + certbot (Server-Artefakt)
  gunicorn.conf.py         Gunicorn-Config (post_fork verwirft den DB-Pool je Worker)
  entrypoint.sh            Container-Bootstrap (KMS, DB-Init, Migrationen, Start)
  deploy/                  systemd-Unit (vms.service), nginx-Configs

Architektur-Prinzipien

  • Dünne Routes, reine Domäne: Blueprints in vms/routes/ orchestrieren nur; die Fachlogik liegt in vms/domain/ und vms/infra/.
  • Absolute Paket-Imports: durchgängig from vms.<subpkg>.<mod> import … (z. B. from vms.domain.models import EmailCandidate, from vms.infra.template_store import load_template). Keine flachen Imports.
  • Blueprints + CSRF: API-Blueprints sind vom Formular-CSRF ausgenommen und nutzen stattdessen den X-CSRFToken-Header (siehe vms/app.py).
  • Lazy DB pro Worker: vms/domain/database.py legt Engine/Session verzögert an; Gunicorn verwirft den Pool nach dem Fork (post_fork in ops/gunicorn.conf.py).
  • Datums-Konvention: Anzeige DD.MM.YYYY, intern ISO — über format_de_date bzw. den Jinja-Filter de_date.

Lokale Entwicklung

Voraussetzungen: Python 3.12, ein laufender Docker-Daemon (für die Tests), sowie libreoffice-writer, falls die PDF-Konvertierung lokal laufen soll.

# 1. Virtuelle Umgebung
python -m venv venv && source venv/bin/activate

# 2. Abhängigkeiten
pip install -r requirements.txt -r requirements-dev.txt

# 3. Konfiguration
cp .env.example .env   # falls vorhanden; sonst .env manuell anlegen (siehe unten)

# 4. PostgreSQL bereitstellen (z. B. per Docker)
docker run --rm -e POSTGRES_USER=admin -e POSTGRES_PASSWORD=admin \
  -e POSTGRES_DB=vms -p 5432:5432 postgres:16-alpine

# 5. Schema anlegen bzw. nachziehen (Flyway, siehe „Datenbank & Migrationen“)
ops/migrate.sh

# 6. App starten (WSGI-Objekt ist vms.app:app)
gunicorn --config ops/gunicorn.conf.py vms.app:app
# oder für die Entwicklung:
FLASK_APP=vms.app flask run

Die App ist danach unter http://localhost:8000 (Gunicorn) bzw. dem Flask-Dev-Port erreichbar; /health liefert {"status": "ok"}.


Konfiguration (Umgebungsvariablen)

Ein Wert wird in dieser Reihenfolge gesucht (vms/app.py:42-44): KMS-Store (secrets.enc, Fernet-verschlüsselt) → Umgebung / .env → eingebauter Default. Ist kein KMS eingerichtet, läuft die App also allein aus der .env.

.env für den Docker-Betrieb

Vollständige Vorlage — liegt auf dem Server neben der docker-compose.yml, lokal im Repo-Root. Alle Werte sind mit den tatsächlichen Defaults gefüllt; ändern musst du nur die mit # ⚠ markierten Zeilen.

# ─── Server ───
# Einzige Stelle, an der die Domain steht: nginx rendert daraus server_name
# und die Zertifikatspfade (ops/deploy/nginx-docker.conf.template).
VMS_DOMAIN=vms.example.org                             # ⚠ Domain dieses Servers

# ─── PostgreSQL (docker-compose baut daraus DATABASE_URL) ───
POSTGRES_USER=admin
POSTGRES_PASSWORD=bitte-ersetzen                       # ⚠ langes Zufallswort
POSTGRES_DB=vms

# ─── Flask ───
# SECRET_KEY  nicht setzen: der Container erzeugt ihn beim ersten Start und
#             legt ihn im kms_data-Volume ab. Eine leere Zeile "SECRET_KEY="
#             wäre schlimmer als gar keine — sie ergäbe einen leeren Schlüssel.
FLASK_ENV=production

# ─── Vorbelegung der Einstellungsseite (KEINE Zugangsdaten) ───
# Füllt nur die leeren Formularfelder vor; Benutzername und Passwort trägt
# jeder Nutzer selbst im Konto ein.
SMTP_SERVER=mail.uni-ulm.de
SMTP_PORT=587

# ─── Image & Compose ───
VMS_IMAGE=git.stuve.uni-ulm.de/hru/vms
VMS_TAG=latest                                         # oder ein Git-SHA für Rollback

Es gibt keine SMTP-Zugangsdaten in der .env. E-Mails werden ausschließlich mit den Zugangsdaten des angemeldeten Nutzers verschickt, die verschlüsselt in der Datenbank liegen und auf der Einstellungsseite gepflegt werden (vms/infra/mailer.py). Ist dort nichts hinterlegt, wird nicht versendet — die Antwort nennt dann die Einstellungen als Abhilfe, statt still auf einen Systemabsender auszuweichen. Absender ist immer der SMTP-Benutzer des Kontos.

COMPOSE_PROJECT_NAME gehört nicht hierher — der Projektname steht als name: ops in der Compose-Datei. Nur wenn ein bestehender Stack andere Volume-Präfixe als ops_ hat, setzt du ihn hier zusätzlich.

Die folgenden Variablen setzt ops/docker-compose.yml bereits selbst; in der .env hätten sie keine Wirkung (environment: sticht env_file:): DATABASE_URL, FLASK_ENV, KMS_MASTER_KEY_PATH, KMS_SECRETS_PATH, GUNICORN_BIND, GUNICORN_WORKERS, GUNICORN_ACCESS_LOG, GUNICORN_ERROR_LOG.

Zusätzlich ohne Docker (bare metal, vms.service)

DATABASE_URL=postgresql://admin:passwort@localhost:5432/vms
KMS_MASTER_KEY_PATH=/etc/vms/master.key
KMS_SECRETS_PATH=/etc/vms/secrets.enc
GUNICORN_BIND=127.0.0.1:8000
# GUNICORN_WORKERS=2                                   ohne Angabe: CPU*2+1.
#             Nicht leer setzen — int("") lässt Gunicorn beim Start abstürzen.
GUNICORN_ACCESS_LOG=/var/log/vms/access.log
GUNICORN_ERROR_LOG=/var/log/vms/error.log
GUNICORN_LOG_LEVEL=info
SQL_ECHO=false                                         # true loggt jedes SQL-Statement
STATIC_EXPORT_DIR=/srv/static                          # Ziel des Static-Exports

Bedeutung im Einzelnen

Variable Zweck Default
VMS_DOMAIN Domain des Servers; nginx setzt daraus server_name und die Let's-Encrypt-Pfade – (Pflicht, Compose bricht sonst ab)
POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB Zugang des db-Containers; Compose setzt daraus DATABASE_URL –
DATABASE_URL PostgreSQL-Verbindung postgresql://admin:admin@db:5432/vms
SECRET_KEY Flask-Session-Schlüssel im Container erzeugt & persistiert
FLASK_ENV production schaltet Secure-Cookies scharf –
SMTP_SERVER / SMTP_PORT Vorbelegung der SMTP-Felder der Einstellungsseite – / 587
KMS_MASTER_KEY_PATH Pfad zum KMS-Master-Key /etc/vms/master.key
KMS_SECRETS_PATH Pfad zur secrets.enc Repo-Root; im Container /etc/vms/secrets.enc
STATIC_EXPORT_DIR Ziel des Static-Exports für Nginx /srv/static
SQL_ECHO SQLAlchemy-SQL-Logging false
GUNICORN_BIND / GUNICORN_WORKERS Bind-Adresse / Worker-Zahl 127.0.0.1:8000 / CPU*2+1
GUNICORN_ACCESS_LOG / GUNICORN_ERROR_LOG / GUNICORN_LOG_LEVEL Logging /var/log/vms/* / info
VMS_IMAGE / VMS_TAG Image und Tag für Compose git.stuve.uni-ulm.de/hru/vms / latest

Datenbank & Migrationen

Das Schema pflegt Flyway (docs/specs/datenbank-migrationen.md). Jede Änderung ist ein SQL-Skript in migrations/, nummeriert und unveränderlich, sobald es irgendwo gelaufen ist:

Skript Inhalt
V1__ausgangsstand_main.sql Schema von main vor dem Redesign
V2 – V4 Daten von früher: Datumsangaben als ISO, invoiced nachtragen, eindeutige Rechnungsnummer
V5 Anfrageseite; Kanboard und Mail-Import entfallen
V6 – V11 Geändert am/von, Code-Link-Versand, Benutzer löschen behält Anfragen, Mail-Texte, Rechnungsdokumente, Passwort-Link
V12 Altspalten email_provider/auth_type gelöscht
V13 Material per ID: Bestand, Cases, Positionen, Entnahmen (Übernahme aus den Namen)
V14 tags und mehrfach gelöscht
  • Server: Der Dienst migrate (ops/docker-compose.yml, Image …/vms-migrations) läuft bei jedem docker compose up vor der App und führt nur aus, was fehlt. Scheitert er, startet die App nicht; die Meldung steht in docker compose logs migrate.

  • Lokal: ops/migrate.sh (braucht Docker, nimmt DATABASE_URL aus der .env):

    ops/migrate.sh                    # migrieren
    ops/migrate.sh info               # was ist gelaufen, was steht aus
    DB=vms_preview ops/migrate.sh     # andere Datenbank auf demselben Server
    
  • Bestehende Datenbanken (von vor Flyway) hängt Flyway bei V1 ein und führt V2 ff. aus. Alle Skripte sind so geschrieben, dass sie auch dort laufen, wo die früheren Python-Migrationen schon Teile erledigt haben.

  • Neue Änderung: nächstes V<n>__beschreibung.sql anlegen und das Modell in vms/domain/models.py anpassen. tests/test_migrationen.py prüft, dass beide genau dasselbe Schema ergeben. Die App legt selbst keine Tabellen mehr an.

  • V4 bricht ab, wenn eine Rechnungsnummer doppelt vergeben ist, und nennt die Vorgänge. Erst fachlich auflösen (einen umnummerieren), dann erneut starten.


Tests

Die Suite nutzt einen PostgreSQL-Testcontainer — ein laufender Docker-Daemon ist Voraussetzung. Das Schema legt Flyway mit migrations/ an, wie in Produktion. Die Fixtures leben in tests/conftest.py.

pytest                     # volle Suite mit Coverage (term + xml + html)
pytest -m unit             # nur reine Logik, ohne DB/App-Context
pytest -m "not slow"       # schnelle Feedback-Schleife
pytest tests/test_app.py   # einzelne Datei

Marker (siehe pyproject.toml): unit, integration, route, slow. Coverage-Reports landen in coverage.xml (maschinell) und htmlcov/ (Review). pythonpath = ["."] macht das vms-Paket im Testlauf importierbar.


Deployment

Der Server braucht kein Repo-Checkout. Das App-Image wird auf dem Entwicklungsrechner gebaut und in die Forgejo-Registry gepusht; auf dem Server liegen nur drei Dateien nebeneinander (z. B. in /opt/vms):

Datei Herkunft
docker-compose.yml ops/docker-compose.yml
nginx-docker.conf.template ops/deploy/nginx-docker.conf.template
.env serverspezifisch, nie im Repo

db, nginx und certbot sind unveränderte Upstream-Images — nur app und migrate (…/vms-migrations, Flyway mit den SQL-Skripten) kommen aus der eigenen Registry, beide mit demselben Tag.

Serverspezifisch ist allein die .env. Die beiden anderen Dateien werden unverändert aus dem Repo kopiert: Die Domain steht als VMS_DOMAIN in der .env, und das nginx-Image ersetzt sie beim Start in nginx-docker.conf.template (server_name und beide Zertifikatspfade) nach /etc/nginx/conf.d/default.conf. NGINX_ENVSUBST_FILTER: "^VMS_" sorgt dafür, dass dabei nur diese Variable ersetzt wird und nginx-eigene wie $host stehen bleiben. Eine neue Domain heißt also: VMS_DOMAIN ändern, Zertifikat ziehen, docker compose up -d nginx.

# Zertifikat für eine neue Domain, bevor nginx sie erwartet
docker compose run --rm --entrypoint certbot certbot certonly --webroot \
    -w /var/www/certbot -d "$VMS_DOMAIN" --agree-tos -m <mail> --no-eff-email

Bauen & Ausrollen

# Entwicklungsrechner (einmalig: docker login git.stuve.uni-ulm.de,
# Token-Scope write:package)
./ops/build-push.sh          # taggt mit dem aktuellen Git-SHA + latest

# Server
cd /opt/vms
VMS_TAG=<sha> docker compose pull app migrate && VMS_TAG=<sha> docker compose up -d app

Steht VMS_TAG in der .env, genügt docker compose up -d app (migrate läuft als Abhängigkeit mit). Rollback ist derselbe Befehl mit dem vorherigen SHA – aber nur innerhalb derselben Schema-Version: Flyway nimmt nichts zurück, ein älteres Image läuft dann gegen das neuere Schema. Vor einem Update mit neuer Migration ein Backup ziehen (docker compose exec db pg_dump …). Der Build-Kontext ist das Repo-Root, weil die Images vms/, assets/, templates/, static/ bzw. migrations/ kopieren.

Das Paket ist öffentlich lesbar — der Server braucht kein docker login. Zugriffsrechte hängen in Forgejo an der Sichtbarkeit des Paket-Besitzers, nicht am Repository; das Verknüpfen eines Pakets mit einem Repo ist rein kosmetisch. Fürs Pushen ist die Anmeldung weiterhin nötig.

Zwei Fallstricke

  • Der Projektname bestimmt die Volume-Präfixe (ops_pgdata, ops_kms_data). Er steht als name: ops in der Compose-Datei selbst, damit er nicht mehr vom Verzeichnisnamen abhängt — ein anderer Name legt leere Volumes an, die Datenbank wirkt dann leer. COMPOSE_PROJECT_NAME in der .env sticht ihn weiterhin; nötig ist der Eintrag nicht.
  • secrets.enc gehört ins kms_data-Volume (KMS_SECRETS_PATH), nicht ins Container-Dateisystem: Beim Image-Update wird der Container neu erstellt.

Container-Bootstrap (ops/entrypoint.sh)

  1. KMS-Master-Key erzeugen (falls nicht vorhanden)
  2. Flask SECRET_KEY erzeugen und persistieren
  3. Secrets aus den Umgebungsvariablen nach KMS_SECRETS_PATH verschlüsseln (nur, wenn die Datei fehlt)
  4. auf die Datenbank warten (das Schema hat vorher der Dienst migrate nachgezogen)
  5. Static-Assets nach /srv/static exportieren — von dort liefert nginx /static/ aus
  6. gunicorn --config ops/gunicorn.conf.py vms.app:app starten

Bare-Metal (systemd): vor jedem Start bzw. Update ops/migrate.sh ausführen (oder eine lokale Flyway-CLI mit migrations/flyway.conf), dann ops/deploy/vms.service nach /etc/systemd/system/ kopieren, aktivieren und starten. Der Dienst startet aus dem Checkout-Verzeichnis gunicorn --config ops/gunicorn.conf.py vms.app:app.

.dockerignore bleibt bewusst im Repo-Root — Docker wertet die Datei relativ zum Build-Kontext aus, nicht relativ zum Dockerfile.

ops/docker-compose.yml ist ein Server-Artefakt: env_file: .env und der nginx-Mount ./nginx-docker.conf.template sind relativ zur Compose-Datei aufgelöst. Für einen lokalen Stack-Test müssen .env und deploy/nginx-docker.conf.template also nach ops/ kopiert werden; beide Kopien sind in .gitignore eingetragen, damit build-push.sh weiterhin einen sauberen Worktree sieht. Der normale Dev-Pfad (venv + flask run, siehe oben) ist davon nicht betroffen.


Sicherheit

  • Secret-Management: produktive Secrets liegen Fernet-verschlüsselt in secrets.enc; der Master-Key liegt getrennt (KMS_MASTER_KEY_PATH). Ohne KMS fällt die App für die Entwicklung auf .env zurück.
  • Passwörter: bcrypt-Hashes (vms/auth.py).
  • Web-Härtung: CSRF-Schutz (Flask-WTF), Rate-Limiting (Flask-Limiter), Secure-/HttpOnly-/SameSite-Cookies in Produktion, ProxyFix hinter Nginx.
  • Nie eingecheckt: .env, secrets.enc, *.key, kms_local/ (siehe .gitignore).