Entwicklung

Entwicklung

Anleitung für die Arbeit am Quellcode von openschichtplaner5-api. Repository: https://github.com/mschabhuettl/openschichtplaner5-api

---

Setup

git clone https://github.com/mschabhuettl/openschichtplaner5-api.git
cd openschichtplaner5-api

python3 -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"

Voraussetzung: Python ≥ 3.12 (das Paket nutzt moderne Generics-Syntax; ältere Versionen scheitern beim Import).

Gegen die lokale Bibliothek entwickeln

Standardmäßig kommt libopenschichtplaner5[postgres]>=1.7.0 von PyPI. Wer Bibliothek und API zusammen entwickelt, legt die Repos als Geschwister ab und linkt die Bibliothek editierbar:

pip install -e "../libopenschichtplaner5[postgres]"

Entwicklungs-Doku der Bibliothek: Lib-Wiki.

---

Server lokal starten

SP5_DB_PATH=tests/fixtures python -m uvicorn sp5api.main:app --reload

• tests/fixtures/ enthält eine vollständige DBF-Fixture-Datenbank (30 Tabellen) — damit läuft die API ohne echte Schichtplaner5-Daten.
• Ohne Frontend-Build startet die API im API-only-Modus; Swagger UI unter http://localhost:8000/api/v1/docs (Anmeldung erforderlich; alternativ SP5_DEV_MODE=1 setzen und das Token __dev_mode__ verwenden — nur lokal!).
• python sp5api/main.py funktioniert als Dev-Shortcut ebenfalls.

---

Tests

pytest          # komplette Suite
ruff check .    # Linting

• Die Suite (pytest, asyncio_mode = auto) läuft vollständig gegen die eingecheckte Fixture-Datenbank — kein externer Dienst nötig.

• SP5_REAL_DB: Zeigt diese Variable auf ein echtes Schichtplaner5-Datenverzeichnis, laufen die Tests gegen diese Daten statt gegen tests/fixtures/:

  SP5_REAL_DB=/pfad/zu/SP5/Daten pytest

• data/ und api/data/ im Repo-Root sind eingecheckte Laufzeit-State-Seeds (Skills, Wünsche, Notification-Settings) für die Tests — dasselbe Layout, das die Hauptanwendung unter backend/ nutzt, aufgelöst über SP5_BACKEND_DIR (setzt die Test-Konfiguration automatisch auf den Repo-Root).

• CI führt ruff und pytest mit Coverage-Gate (70 %) auf Python 3.12 und 3.13 aus.

---

Projektlayout

Pfad	Inhalt
sp5api/main.py	FastAPI-App: Lifespan (Auto-Migration, Auto-Backup, Cleanup, Report-Scheduler), Middlewares, Health/Metrics, SPA-Serving, Router-Registrierung
sp5api/routers/	26 Domänen-Router (auth, employees, schedule, absences, reports, …)
sp5api/dependencies.py	Logging, JWT, Session-Store, Rollen-/Rechte-Dependencies, Rate-Limiter, DB-Backend-Weiche, Audit-Log
sp5api/schemas.py / sp5api/types.py	Pydantic-Modelle / Typ-Aliase
sp5api/cache.py / sp5api/rate_limit_store.py	TTL-Response-Cache, 429-Event-Log
tests/	Test-Suite + DBF-Fixture-Datenbank (tests/fixtures/)
docs/architecture.md	Architektur-Notizen inkl. vollständigem Routeninventar

Konventionen: ruff (line-length 100, Target py312), eine Routerdatei pro Domäne, Rollen-/Rechteprüfung ausschließlich über die Dependencies (require_auth, require_planer, require_admin, require_write(...), require_addempl).

---

Releases

Tag vX.Y.Z auf main pushen — der Release-Workflow baut sdist + wheel und publiziert via Trusted Publishing (OIDC) nach PyPI (keine gespeicherten Tokens). Versionierung nach SemVer, Änderungen gehören ins CHANGELOG (Keep-a-Changelog-Format).

---

Siehe auch

• Installation-und-Betrieb — Betrieb der gebauten Pakete
• Endpunkt-Referenz — Routen-Übersicht
• App-Wiki — Full-Stack-Entwicklung mit Frontend