Home

openschichtplaner5-api — Wiki

openschichtplaner5-api v1.2.0 ist die REST-Service-Schicht von OpenSchichtplaner5: ein pip-installierbares FastAPI-Paket (Importname sp5api), das Schichtplanungsdaten aus den originalen Schichtplaner5-FoxPro-.DBF-Dateien — oder dem SQLite/PostgreSQL-Mirror der Bibliothek — als HTTP-API bereitstellt.

Alle Soll-/Ist-/Bedarfszahlen werden von der Berechnungsfassade der Bibliothek libopenschichtplaner5 (sp5lib, ab Version 1.7.0) geliefert — die API rechnet nicht selbst.

💡 Hinweis zu den Namen: Das PyPI-Paket heißt openschichtplaner5-api, das importierbare Python-Paket sp5api (analog zu libopenschichtplaner5 → sp5lib).

---

Funktionsumfang (v1.2.0)

Bereich	Inhalt
🔐 Auth	Login gegen die SP5-Benutzertabelle, JWT-Sessions, TOTP-2FA mit Backup-Codes, Rollen Leser/Planer/Admin + granulare Schreibrechte → Authentifizierung-und-Rechte
📅 Dienstplan	Monats-/Wochen-/Tages-/Jahresansichten, Schreiben mit Konflikt- und Restriktionsprüfung, Bulk-Operationen, Wochen-Templates, Schichttausch, Schichtzyklen, Einsatzplan
🏖️ Abwesenheiten	Anträge inkl. Self-Service und Genehmigungsworkflow, Urlaubskonto, Urlaubssperren, Stichtags-Verfall, Jahresabschluss
📊 Reports & Exporte	Statistiken (auch über freie Auswertungszeiträume), Personaltabelle, Zeitkonto, CSV/HTML/XLSX-Exporte, PDF-Monatsabschluss, zeitgesteuerte Berichte per E-Mail → Berichte-und-Exporte
🔗 Integrationen	SSE-Echtzeit-Events, In-App-Notifications + E-Mail, iCal-Feeds (webcal), signierte Webhooks
⚙️ Betrieb	Health-/Metrics-Endpoints, strukturiertes JSON-Logging, Rate-Limiting, Auto-Backup, DBF-Auto-Migration, API-Versionierung (/api/v1) → Installation-und-Betrieb

Insgesamt stellt die API 313 Routen unter /api bereit — die komplette Übersicht steht in der Endpunkt-Referenz.

---

🚀 Schnellstart

Variante 1: PyPI

pip install openschichtplaner5-api

SP5_DB_PATH=/pfad/zu/SP5/Daten python -m uvicorn sp5api.main:app --host 0.0.0.0 --port 8000

Variante 2: Docker (Standalone)

docker build -t openschichtplaner5-api .

echo "SECRET_KEY=$(openssl rand -hex 32)" > .env
docker run -d --name sp5-api -p 8000:8000 \
  -v /pfad/zu/SP5/Daten:/app/data \
  --env-file .env \
  openschichtplaner5-api

curl http://localhost:8000/api/health
# → {"status":"healthy", ..., "version":"1.2.0", ...}

Details (Docker Compose, Volumes, Health-Checks): Installation-und-Betrieb.

Interaktive API-Dokumentation

Eine laufende Instanz liefert Swagger UI unter /api/v1/docs (ReDoc: /api/v1/redoc, OpenAPI-Schema: /api/v1/openapi.json) — erreichbar mit angemeldeter Session bzw. Token.

---

📦 Versionsstand

Komponente	Version
openschichtplaner5-api (dieses Paket)	1.2.0
benötigte Bibliothek libopenschichtplaner5[postgres]	≥ 1.7.0
Hauptanwendung OpenSchichtplaner5	1.2.0 (nutzt diese API)
Python	≥ 3.12

Alle Änderungen: CHANGELOG.

---

📚 Wiki-Seiten

• Installation-und-Betrieb — PyPI, Docker, Compose, Health & Metrics
• Endpunkt-Referenz — alle Routen-Familien im Überblick
• Authentifizierung-und-Rechte — Login, JWT, 2FA, Rollen & granulare Rechte
• Konfiguration — Environment-Referenz
• Berichte-und-Exporte — Exporte, Formate, Scheduled Reports
• Entwicklung — Setup, Tests, lokale Bibliotheks-Entwicklung

🔗 Verwandte Projekte

• Hauptanwendung: openschichtplaner5 · App-Wiki
• Bibliothek: libopenschichtplaner5 · Lib-Wiki
• Architektur-Notizen: docs/architecture.md