Zeitschreibung
⏱️ SPL TimeTrack (Zeitschreibung)
Überblick
SPL TimeTrack ist eine webbasierte Zeiterfassungs- und Dispositionslösung. Die Anwendung besteht aus:
- Frontend: React + TypeScript (Vite)
- Backend: FastAPI (Python)
- Datenbank: PostgreSQL
- Authentifizierung: JWT + Refresh Tokens
- Besonderheiten: GPS-basierte Zeiterfassung, Offline-Fähigkeit, Genehmigungsprozesse, Kostenstellen-/Kostenträgerverwaltung, PWA-Unterstützung, Push-Benachrichtigungen
Architektur
flowchart TD
FE["Frontend
React / Vite"] --> BE["FastAPI Backend"]
BE --> DB[("PostgreSQL")]
Technologiestack
Frontend: React · TypeScript · React Router · TanStack Query · ShadCN UI · PWA-Unterstützung · IndexedDB (Offline-Betrieb)
Backend: FastAPI · SQLAlchemy · PostgreSQL 16 · JWT Authentication · bcrypt Passwort-Hashing · Web Push Notifications
Hauptfunktionen
1. Zeiterfassung
Start/Stopp: Mitarbeiter können Arbeitszeiten starten und beenden. Erfasst werden: Startzeit, Endzeit, Beschreibung, GPS-Koordinaten, Kostenstelle, Kostenträger.
Laufende Einträge: Die Anwendung erkennt aktive Arbeitszeiten, offene Einträge und fehlende Tagesabschlüsse.
2. GPS-Tracking
Funktionen: GPS-Pflicht beim Buchen, Standortprüfung, GPS-Protokollierung, Kartenansicht, Standortwechsel-Erkennung.
Komponenten: GpsGate, GpsMiniMap, EntryGpsDialog, MultiEntryGpsDialog, GpsErrorAlert.
3. Kostenstellen & Kostenträger
Administratoren verwalten Kostenstellen, Kostenträger und Zuordnungen. Bei jeder Zeiterfassung kann ein Mitarbeiter Kostenstelle und Kostenträger auswählen sowie eine Beschreibung hinterlegen.
4. Genehmigungsworkflow
Rollen: Mitarbeiter, Manager, Administrator.
flowchart LR
A["Mitarbeiter erfasst Zeiten"] --> B["Eintrag erhält Status"]
B --> C["Verantwortlicher prüft"]
C -->|"Genehmigung"| D["Freigegeben"]
C -->|"Ablehnung"| E["Abgelehnt
(Grund gespeichert)"]
Funktionen: offene Genehmigungen anzeigen, Ablehnungsgründe speichern, Historie nachvollziehen.
5. Historie & Auswertungen
Historie: Kalenderansicht, Heatmap-Darstellung, Tagesübersicht, Zeitverlauf.
Statistiken: Backend-Endpunkte liefern Benutzerzusammenfassungen, Arbeitszeitübersichten und Genehmigungsstatus.
6. Offline-Betrieb
Die Anwendung funktioniert auch ohne Internet: lokale Speicherung, Warteschlange für Änderungen, automatische Synchronisation (IndexedDB, Offline Queue, Statusüberwachung).
7. PWA (Progressive Web App)
Installierbar auf Smartphones, offline nutzbar, Push-Benachrichtigungen. Komponenten: InstallBanner, InstallPage, PwaRouteGuard.
8. Push-Benachrichtigungen
Unterstützt Browser Push, Erinnerungen und Genehmigungsanfragen. Backend verwendet VAPID-Schlüssel und die Web Push API.
Benutzerverwaltung
Administrationsbereiche:
| Bereich | Pfad |
|---|---|
| Benutzer (Mitarbeiter, Rollen, Berechtigungen) | /admin/users |
| Kostenstellen | /admin/cost-centers |
| Kostenträger (≈ Sales Orders) | /admin/cost-objects |
| Firmenstandorte | /admin/company-location |
| Buchungsarten | /admin/entry-types |
Tätigkeitsbeschreibungen bestehen für Kostenstellen und Kostenträger getrennt. Es gibt zwei Tabs: (1) Anlegen und Löschen, (2) pro Kostenstelle auswählen, welche Tätigkeiten im Dropdown verfügbar sind.
Sicherheit
Authentifizierung
- Login: /auth/sign-in
- Session: JWT-basiert mit Access- und Refresh-Token
- Passwortschutz: bcrypt-Hashing, Passwortwechsel erzwingbar, Passwortänderungs-Guard
Datenschutz
Mitarbeiter sehen ausschließlich eigene Zeiteinträge und Daten; Manager/Admins erhalten erweiterte Rechte. Schutzmechanismen: SQL-Injection-Schutz, CORS-Whitelist, Token-Widerruf, Rollenprüfung.
KI-Funktionen
Das Backend unterstützt einen KI-gestützten Zeitsplit (/functions/split-time-entry). Er nutzt einen OPENAI_API_KEY und teilt einen laufenden Zeiteintrag automatisch auf mehrere Tätigkeiten oder Projekte auf.
Wichtige Seiten
| Seite | Zweck |
|---|---|
| / | Dashboard |
| /auth | Login |
| /history | Historie |
| /approvals | Genehmigungen |
| /profile | Benutzerprofil |
| /change-password | Passwortänderung |
| /help | Hilfe & Doku |
| /install | App-Installation |
Backend-API
Auth: POST /auth/sign-in · POST /auth/sign-up · POST /auth/sign-out · GET /auth/session · GET /auth/user · PATCH /auth/user
Daten: POST /data/select · POST /data/insert · PATCH /data/update · DELETE /data/delete
Funktionen: Benutzerstatistiken, Genehmigungen, Rollenverwaltung, Zeitsplit und weitere Business-Funktionen.
Besondere Geschäftslogik: Mitternachtssplit
Das Backend teilt Zeiteinträge, die über Mitternacht laufen, automatisch auf. Beispiel: 22:00 - 02:00 wird getrennt in 22:00 - 23:59 und 00:00 - 02:00. Dadurch bleiben Tagesauswertungen korrekt.
Server
Das Projekt liegt unter /mnt/data/spl_time_secure auf dem KI-Server. Es läuft mit Docker Compose (Services: backend, frontend, db).
Erreichbar unter http://192.168.208.2:8100 — mit VPN und im SPL-TELE-Netzwerk.